Why Skills Matter When You Build an Agent

The reason skills matter is simple: an agent only performs as well as the instructions in front of it, but you cannot put every instruction in front of it at once. Stuff the system prompt with every workflow the agent might ever need and you blow the token budget and confuse the model. Skills fix that. They let you hand the agent deep capability that loads only when a task actually needs it.

I have written about skills in Deep Agents before. This post is the cleaner, framework-focused version: what a skill is, how DeepAgents loads it in three layers, and how to write one that gets activated reliably. It is part four of my series on building with DeepAgents.

What a skill is#

A skill is a directory. At minimum it holds a SKILL.md: a markdown file with YAML frontmatter (name and description) followed by instructions the agent follows when the skill is active. It can also carry supporting files: scripts, reference docs, templates.

skills/
  langgraph-docs/
    SKILL.md
    scripts/
      fetch_docs.py
    references/
      api-patterns.md
      style-guide.md
    assets/
      report-template.md
      schema.json

You point the agent at the top-level skills directory:

import { createDeepAgent, FilesystemBackend } from "deepagents";
 
const backend = new FilesystemBackend({ rootDir: process.cwd() });
 
const agent = await createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  backend,
  skills: ["/skills/"],
});

At startup the agent loads each skill's name and description into the system prompt. When a task matches a description, it reads that skill's full SKILL.md and follows it.

The mechanism: progressive disclosure in three levels#

This is the whole reason skills scale, so it is worth being precise. Skills load in three levels, each adding detail only when the task needs it.

So at startup, the model sees a one-line description of every skill and nothing more. That is cheap. You can configure dozens of skills and pay only for their descriptions until one is actually relevant. When the agent decides a skill fits, it reads the body. When the body points to a reference file, it reads that. Detail arrives exactly when it is needed and not before.

In DeepAgents, the skills middleware handles the first two levels (discovery and read), and the model handles the third (executing instructions and pulling in supporting files). The pattern is the same one that runs through the whole framework: keep the context window as a small working set, keep everything else on the backend until needed. I made that case in the context engineering post.

When to write a skill#

The trigger is repetition. If you find yourself giving the agent similar multi-step instructions more than once, codify them. Next time, the agent already knows the procedure. You can even ask the agent to write the skill for a task you just worked through together.

Skills are a good fit for:

• Step-by-step workflows, like recipes the agent follows
• Domain knowledge, including where to pull information and which tools to use for it
• Procedures with executable code, so the agent runs tested logic instead of regenerating it each time
• Guidelines and guardrails, like "always follow this format" or "always run the tests"

Writing a SKILL.md the agent will actually use#

Most skill failures are activation failures: the agent never reads the skill because the description did not match. A few rules fix the majority of that.

The description is everything. During discovery, the description is the only thing the agent sees for each skill. It has to say both what the skill does and when to use it, with keywords the agent can match against.

# Good: specific about what and when
description: >-
  Extract text and tables from PDF files, fill PDF forms, and merge
  multiple PDFs. Use when working with PDF documents or when the user
  mentions PDFs, forms, or document extraction.
 
# Poor: too vague to match reliably
description: Helps with PDFs.

Keep both layers small. Keep frontmatter tight and the SKILL.md body under about 5,000 tokens (the spec suggests under 500 lines). Frontmatter is paid at startup for every skill; the body is paid only on activation. Small layers mean you can load many skills without crowding the window. When instructions grow, move detail into reference files and link them.

Structure the body as instructions, not prose. Write it for an agent to follow: numbered procedures for multi-step work, decision criteria for choosing between approaches, examples of expected inputs and outputs, and the edge cases the agent should handle or flag.

Manage skill count. Fewer, well-scoped skills beat many overlapping ones. As descriptions start to overlap, the agent's ability to pick the right one degrades and it hesitates or picks wrong. If two skills serve similar purposes, merge them into one with sections.

Here is a compact, well-formed SKILL.md:

---
name: langgraph-docs
description: Use this skill for requests related to LangGraph in order to fetch relevant documentation and provide accurate, up-to-date guidance.
---
 
# langgraph-docs
 
## Instructions
 
### 1. Fetch the documentation index
Use the fetch_url tool to read https://docs.langchain.com/llms.txt
This provides a structured list of all docs with descriptions.
 
### 2. Select relevant documentation
Pick the 2-4 most relevant URLs. Prioritize how-to guides for
implementation questions and concept pages for understanding questions.
 
### 3. Fetch and synthesize
Read the selected pages, then answer. Give a direct answer first,
include minimum necessary context, and link sources rather than
quoting long passages.

Supporting resources: scripts, references, assets#

Beyond SKILL.md, the spec defines three optional directories. DeepAgents does not load any of them at discovery or activation. The agent reads or runs them only when the SKILL.md instructions say to.

scripts/ holds executable code the agent can run: API clients, transforms, validators. Make scripts self-contained, give them clear error messages, and handle edge cases. references/ holds documentation the agent reads on demand: detailed technical reference, format specs, domain guides. Keep each file focused so it costs little when loaded. assets/ holds static files the agent uses but does not read as instructions: templates, images, lookup tables, schemas.

Reference them from SKILL.md with paths relative to the skill root, and say what each file is and when to use it:

For API details, see the reference guide at references/api-patterns.md.
 
To extract tables from a PDF, run scripts/extract.py.

Keep references one level deep. Deeply nested chains force the agent through multiple reads to reach what it needs, which is slow and error-prone.

Skills for subagents#

Skill inheritance has one rule that trips people up. The general-purpose subagent inherits the main agent's skills. Custom subagents do not; you give them their own with the skills parameter.

const researchSubagent = {
  name: "researcher",
  description: "Research assistant with specialized skills",
  systemPrompt: "You are a researcher.",
  tools: [webSearch],
  skills: ["/skills/research/", "/skills/web-search/"],
};

Skill state is fully isolated in both directions. A subagent's loaded skills are invisible to the parent, and the parent's are invisible to the custom subagent. That isolation is a feature: it keeps a specialized subagent's context clean. I cover the delegation side of this in the subagents post.

Skills, memory, and tools: which to reach for#

These three all add capability, and people mix them up. The quick guide:

The line between skills and memory is a spectrum, not a wall. An agent with write access can update its own skills as it works, capturing new procedures over time. In that sense skills act as a form of progressive-disclosure memory: knowledge the agent builds up and retrieves on demand instead of loading on every prompt. More on the memory side in the memory post.

The frontmatter fields#

For reference, the Agent Skills spec defines these:

SKILL.md files must be under 10 MB or they get skipped at load time, but if you are anywhere near that you have bigger structural problems.

The takeaway#

Skills are how you give an agent depth without width: deep capability that stays out of context until a task calls for it. Get the descriptions sharp, keep the bodies small, push detail into reference files, and do not let your skill set sprawl into overlap. Do that and you can hand an agent a large library of capabilities while keeping its context lean enough to reason well.

Next in the series: human-in-the-loop in DeepAgents, how to put a person in front of the actions that should never run unsupervised.