Glossary
What is SKILL.md?
A packaged procedure an agent loads only when the task calls for it.
Updated 2026-09-09
SKILL.md is a markdown file that packages a specific workflow for an agent, loaded on demand rather than kept in context all the time.
The split is worth internalising. AGENTS.md is what the agent always knows. A skill is what it goes and reads when the job is review this pull request, cut a release, or write a database migration. That is why skills scale: you can have fifty of them without paying for fifty of them on every turn.
A skill is a folder. SKILL.md holds frontmatter with a name and a description, then the instructions in the body. The agent sees the description first and uses it to decide whether the skill is relevant, then loads the full body. You can ship helper scripts and reference files in the same folder, which is how skills end up more reliable than a prompt you paste by hand.
Write the body as a procedure, not an essay. Numbered steps, exact commands, and a short checklist at the end beat three paragraphs of context. If a step has a failure mode, say what to do when it fails.
skills/release/SKILL.md
---
name: release
description: Use when cutting a release, tagging a version, or writing release notes.
---
1. Confirm main is green: pnpm test && pnpm tsc --noEmit
2. Bump the version in package.json (semver, no prereleases).
3. Generate notes from commits since the last tag.
4. Tag and push: git tag vX.Y.Z && git push --tags
If tests fail, stop and report which suite broke. Do not tag.Where people get this wrong
- The description is the routing signal. If it does not say when to use the skill, the agent will never reach for it.
- Skills that repeat your always-on rules are pure noise. Only package what is situational.
- One skill per job. A kitchen sink skill called helpers never fires because nothing matches it.