Skill Writer

---
name: skill-writer
description: Write a SKILL.md that teaches an AI agent one job properly — the five questions, trigger-rich description, and failure handling that keep a skill working unsupervised. Use when asked to write a skill, create a SKILL.md, teach an agent a new capability, fix a skill that never fires or gets ignored, split an instruction file into skills, or someone says 'the agent knows the rule but doesn't follow it'. For the always-loaded driver, see claude-md-writer. For testing what you wrote, see eval-writer.
metadata:
  version: 1.0.0
---

# Skill writer

A skill is one instruction file that teaches the agent **one job properly**. The
course's one-sentence standard:

> A good SKILL.md answers five questions in order: when do I run, what do I need
> as input, what are the exact steps (with the code), what does my output look
> like, and what do I do when it fails. **If a skill cannot answer the fifth
> question, it will silently break your run.**

Skills are what make agents scale: the driver stays under 200 lines because every
procedure lives here, loading only when its job comes up.

## Before you start

| Input | Why |
| --- | --- |
| The one job, in a sentence | Two jobs means two skills |
| The exact procedure — commands, thresholds, numbers | A skill states, never gestures |
| The phrases a user would say to trigger it | The description is the routing |
| What failure looks like in practice | Question five is written from real breakage |

## Step 1 — Write the description first (question 1)

The agent sees only the description until the skill fires. A perfect body behind
a vague description never runs.

Formula: **what it does + "Use when" + the words a user actually says** — 8+
phrasings including a frustrated one — **+ route to sibling skills by name** so
the wrong skill can't fire unchallenged.

## Step 2 — State the inputs (question 2)

A table near the top: each input, and why it is needed. Then the stop rule:
if a required input is missing, the skill **asks instead of assuming** —
skills fail by over-reaching far more often than by under-reaching.

## Step 3 — Write the steps as a procedure (question 3)

- Numbered steps the agent performs in order — prose invites improvisation,
  which is exactly what a procedure exists to prevent.
- Exact strings for anything typed: commands, file names, sizes. `1080x1350`,
  not "the right size".
- Every threshold carries its number. No number, no rule.
- Decision points become tables, not paragraphs of conditionals.

## Step 4 — Show the output shape (question 4)

A fenced block showing the **literal** shape of what comes back — not "produce a
report" but the report's actual skeleton. Ambiguity here produces a different
structure every run.

## Step 5 — Write "When it breaks" (question 5)

The one people skip, and the one that decides survival. A three-column table:

| What you see | What it means | The fix |

The middle column is what makes it useful — it names the *cause*, so the reader
recognises the next variant of the same problem. Close with the retry rule:
**never retry blindly — report what broke, what was tried, what is needed.** An
agent that fails loudly is worth ten that fail quietly.

## Step 6 — Add rules with reasons, and route onward

- Each rule carries its why — the reason is what lets the agent judge a case the
  rule didn't anticipate.
- End with **Related skills**: one line per sibling, when to go there instead.
- Helper files sit next to SKILL.md for detail that would bloat it; they load
  only when the skill reads them.

## Output

```
.claude/skills/<name>/SKILL.md answering, in order:
  Q1 description: 8+ triggers + sibling routing
  Q2 ## Before you start — inputs table + stop rule
  Q3 ## Step 1..N — numbered, exact strings, numbered thresholds
  Q4 ## Output — literal fenced shape
  Q5 ## When it breaks — see/means/fix table + never-retry-blindly
  ## Rules — each with its reason
  ## Related skills — routing for the reader
Helper files: <only if the body would bloat past ~200 lines>
```

## When it breaks

| What you see | What it means | The fix |
| --- | --- | --- |
| Skill never fires | Description lacks the user's real words | Rewrite with 8+ phrasings they'd actually type |
| Wrong skill fires instead | No sibling routing | "For X, see other-skill" in both descriptions |
| Agent reads it and still improvises | Documentation, not procedure | Numbered steps, exact strings, decision tables |
| Output different every run | No literal shape shown | Question 4: fence the skeleton |
| Works until anything goes wrong | Question five missing | The failure table is the survival kit — write it from real breakage |
| Skill does half of another skill's job | Two jobs in one file | Split; if they share a third of their steps, merge instead |
| Grows past 300 lines and slows runs | Detail belongs in helper files | Body is the procedure; depth loads on demand |

Never ship a skill whose failure section you couldn't write. Not knowing what
breakage looks like means the procedure hasn't been run for real yet — run it
once, then write question five from what actually happened.

## Rules

- **One skill, one job**, because a file serving two jobs routes badly and grows
  without limit.
- **The description is the routing**, because a perfect body behind a vague
  description never executes.
- **The fifth question is mandatory**, because a skill that can't say what to do
  on failure silently breaks the run that trusted it.
- **Exact strings and numbered thresholds**, because "do it well" cannot be
  followed and "2–7 words" can.
- **Ask when inputs are missing**, because over-reach on guessed inputs is the
  most common skill failure.

## Related skills

- **claude-md-writer** — what stays in the always-loaded driver instead.
- **eval-writer** — 3–5 tests per skill, one of refusal, before it ships.
- **agent-folder-scaffold** — where the skill folders live.
- **prompt-library-manager** — reusable starters that are not yet procedures.