Writing Great Skills

A skill is a reusable instruction package: a proven prompt with a defined process and output format. Great skills are why one team's agent produces consistent, senior-level work while another's produces vibes.

Anatomy of an excellent skill

Every high-quality skill answers five questions:

1. Purpose — one sentence: what it does and when to use it
2. Process — numbered steps the agent follows, in order
3. Output contract — the exact sections or format of the result
4. Examples — 1–3 realistic invocations
5. Boundaries — what it must not do (the most-skipped, most-valuable part)

Look at advanced-code-reviewer: a process ("follow this exact process: 1…7"), an output contract ("use these exact sections"), and hard rules ("never be vague"). That structure is the whole trick.

The five rules

1. Deterministic steps beat open instructions. "Check for N+1 queries, then missing indexes, then…" outperforms "review the database code carefully."
2. Define the output format exactly. Markdown sections with fixed headings, or JSON with a schema. The next agent (or human) should be able to parse it without guessing.
3. Encode judgment, not just process. "Prefer the smallest fix that addresses the root cause, not the symptom" is the kind of line that separates great skills from checklists.
4. State boundaries explicitly. "Never edit implementation files — only test files." Agents respect hard limits far more reliably than implied scope.
5. Start small, version it. Ship the minimal useful version, then add rules each time the skill produces a wrong result. Treat it like code.

Where skills live, per runner

Claude Code's SKILL.md format uses YAML frontmatter so the agent knows when to load it without paying its full token cost up front:

---
name: code-reviewer
description: Use when reviewing diffs or PRs for correctness, security, and tests.
---

You are an expert senior engineer performing a rigorous code review.
(full instructions here…)

That description matters more than it looks — it's how the agent decides the skill is relevant. Write it as "Use when…" with concrete triggers.

A complete template

---
name: web-researcher
description: Use when the task needs current information from the web with cited sources.
---

**Purpose**: Targeted web research returning synthesized findings with sources.

**Process**:
1. Break the question into 2–4 specific search queries
2. Search; open the 3–5 most authoritative results
3. Cross-check claims that appear in only one source
4. Synthesize — do not pad

**Output** (exact sections):
## Summary        ← 3 sentences max
## Key Findings   ← bullet points, each with a source link
## Open Questions ← what couldn't be verified

**Boundaries**:
- Never present a single-source claim as established fact
- If sources conflict, show the conflict instead of picking silently

Testing a skill

Run it on a task where you already know the right answer, three times. If the outputs differ in structure, your output contract is too loose. If they differ in substance, your process steps are too vague. Tighten and repeat — this loop is fast and brutally effective.

Download ready-made skills from the Skills directory, or study a real skill definition in the examples.