What a skill is
06 — Skills
Skills: packaged, reusable units of knowledge/procedure that an agent loads on demand to do a specific job well — and how to build and manage them.
What a skill is
A skill is a self-contained bundle that teaches an agent how to do a particular kind of task. Where a model’s weights carry general knowledge and the system prompt carries standing instructions, a skill carries domain-specific procedure plus reference material for a narrow job. It’s the difference between “the model knows about git” and “the model knows this repo’s git conventions and will run markdownlint after editing.”
A skill typically combines:
- A trigger / description — when the agent should reach for this skill (matched from the user’s request).
- Procedure — the steps, in order, to accomplish the task.
- Reference material — file locations, templates, commands, conventions, gotchas.
- Boundaries — what the skill is not for, and guardrails (e.g. “never commit secrets”, “get confirmation before X”).
Why skills exist (the context problem)
An agent can’t load everything it might ever need into context — that’s both expensive and degrading (see Context Sizing). Skills solve this with on-demand, just-in-time knowledge: the description list is cheap to keep resident, and the full skill body is loaded only when the task matches. This is the same isolation principle as sub-agents, but applied to knowledge rather than work:
- Sub-agent = delegate execution to a fresh context.
- Skill = inject the right knowledge into the context for this task.
They compose naturally: a sub-agent prompt that references the relevant skill gives the worker both a clean context and the domain procedure it needs.
Anatomy of a good skill
A skill that an agent actually uses well has a few properties:
- One skill per job. “NANDA Docs”, “deploy a llama server”, “rotate a Postgres secret” — not a catch-all. A broad skill is one the agent can’t reliably trigger.
- Self-contained. Everything needed to do the job is in the skill: absolute paths, exact commands, template locations, the conventions. The agent shouldn’t have to guess or ask.
- Prescriptive, not descriptive. Give the exact command and the exact file, not “run the linter somewhere”.
- Guardrails up front. Safety constraints (redact secrets, confirm before committing, don’t hard-wrap prose) belong in the skill so they apply every time the skill is used.
- Stable, small, and versionable. Skills live in the agent’s workspace (often as files in a known directory) and are reviewed like code. When a procedure changes, the skill changes.
Skills vs the things they’re confused with
| Thing | What it is | Relation to a skill |
|---|---|---|
| System prompt | Standing, always-loaded instructions | A skill is loaded on demand; the system prompt is resident. Put cross-cutting rules in the system prompt; task-specific procedure in a skill. |
| Tool (e.g. Open Terminal) | A capability — something the agent can do | A skill is knowledge about how to use capabilities well. A skill frequently references tools (e.g. “run markdownlint-cli2 via the terminal”). |
| Sub-agent | A delegated execution in a fresh context | A skill can be handed to a sub-agent as its brief; the sub-agent provides the clean context, the skill provides the procedure. |
| MCP server | A protocol for exposing tools/data | MCP is how tools are wired in; a skill is what to do with them. |
The clean way to think about it: tools are hands, skills are the manual, sub-agents are the fresh pair of hands.
How an agent uses a skill (the loop)
User request
│ agent scans available skill *descriptions* (cheap, resident)
▼
Match? ──no──► proceed without a skill
│yes
▼
Load the skill *body* into context (procedure + references + guardrails)
│
▼
Follow the procedure, calling tools (terminal, file ops, …) as needed
│ may delegate a step to a sub-agent, passing the skill as its brief
▼
Done — result returned; skill body can be dropped from context
Because only the description list needs to be resident, you can have many skills without paying for their full bodies until one is actually used.
Tips for building skills on a local stack
- Start from a real task. Do the job once by hand, note every command, path, and decision, and codify that. A skill distilled from a real run is far more reliable than one written abstractly.
- Use absolute paths. A skill that says “the repo is at
/home/u/…/NANDAand the template is attemplates/doc.md” removes an entire class of “which file?” failures. - Keep guardrails in the skill, not in your head. If you’ve ever had to remind the model “redact secrets before committing”, that reminder belongs in the skill so it fires automatically.
- Version skills like code. Put them in a git-backed directory, review changes, and keep them current when the underlying procedure changes — a stale skill is worse than no skill, because the agent trusts it.
- Match skill granularity to model. A small worker model benefits most from a very prescriptive skill (exact commands, no judgement); a large model can work from a looser brief. Pair skill detail with the model that will execute it (see Sub-agents).
Related
- Sub-agents — skills as sub-agent briefs
- Open Terminal & Tooling — the tools skills direct
- Context & Quantisation — the context economics that motivate on-demand loading
Source Disclaimer
- AI Generated
- Human Generated
- AI Edited
- Human Edited