A tool can expose an action without explaining the procedure around it. SKILL.md supplies that missing discipline as reusable, selectively loaded instructions for an AI agent, rather than putting every workflow into rules loaded on every request. section 3.3.6
A skill is a folder containing SKILL.md. Its YAML frontmatter gives the skill a name and a description of when to use it; the Markdown body contains the instructions. The folder can also include reference documents, templates, example outputs, and executable scripts. section 3.3.6
Design the skill for selective loading:
- Make the description specific about the tasks that should trigger the skill. The agent sees the frontmatter when deciding whether to use it. section 3.3.6
- Put the procedure in the body, with supporting detail in the folder. This keeps the full instructions from entering every request’s context. section 3.3.6
- State stop conditions and human responsibilities explicitly when the process requires them. section 3.3.6
The frontmatter still has an ongoing context cost for every installed skill. The stated estimate is roughly 80 tokens per skill; the descriptions must earn that space by helping the agent select the right procedure. section 3.3.6
Listing 3.1 Skills.md
--- name: pull-request-review description: Reviews a pull request before it reaches a human reviewer. Use when asked to review, check, or sanity-check a PR or a branch diff. --- # Pull request review 1. Run scripts/check-migrations.sh. If it exits non-zero, stop and report - do not review further. 2. Walk the diff against references/review-checklist.md. 3. Report findings as blocking, non-blocking, or nitpick. Never approve a PR. A human approves.
This pull-request review skill combines a trigger description with a migration check, a review checklist, and an explicit human-approval boundary. section 3.3.6
Skills can encode engineering methods as well as organization-specific rules. For example, separate skills can load brainstorming, test-driven development, systematic debugging, or code review procedures when the agent recognizes the relevant work. section 3.5.3


