An agent skill packages procedural instructions as a directory that an AI agent can load when a task calls for them. A SKILL.md file combines YAML frontmatter—a name and use description—with Markdown instructions; optional resources include references, templates, examples, and scripts. section 3.3.6
pull-request-review/ ├── SKILL.md # frontmatter + instructions ├── references/ # the full review checklist ├── scripts/ # run-lint.sh, check-migrations.sh └── assets/ # PR description template
A pull-request review skill can separate its instructions from a checklist, scripts, and a reusable template. section 3.3.6
Skills use progressive disclosure to limit always-loaded context:
- At rest, the agent receives the skill’s name and description; the description helps it decide whether the skill applies. section 3.3.6
- When a task calls for the skill, its full instructions load. Keep procedures in skills rather than relying on general tool descriptions. section 3.3.6
- A skill can teach how to query live workspace data, but static instructions cannot report what is currently true; MCP-backed queries can fill that gap. section 10.2.5
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 demonstrates a procedure with a stop condition, checklist, finding categories, and a human approval boundary. section 3.3.6





