Agent Skills
Capability packs loaded on demand
Reusable capability folders that bundle instructions, scripts and resources around a SKILL.md file, which an agent loads into its context only when a task needs them.
You want to teach an agent dozens of procedures: how to fill a PDF form, your company's release-notes format, how migrations are written in this repo. Pile them all into the system prompt and you burn thousands of tokens on every request while the model loses focus on the actual task. Agent Skills solve this with progressive disclosure.
A skill is a folder containing at least a SKILL.md file. The file
starts with YAML frontmatter where name and description are
required, followed by Markdown instructions; the folder may also hold
scripts/, references/ and assets/. The format is specified as an
open standard at agentskills.io, and tools such as Claude Code and
OpenAI Codex read the same format.
Loading happens in three tiers:
1. At startup, only each skill's name and description enter context.
2. When a task matches the description, the model reads the full
SKILL.md.
3. If the instructions point to another file or script, that is read or
executed only when needed.
How it differs from its neighbours: a system prompt is present on every request, while a skill is a single line until invoked. MCP gives the agent new tools and data access; a skill teaches it how to do a job with the tools it already has. Fine-tuning changes model weights; a skill is plain-text knowledge you can roll back by deleting a folder.
Like the recipe binders in a good kitchen. The chef doesn't memorise every recipe; they know the labels on the binder spines ("Sourdough", "Fermented sauces"). When an order comes in, they pull the right binder, read the recipe, and if it says "see the hydration table" they flip to that page. Label = description, recipe = SKILL.md, table = reference file.
A team wants weekly release notes in the same format every time:
heading structure, a breaking-changes section, issue links. Instead of
explaining this to the agent each week, they write a SKILL.md in
.claude/skills/release-notes/ whose description says "use when the
user asks for release notes, a changelog, or a release summary."
When a Claude Code session opens, the skill takes up one line of
context. When someone says "draft release notes for v2.4", the model
picks the skill, reads the instructions, runs scripts/collect.sh from
the folder to gather commits, and produces text that follows the
template. The same folder can also be invoked by hand as /release-notes.
---
name: release-notes
description: Generates release notes from commits since the last
tag. Use when the user asks for release notes, a changelog, or a
release summary.
---
# Generating release notes
1. Run `scripts/collect.sh` to gather commits since the last tag.
2. Group them under: New, Fixed, Breaking change.
3. Add the related issue link to every item.
4. Follow `references/template.md` for formatting.
If there are no breaking changes, omit that heading entirely.release-notes/
├── SKILL.md # required: frontmatter + instructions
├── scripts/
│ └── collect.sh # executed when needed
└── references/
└── template.md # read when needed- Teaching the agent a recurring, well-defined procedure once and for all
- Adding many areas of expertise without bloating the system prompt
- Packaging knowledge with scripts and templates to share across a team (commit it)
- Reusing the same capability across different agent tools (open standard)
- Rules that must apply on every request — those belong in the system prompt or CLAUDE.md/AGENTS.md
- The agent needs to reach a new system — that's a job for an MCP server or a tool
- The rule must be enforced without exception — a skill is a suggestion; use a hook for guarantees
Writing a vague description
The model picks a skill from its description alone. Something like 'helper utilities' never triggers. State what it does and when to use it in the first sentence.
Stuffing everything into SKILL.md
Once a skill is chosen, the whole file enters context. Move long tables and API references into separate files so they're read only when needed — that's the entire point of progressive disclosure.
Installing untrusted skills
Scripts inside a skill run with the agent's permissions, and its instructions steer the model. Read the code before installing someone else's skill; it's the same risk as running an unknown npm package.