The Complete Guide to SKILL.md
SKILL.md is a structured instruction file used to teach AI agents a reusable capability, workflow, or domain behavior. A strong SKILL.md usually includes a clear purpose, trigger conditions, step-by-step instructions, examples, boundaries, and optional scripts or resources.
Key takeaways
- The frontmatter description doubles as the trigger: agents match it against the task to decide whether the skill applies.
- The four booleans that predict quality: has examples, has boundaries, has tests, has scripts. Most published skills ship none of the four.
- A skill is procedural memory made durable: the difference between telling someone "review this code" and handing them the review checklist.
- When-NOT-to-use sections are rarer than when-to-use sections and prevent most misfires.
- Skills can bundle executable scripts, which makes third-party skills a code-review surface, not just a content one.
Anatomy of a SKILL.md
A SKILL.md has two parts: frontmatter that decides whether the skill runs, and a body that decides how well it runs.
---
name: systematic-debugging
description: Use when encountering any bug, test failure, or
unexpected behavior, before proposing fixes
---
# Systematic Debugging
[purpose, steps, verification, boundaries, examples]| Component | Job | Quality signal |
|---|---|---|
| name | Stable identifier | Kebab-case, task-shaped |
| description | The trigger: matched against the task | States when to use AND when not to |
| Purpose | The failure this skill prevents | Names a concrete failure, not an aspiration |
| Instructions | The procedure | One action per step, observable results |
| Verification | How the skill checks its own work | Runnable commands or inspectable artifacts |
| Boundaries | Never-do rules | Present at all (most skills omit them) |
| Examples | Worked applications | Realistic input, applied steps, verified result |
| Scripts / resources | Bundled executables and references | Reviewed like code, because they are code |
How triggering works
Agents match the frontmatter description against the current task. This makes the description the single most important line in the file: a trigger-shaped description ("Use when encountering any bug, test failure, or unexpected behavior") fires reliably; a marketing-shaped one ("A powerful debugging assistant") mostly never fires. Silent non-use is the most common failure of published skills, and it is invisible: the skill exists, the agent just never picks it up.
Slash commands are the manual alternative: the operator invokes the procedure explicitly. High-stakes procedures are often deliberately slash-only, trading trigger convenience for governance.
Skills are procedural memory
The deepest way to understand the format: a skill is procedural memory made durable. Instead of hoping the model remembers your team's review workflow, the workflow is written down where it cannot decay, can be diffed when it changes, and produces one quality level across every operator. That is the difference between a prompt and a skill: prompts are consumed by a session; skills are infrastructure.
What separates high-leverage skills
Agentiquette scores skills on leverage: reliable capability added per unit of adoption effort. Across our scored set, the predictors are consistent:
- Trigger precision. The best skills state exclusions. verification-before-completion even anticipates the agent rationalizing its way around the trigger and counters it in a red-flag table.
- Verification. A skill that cannot check its own output cannot refuse bad work.
- Boundaries. Never-do rules are what make a skill safe to auto-trigger.
- The four booleans. Has examples, has boundaries, has tests, has scripts. Most published skills ship none of the four; S-tier candidates ship at least three.
The security angle
Skills can bundle executable scripts, and installing a skill means an agent may run them. Treat third-party skills as a code-review surface: read the scripts, check the boundaries, and run the evaluation checklist before team-wide adoption.
Frequently asked questions
What is SKILL.md?
A structured instruction file that teaches AI agents a reusable capability or workflow, typically YAML frontmatter (name, trigger-bearing description) followed by markdown instructions, examples, and boundaries.
How does a SKILL.md get triggered?
The agent matches the frontmatter description against the current task. Precise, task-shaped descriptions fire reliably; vague ones cause silent non-use. Slash commands are the manual alternative.
What's the difference between SKILL.md and CLAUDE.md?
SKILL.md is a procedure (how to do one class of work); CLAUDE.md is identity (persistent project context). Procedure versus identity is the whole distinction.
What are common mistakes in SKILL.md files?
Marketing-style descriptions that never trigger, missing when-not-to-use exclusions, no verification steps, and no examples. All four are scored dimensions in Agentiquette's rubric.
Summary
- Topic
- SKILL.md: the agent skill file format
- Definition
- A structured instruction file teaching agents a reusable capability: purpose, triggers, steps, examples, boundaries, optional scripts
- Best used for
- Encoding procedures once so every session and every operator gets the same quality
- Related concepts
- agent skill, trigger conditions, AGENTS.md, procedural memory
- Common mistakes
- Vague descriptions that never fire; no boundaries; no verification; treating a prompt with a filename as a skill
- Recommendation
- Start from the Agentiquette SKILL.md template; write the description as trigger conditions with exclusions