Skillwright
Guide the writing of a skill that an agent can read cheaply, navigate reliably, and execute without guessing.
Non-negotiables
- Frontmatter is
name and description only. Extra fields break portability across SKILL.md-aware tools.
- Write tool-agnostic. "Search the codebase for X", not a specific tool name. The skill must work in Claude Code, Codex, and whatever comes next.
- The name must not collide with well-known skills (check before writing, see step 2).
- Adapted content keeps its attribution. A footer line naming the source and license; never copy text from unlicensed sources, rewrite the ideas instead.
- The prose passes unslop. No em dashes, sentence-case headings, no decorative emojis, no filler.
Step 1: Confirm it should be a skill
| It is a… |
When |
Lives in |
| Instruction file entry |
The rule applies to every message (style, standing constraints) |
CLAUDE.md / AGENTS.md |
| Skill |
Reusable procedure for a recurring kind of task |
skills/<name>/SKILL.md |
| Spec |
Describes one deliverable for one project |
The project, not a skills repo |
If the content is a standing rule, stop here and put it in the instruction file. A skill that should fire on all writing can do both: a normal skill plus an @-import of its file from the instruction file for a guaranteed always-on path.
Step 2: Name it
- Short, kebab-case, says what it does or is memorably coined. Verb-first names ("prep-commit") read well for workflows.
- Check for collisions before committing to it:
ls ~/.claude/skills/, the well-known skill repos (anthropics/skills, superpowers, pstack, android/skills), and a GitHub name search. Generic names ("code-review", "skill-creator") are guaranteed collisions; avoid them.
Step 3: Write the description
The description is the only part loaded in every session, and it alone decides whether the skill fires. Include, in one or two sentences:
- What the skill does (the imperative core).
- When to use it, including literal trigger phrases users say ("update dependencies", "bump versions").
- For an always-on skill, end with "Must always apply." so the ever-present description nudges invocation.
Step 4: Choose the layout
| Level |
Loaded |
Budget |
| description |
always |
one or two sentences; spend them on triggers |
| SKILL.md body |
every invocation |
small; workflow, invariants, decision rules |
references/*.md |
on demand, per section of work |
can be large; one file per ecosystem/topic |
Getting this split right saves more context than any formatting choice inside a file. If the body explains one ecosystem or scenario for more than ~30 lines, that content wants to be a reference file. Give sibling reference files an identical section skeleton so an agent that learned one can navigate the others blind. Executable helpers go in a scripts/ directory next to the SKILL.md.
Step 5: Write the body
Open with the workflow in one line. When the skill has invariants that hold across steps, put them in a numbered non-negotiables block right after it: attention is strongest at the start, and later text can cite "non-negotiable 3" instead of restating it. A small single-purpose skill needs no such block. Number sections (§2.2 style) when references cross-link them; anchors act as pointers and cut repetition.
Match the form of each chunk to the shape of its content:
| Content shape |
Form |
Why |
| Sequential procedure |
numbered steps or STEP headings |
Order is load-bearing, and numbers make steps citable |
| Executable |
fenced code block with <placeholders> |
The agent runs it instead of reconstructing it |
| Relational facts (X couples to Y, error → fix) |
table |
Encodes relations with no connective-tissue tokens |
| Parallel, order-independent items |
bullets |
The only case plain bullets win |
| Causal or conditional logic |
one tight sentence |
"A → B because C unless D" dies when fragmented |
| Expected output |
literal template, exact strings to say |
The agent copies instead of improvising |
Rules of thumb while writing:
- State each rule once. The exception is guardrails ("never hand-edit the lockfile"): repeat those in every section where they bite, so a partial read still contains them.
- Give a non-obvious rule a one-clause why. Reasoned rules get better compliance and generalize to cases the rule didn't anticipate.
- Mark provenance when it differs: rules learned from real project history versus rules assembled from public docs. Readers calibrate trust differently.
- Delegate instead of duplicating: when an official skill or document owns a topic (an upgrade guide, a vendor skill), point at it, resolved dynamically (by target version or by lookup), never by a pinned name that rots.
- End with a verification checklist. Agents turn checklists into todos.
Anti-patterns, all of which cost tokens or reliability:
- Motivational repetition (persuasion is for humans; an agent needs the rule once).
- Vague adverbs ("carefully", "appropriately"): not executable, replace with the concrete action.
- Over-fragmentation: forty ungrouped one-liners lose addressability just like a wall of prose; group under headings.
- Describing an output format in prose when a template would show it.
- A "When to use" body section that restates the description. The description already routed the invocation; the body is only read after that decision.
Step 6: Verify before publishing
1---2name: skillwright3description: Write or restructure an agent skill (SKILL.md). Use when creating a new skill, reviewing an existing one, or deciding whether something should be a skill at all. Covers naming, the description line, layout, formatting for agent readers, and the pre-publish checklist.4---56# Skillwright78Guide the writing of a skill that an agent can read cheaply, navigate reliably, and execute without guessing.910## Non-negotiables11121. **Frontmatter is `name` and `description` only.** Extra fields break portability across SKILL.md-aware tools.132. **Write tool-agnostic.** "Search the codebase for X", not a specific tool name. The skill must work in Claude Code, Codex, and whatever comes next.143. **The name must not collide** with well-known skills (check before writing, see step 2).154. **Adapted content keeps its attribution.** A footer line naming the source and license; never copy text from unlicensed sources, rewrite the ideas instead.165. **The prose passes unslop.** No em dashes, sentence-case headings, no decorative emojis, no filler.1718## Step 1: Confirm it should be a skill1920| It is a… | When | Lives in |21|----------|------|----------|22| Instruction file entry | The rule applies to every message (style, standing constraints) | `CLAUDE.md` / `AGENTS.md` |23| Skill | Reusable procedure for a recurring *kind* of task | `skills/<name>/SKILL.md` |24| Spec | Describes one deliverable for one project | The project, not a skills repo |2526If the content is a standing rule, stop here and put it in the instruction file. A skill that should fire on all writing can do both: a normal skill plus an `@`-import of its file from the instruction file for a guaranteed always-on path.2728## Step 2: Name it2930- Short, kebab-case, says what it does or is memorably coined. Verb-first names ("prep-commit") read well for workflows.31- Check for collisions before committing to it: `ls ~/.claude/skills/`, the well-known skill repos (anthropics/skills, superpowers, pstack, android/skills), and a GitHub name search. Generic names ("code-review", "skill-creator") are guaranteed collisions; avoid them.3233## Step 3: Write the description3435The description is the only part loaded in every session, and it alone decides whether the skill fires. Include, in one or two sentences:3637- What the skill does (the imperative core).38- When to use it, including literal trigger phrases users say ("update dependencies", "bump versions").39- For an always-on skill, end with "Must always apply." so the ever-present description nudges invocation.4041## Step 4: Choose the layout4243| Level | Loaded | Budget |44|-------|--------|--------|45| description | always | one or two sentences; spend them on triggers |46| SKILL.md body | every invocation | small; workflow, invariants, decision rules |47| `references/*.md` | on demand, per section of work | can be large; one file per ecosystem/topic |4849Getting this split right saves more context than any formatting choice inside a file. If the body explains one ecosystem or scenario for more than ~30 lines, that content wants to be a reference file. Give sibling reference files an identical section skeleton so an agent that learned one can navigate the others blind. Executable helpers go in a `scripts/` directory next to the SKILL.md.5051## Step 5: Write the body5253Open with the workflow in one line. When the skill has invariants that hold across steps, put them in a numbered non-negotiables block right after it: attention is strongest at the start, and later text can cite "non-negotiable 3" instead of restating it. A small single-purpose skill needs no such block. Number sections (§2.2 style) when references cross-link them; anchors act as pointers and cut repetition.5455Match the form of each chunk to the shape of its content:5657| Content shape | Form | Why |58|---------------|------|-----|59| Sequential procedure | numbered steps or STEP headings | Order is load-bearing, and numbers make steps citable |60| Executable | fenced code block with `<placeholders>` | The agent runs it instead of reconstructing it |61| Relational facts (X couples to Y, error → fix) | table | Encodes relations with no connective-tissue tokens |62| Parallel, order-independent items | bullets | The only case plain bullets win |63| Causal or conditional logic | one tight sentence | "A → B because C unless D" dies when fragmented |64| Expected output | literal template, exact strings to say | The agent copies instead of improvising |6566Rules of thumb while writing:6768- State each rule once. The exception is guardrails ("never hand-edit the lockfile"): repeat those in every section where they bite, so a partial read still contains them.69- Give a non-obvious rule a one-clause why. Reasoned rules get better compliance and generalize to cases the rule didn't anticipate.70- Mark provenance when it differs: rules learned from real project history versus rules assembled from public docs. Readers calibrate trust differently.71- Delegate instead of duplicating: when an official skill or document owns a topic (an upgrade guide, a vendor skill), point at it, resolved dynamically (by target version or by lookup), never by a pinned name that rots.72- End with a verification checklist. Agents turn checklists into todos.7374Anti-patterns, all of which cost tokens or reliability:7576- Motivational repetition (persuasion is for humans; an agent needs the rule once).77- Vague adverbs ("carefully", "appropriately"): not executable, replace with the concrete action.78- Over-fragmentation: forty ungrouped one-liners lose addressability just like a wall of prose; group under headings.79- Describing an output format in prose when a template would show it.80- A "When to use" body section that restates the description. The description already routed the invocation; the body is only read after that decision.8182## Step 6: Verify before publishing8384- [ ] Frontmatter has `name` and `description` only; description carries trigger phrases85- [ ] Name collision-checked against installed skills and the well-known repos86- [ ] Body opens with the workflow; cross-step invariants, if any, sit in a non-negotiables block87- [ ] Every chunk's form matches its content shape (table above)88- [ ] Heavy per-topic detail split into `references/` with a shared skeleton89- [ ] Guardrails repeated where they bite; everything else stated once90- [ ] Adapted content attributed; provenance marked where rules aren't battle-tested91- [ ] Prose passes unslop (no em dashes, sentence-case headings, no decorative emojis)92- [ ] Tested: invoke the skill on a real case and watch where it hesitates; that's the next edit
Ashhas