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.
Glossary
Terms explained here
Open a term for a short definition, then continue to its full sourced entry if useful.
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 specification (opens in a new tab)Agent Skills · Specification for the directory, SKILL.md, frontmatter, and optional resources.
- Optimizing skill descriptions (opens in a new tab)Agent Skills · Documentation of the description’s role in discovery and activation.
- Agent Skills overview (opens in a new tab)Anthropic · Primary documentation for reusable skills, loading, and supporting resources.
Continue
Related guides and tools
Understand → Recognize → Choose → Compare
Pack for your agent
Pre-written instruction by SkillCodex — your request is neither sent nor used to adapt this text; no content is generated, and copying executes nothing.
Implement correctly
Apply “SKILL.md: build an Agent Skill that is useful, discoverable, and testable” step by step
# Apply the “SKILL.md: build an Agent Skill that is useful, discoverable, and testable” guide in your agent ## Objective 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. ## Prerequisites - Inspect the repository, documentation, and existing conventions. - Confirm the need matches the guide scope: A complete method for turning a repeated procedure into a skill an agent can discover, execute, and verify. - Preserve the correct decisions already in place. ## Guide steps - 1. A skill is not merely a longer prompt — If a procedure does not need reuse or testing, a clear prompt is probably enough. - 2. 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. - 3. 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. - 4. Treat activation as a boundary-design problem — A good description explains the “when” as clearly as the “what.” - 5. 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. ## Acceptance criteria — Checklist before sharing an Agent Skill - The name is stable, descriptive, and valid for the target format. - The description says what the skill does and when to use it. - The instructions begin with an observable outcome. - Tools, permissions, boundaries, and stopping conditions are explicit. - Long references and scripts load only when needed. - File paths are relative to the skill root. - Tests cover activation, non-activation, failures, and final output. - The report separates obtained evidence from remaining manual validation. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
- Requires · The real project context: repository, documentation, and existing constraints
Why it works
- The steps come from a published, sourced guide, not improvisation.
- The checklist turns advice into verifiable criteria.
- The declared scope keeps the guide within its evidence.
Try next
Anchor the guide in the project
# Anchor the guide in the project ## Objective Turn the applied steps into durable repository conventions. ## Checks - Link each decision made to the guide step that justifies it. - Add the checklist to the relevant reviews. - Record out-of-scope cases for the neighboring guides. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
sha256:c0dd6e65ff33cefb38060e6204111c10641fc12c158ca45aadf2f82d2a97c1fd
Diagnose a problem
Diagnose a “SKILL.md: build an Agent Skill that is useful, discoverable, and testable” guide gap
# Diagnose a failed application of the “SKILL.md: build an Agent Skill that is useful, discoverable, and testable” guide ## Observed symptom [DESCRIBE THE SYMPTOM HERE] ## Observable checks - Replay the steps in order and note the first one that diverges: - 1. A skill is not merely a longer prompt — If a procedure does not need reuse or testing, a clear prompt is probably enough. - 2. 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. - 3. 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. - 4. Treat activation as a boundary-design problem — A good description explains the “when” as clearly as the “what.” - 5. 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. ## Possible causes - A step was skipped or executed out of order. - The actual need falls outside the guide scope. - A checklist criterion was never verified. ## Bounded fixes - Redo only the diverging step and what depends on it. - Document the gap if the guide scope does not cover the need. ## Final verification — Checklist before sharing an Agent Skill - The name is stable, descriptive, and valid for the target format. - The description says what the skill does and when to use it. - The instructions begin with an observable outcome. - Tools, permissions, boundaries, and stopping conditions are explicit. - Long references and scripts load only when needed. - File paths are relative to the skill root. - Tests cover activation, non-activation, failures, and final output. - The report separates obtained evidence from remaining manual validation. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
- Requires · The real project context: repository, documentation, and existing constraints
Why it works
- The diagnosis replays ordered steps instead of searching at random.
- Fixes stay bounded to the first real divergence.
- The checklist serves as a reproducible final verification.
Try next
Prevent the next drift
# Prevent the next drift ## Objective Turn the first diverging step into an explicit project check. ## Checks - Add a focused check on the step that diverged. - Verify the checklist on a second real case. - Document the scope limit you hit. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
sha256:fab0f1ad543e227680475bf62296a2fdcfc2a8c82bf4a27fc2dcdd89807db8c4
Pack digest: sha256:7f54a87e2dc7a7b6e3eae26bb3102f4352d5bed457d6259a145df1215fdee70c