SKILL.md: build an Agent Skill that is useful, discoverable, and testable

# 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.
- 6. Load only the relevant reference — For a skill that checks invoices, keep the trigger and basic steps in SKILL.md; put the detailed tax examples in a referenced file. Try one invoice task and one unrelated request. Record which reference was actually needed.

## 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

# 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:fac85c1b9247d6dc913e9b0b0903c92fb34c82b4e078599134d8caf6cc11935e

# 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.
- 6. Load only the relevant reference — For a skill that checks invoices, keep the trigger and basic steps in SKILL.md; put the detailed tax examples in a referenced file. Try one invoice task and one unrelated request. Record which reference was actually needed.

## 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

# 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:bf1a1a20cc90bfed473e5c04852ba30dd9ef8d5a2655f02bfcf2404c806ab92e