Reference guide · Agent Skills
11 min read
Updated
SKILL.md: build an Agent Skill that is useful, discoverable, and testable
A complete method for turning a repeated procedure into a skill an agent can discover, execute, and verify.
Direct answer
Create an Agent Skill when you need a procedure to be reusable and discoverable. The directory contains at least SKILL.md: frontmatter with name and description, followed by operational instructions. Add scripts, references, or templates only when they make execution more reliable. Judge a skill by three proofs: it activates for the right requests, stays silent for unrelated ones, and produces a verifiable result.
01
A skill is not merely a longer prompt
A prompt addresses the current situation. A skill formalizes expertise that should be found and applied across multiple tasks. Its name and description let the agent judge relevance before loading the full instructions.
A skill is not a tool either. A tool provides an action — read a file, call an API, run a test. The skill explains when to use those actions, in what order, within which boundaries, and with what proof of success. The agent remains the system that chooses, acts, observes, and decides whether to continue or stop.
- Prompt: a one-off instruction tied to the current conversation.
- Skill: a reusable procedure loaded when a request matches.
- Tool: an operation the agent can call to observe or change a system.
- Agent: the decision loop that uses instructions, skills, and tools.
If a procedure does not need reuse or testing, a clear prompt is probably enough.
02
The minimum anatomy of SKILL.md
The Agent Skills specification requires a directory containing at least SKILL.md. The file begins with YAML frontmatter. name identifies the skill; description states both what it accomplishes and the situations in which it should activate. The Markdown body holds instructions the agent reads after activation.
Keep that file decision-oriented. Put long procedures or detailed knowledge in references/, deterministic operations in scripts/, and reusable templates in assets/. Progressive loading avoids occupying context with resources that do not help the current request.
---
name: interface-qa
description: Audit a web interface after a UI change. Use when a task asks to verify responsive behavior, keyboard access, or visual regressions.
---
# Interface QA
1. Inspect the changed routes and existing test conventions.
2. List the user journeys affected by the change.
3. Run the narrowest relevant automated checks.
4. Record every unverified browser or device gate explicitly.
5. Report evidence, failures, and remaining work separately.03
Write instructions an agent can actually follow
Start with the expected outcome, then describe decisions in the order they occur. An instruction such as “check quality” is too vague. Name the surfaces to inspect, the signals to look for, the commands that are allowed, and the form of the final evidence.
Add exceptions that change the path: a missing file, an unauthenticated environment, an ambiguous result, an unavailable test, or a destructive action. Also say what must not happen. Explicit boundaries keep a useful procedure from becoming blanket authorization.
- Define an observable input and expected result.
- Use action verbs and a clear execution order.
- Separate inspection, modification, validation, and reporting.
- Cover error branches and stopping conditions.
- Reference files relative to the skill root.
04
Treat activation as a boundary-design problem
The description is the primary discovery signal. It should name the capability and the kinds of request that make it relevant. A narrow description misses useful cases; a broad one loads the skill for tasks it cannot handle.
Build two small corpora: requests that should activate the skill and neighboring requests that should not. False negatives reveal missing user language. False positives show where the scope needs sharper wording or where a variant belongs in another skill.
A good description explains the “when” as clearly as the “what.”
05
Test the procedure, not only the format
Frontmatter validation is necessary but insufficient. Run the skill on representative cases, inspect its artifacts, and compare the result with observable criteria. Scripts should have bounded inputs, readable failures, and deterministic behavior whenever possible.
Version the skill together with its examples and tests. When an instruction changes, replay the cases that motivated the old rule. A dependable skill also reports honestly: it separates what was verified, what remains manual, and what is blocked by a missing permission or environment.
- Activation: positive, negative, and ambiguous requests.
- Execution: nominal path, missing data, and tool failure.
- Output: format, completeness, provenance, and success criteria.
- Security: minimal permissions, no secrets in logs, confirmation for destructive actions.
- Regression: replay real cases after every material change.
Keep this
Checklist before sharing an Agent Skill
- 01The name is stable, descriptive, and valid for the target format.
- 02The description says what the skill does and when to use it.
- 03The instructions begin with an observable outcome.
- 04Tools, permissions, boundaries, and stopping conditions are explicit.
- 05Long references and scripts load only when needed.
- 06File paths are relative to the skill root.
- 07Tests cover activation, non-activation, failures, and final output.
- 08The report separates obtained evidence from remaining manual validation.
Primary sources
Technical claims in this guide connect to first-party specifications and documentation.
- Agent Skills specificationAgent Skills · Specification for the directory, SKILL.md, frontmatter, and optional resources.
- Optimizing skill descriptionsAgent Skills · Documentation of the description’s role in discovery and activation.
- Agent Skills overviewAnthropic · Primary documentation for reusable skills, loading, and supporting resources.
Continue