# Skill Quality Checklist

Based on Anthropic's internal skills best practices (https://x.com/trq212/status/2033949937936085378).

Score each dimension 0-2: 0 = missing, 1 = partial, 2 = good. Max score: 24.

---

## 1. Category Fit (0-2)

Does the skill fit cleanly into ONE category?

| Category | Signal |
|----------|--------|
| Library & API Reference | Explains how to use a library, CLI, SDK. Gotchas, snippets, edge cases |
| Product Verification | Tests/verifies output is correct. Playwright, simulator, assertions |
| Data Fetching & Analysis | Connects to data/monitoring stacks. Credentials, dashboard IDs, workflows |
| Business Process & Automation | Automates repetitive workflows. Logs previous results for consistency |
| Code Scaffolding & Templates | Generates boilerplate for specific codebase function. May include scripts |
| Code Quality & Review | Enforces code quality. Deterministic scripts for robustness |
| CI/CD & Deployment | Fetch, push, deploy. May reference other skills for data |
| Runbooks | Symptom → investigation → structured report |
| Infrastructure Operations | Routine maintenance with guardrails for destructive actions |

- **2** — fits one category cleanly
- **1** — mostly one but bleeds into another
- **0** — unclear category or straddles several

## 2. Description Quality (0-2)

The `description:` field is scanned by Claude to decide "is there a skill for this request?"

Check:
- [ ] Has 3+ trigger phrases (what user says to invoke)
- [ ] Has "Do NOT use for X (use /other)" negative examples
- [ ] Specific enough to avoid false triggers on adjacent skills
- [ ] Under 300 chars (long descriptions dilute signal)

- **2** — trigger phrases + negative examples + no false triggers
- **1** — has triggers but missing negatives, or too vague
- **0** — generic description that could match anything

## 3. Progressive Disclosure (0-2)

"A skill is a folder, not just a markdown file."

Check:
- [ ] Uses `references/` for detailed content (API docs, templates, command lists)
- [ ] SKILL.md tells Claude what reference files exist and when to read them
- [ ] Scripts in `scripts/` for automation
- [ ] Templates in `assets/` for output generation
- [ ] SKILL.md stays under 300 lines (core logic only)

- **2** — reference files exist, SKILL.md points to them, under 300 lines
- **1** — has references OR is short, but not both
- **0** — everything crammed into one SKILL.md, over 400 lines

## 4. Gotchas Section (0-2)

"The highest-signal content in any skill."

Check:
- [ ] Has explicit `## Gotchas` section
- [ ] 3-5 concrete pitfalls (not generic warnings)
- [ ] Each gotcha is from real failure experience (not hypothetical)
- [ ] Gotchas push Claude away from default behavior it would otherwise follow

- **2** — 3+ concrete, experience-based gotchas
- **1** — has "Common Issues" but not real gotchas (more troubleshooting than prevention)
- **0** — no gotchas or pitfalls section

## 5. Don't State the Obvious (0-2)

"Focus on information that pushes Claude out of its normal way of thinking."

Check:
- [ ] No generic coding advice Claude already knows
- [ ] No framework docs that Claude has in training data
- [ ] Focuses on YOUR codebase specifics, internal conventions, non-obvious patterns
- [ ] Gotchas are things Claude would get WRONG by default

- **2** — every section adds non-obvious value
- **1** — mix of obvious and non-obvious content
- **0** — mostly restates what Claude already knows

## 6. Flexibility vs Railroading (0-2)

"Give Claude the information it needs, but give it the flexibility to adapt."

Check:
- [ ] Gives principles and context, not rigid step-by-step scripts
- [ ] Allows Claude to skip/adapt steps based on situation
- [ ] Uses "if X then Y" branching, not linear railroad
- [ ] Doesn't over-specify output format for every case

- **2** — provides context + principles, Claude adapts to situation
- **1** — mostly flexible but some unnecessarily rigid sections
- **0** — strict step-by-step that breaks on edge cases

## 7. Setup & Config (0-2)

"Store setup information in a config.json file in the skill directory."

Check:
- [ ] Handles first-run setup gracefully (detects missing config)
- [ ] Asks user for config via AskUserQuestion when needed
- [ ] Stores config in stable location (not overwritten on skill update)
- [ ] Works with sensible defaults if config is missing

- **2** — proper config pattern with detection + fallback
- **1** — handles setup but no persistent config
- **0** — assumes everything is configured, crashes on first run
- **N/A** — skill doesn't need configuration (score as 2)

## 8. Memory & State (0-2)

"Some skills can include a form of memory by storing data within them."

Check:
- [ ] Stores results/logs for future reference when appropriate
- [ ] Previous runs inform current run (e.g., standup skill reads history)
- [ ] Uses stable storage path (not deleted on skill update)
- [ ] Avoids accumulating unbounded state

- **2** — meaningful state that improves over time
- **1** — stateless but could benefit from memory
- **0** — should store state but doesn't
- **N/A** — genuinely stateless skill (score as 2)

## 9. Scripts & Composable Code (0-2)

"Giving Claude scripts and libraries lets Claude spend its turns on composition."

Check:
- [ ] Includes scripts/ or code snippets Claude can execute
- [ ] Code is composable (functions, not monoliths)
- [ ] Claude can generate new scripts by combining provided building blocks
- [ ] Prefers giving Claude code over natural language instructions for complex operations

- **2** — includes scripts/snippets that Claude composes into solutions
- **1** — has some code but mostly instructions
- **0** — all natural language, no executable code
- **N/A** — skill doesn't involve code execution (score as 2)

## 10. Allowed Tools (0-2)

Check:
- [ ] `allowed-tools:` lists only what's actually needed
- [ ] MCP tools listed with "use if available" fallback pattern
- [ ] Doesn't request overly broad tool access

- **2** — minimal, correct tool list with MCP fallback
- **1** — mostly correct but includes unnecessary tools
- **0** — missing allowed-tools or requests everything

## 11. Argument Handling (0-2)

Check:
- [ ] Has `argument-hint:` in frontmatter
- [ ] Parses `$ARGUMENTS` with clear fallback (empty → ask user)
- [ ] Supports common input patterns (name, path, URL, flag)

- **2** — hint + parsing + graceful fallback
- **1** — has arguments but no fallback or hint
- **0** — ignores arguments entirely

## 12. Output & Artifacts (0-2)

Check:
- [ ] Writes output to a file (not just prints to console)
- [ ] Output path is predictable and documented
- [ ] Output format is useful for downstream skills/pipeline
- [ ] Includes summary for user (not just raw data dump)

- **2** — file output + summary + pipeline-compatible
- **1** — prints to console only, or outputs without summary
- **0** — unclear what the skill produces

---

## Scoring

| Score | Grade | Action |
|-------|-------|--------|
| 22-24 | A | Ship-ready. Minor polish only |
| 18-21 | B | Good. Fix 1-2 weak areas |
| 14-17 | C | Functional but needs work. Prioritize gotchas + progressive disclosure |
| 10-13 | D | Needs rewrite. Missing fundamentals |
| 0-9 | F | Stub or notes, not a skill |

# Glossary — the vocabulary of skill quality

The domain model behind [writing-skills.md](writing-skills.md). Root virtue: **Predictability**. Every term is a lever on it, or a **failure mode** that costs it.

Use these words exactly when auditing or discussing a skill — the shared vocabulary is what makes two audits agree. Each entry ends with _Avoid_: the near-synonyms that blur the term.

## Predictability

The degree to which a skill makes the agent behave the same _way_ on every run — the same process, not the same output. The root virtue every other term serves; cost and maintainability are symptoms of it, not rivals.

_Avoid_: consistency, reliability, robustness, output-determinism

## Invocation

**Model-invoked** — a skill that keeps its **description**, so the agent can fire it autonomously; the human can still type its name, so model-invocation always _includes_ user reach. Pays permanent **context load**. Reachable by other skills. A model-invoked skill that is all **reference** is one home for shared reference. _Avoid_: ability, tool, capability

**User-invoked** — a skill with its description stripped: invisible to the agent, reachable only by the human typing its name. Zero context load; nothing but the human can fire it. _Avoid_: procedure, workflow, command

**Description** — the machine-readable trigger, and the one **context pointer** a model-invoked skill keeps loaded at all times. Its mere presence _is_ the invocation axis: keep it and the skill is model-invoked; delete it and it is user-invoked. _Avoid_: frontmatter, summary

**Context pointer** — a reference held in context that names out-of-context material and encodes the condition for reaching it. The description is the top-level pointer (window → skill); pointers to `references/` files are the same object one level down. Its wording, not its target, decides when and how reliably the agent reaches. _Avoid_: link, import

**Context load** — the cost a model-invoked skill imposes on the context window: its description, always loaded, spending tokens and attention. The brake on splitting into more model-invoked skills. _Avoid_: token cost, context bloat

**Cognitive load** — the cost a user-invoked skill imposes on the human: remembering it exists and when to reach for it. Not a cost to minimise — it is the price of human agency. Spend it where human judgement matters. _Avoid_: burden, overhead

**Router** — one place that names your user-invoked skills and when to reach for each, so the human holds one index instead of many. In solo-factory: `rules/routing.md`. _Avoid_: dispatcher, menu, registry

**Granularity** — how finely you divide skills. Finer division spends one of the two loads. Two cuts: by **invocation** (a distinct **leading word** deserves its own trigger) and by **sequence** (a step's **post-completion steps** need hiding). _Avoid_: chunking, modularity

## Information hierarchy

**Information hierarchy** — a skill's content ranked by how immediately the agent needs it: **steps** (in-file, primary) → **reference** in-file (secondary) → **reference** disclosed behind a **context pointer**. Independent of invocation. In-file reference that should be disclosed buries the steps and turns attending to them into a coin-flip. _Avoid_: structure, layout

**Steps** — the ordered actions the agent performs; the primary tier when a skill has them. Every step ends on a **completion criterion**. _Avoid_: workflow, instructions

**Reference** — material consulted on demand: definitions, facts, parameters, examples, conditional instructions. The prime candidate for **progressive disclosure**. _Avoid_: supporting material, background

**External reference** — reference living outside the skill system (`templates/principles/*.md`), pointable by any skill. The only shared home two user-invoked skills can use, since neither can fire the other. _Avoid_: doc, knowledge base

**Progressive disclosure** — moving reference out of `SKILL.md` into `references/` behind a pointer, so the top stays legible. Not primarily a token optimisation; it is how the hierarchy is protected. Licensed by **branching**. _Avoid_: lazy loading

**Co-location** — keeping a concept's definition, rules, and caveats under one heading rather than scattered, so reading one part brings its neighbours. The hierarchy ranks how far _down_ a piece sits; co-location decides what sits _beside_ it. Distinct from **duplication**: that repeats one meaning twice, scattering fragments one meaning across many places. _Avoid_: grouping, cohesion

## Steering

**Branch** — a distinct way a skill can be invoked, so different runs take different paths through it. The cleanest test for what to disclose. _Avoid_: path, case, fork

**Leading word** — a compact concept already in the model's pretraining that the agent thinks with while running the skill (_lesson_, _fog of war_, _tracer bullet_, _tight_, _red_). Repeated as a token, never as a sentence, it accumulates a distributed definition and anchors a region of behaviour in the fewest tokens. Anchors _execution_ in the body and _invocation_ in the description — word a description with the leading words you actually type when you want the skill. _Avoid_: keyword, term, motif

**Completion criterion** — the condition that tells the agent a unit of work is done. Two properties make it a lever: **clarity** (can it tell done from not-done?) resists **premature completion**; **demand** (how much it requires) sets **legwork**, and binds flat reference too ("every rule applied"). The strongest criteria are both checkable and exhaustive. _Avoid_: done condition, exit condition

**Legwork** — the digging an agent does within a single step: reading files, exploring, finding out rather than asking the user. Never written as its own step; latent in the wording. Raised by a leading word (_relentless_) or a demanding completion criterion. _Avoid_: scope, diligence, coverage

**Post-completion steps** — the steps that follow the current one. Visible, they pull the agent forward into **premature completion**; the defence is to hide them across a real context boundary. _Avoid_: horizon, lookahead

## Failure modes

**Premature completion** — ending the current step before it is genuinely done, because attention slips to _being done_. A between-steps failure: needs steps to occur. A tug-of-war between visible post-completion steps (the pull) and the criterion's clarity (the resistance). Sharpen the bound first — local and cheap; hide the later steps only when the criterion is irreducibly fuzzy _and_ you observe the rush. _Avoid_: premature closure, rushing

**Duplication** — the same meaning given more than one **single source of truth**. Costs maintenance and tokens, and inflates a meaning's prominence past its real rank. The accidental inverse of a leading word, which repeats a _token_ on purpose, never the meaning. _Avoid_: repetition, redundancy

**Sediment** — stale layers that settle because adding feels safe and removing feels risky, so you must core down through them to find what is live. The default fate of any skill without a pruning discipline. _Avoid_: accretion, cruft, rot

**Sprawl** — a skill simply too long, even when every line is live and unique. Distinct from sediment (length from staleness) and duplication (length from repetition) — sprawl is length itself. Cure: the ladder, plus splitting by branch or sequence. _Avoid_: bloat, verbosity

**No-op** — an instruction the model already obeys by default, so you pay load to say nothing. The test: does this line change behaviour versus the default? Model-relative, not reader-relative — two people disagreeing about a no-op disagree about the default, and settle it by running the skill, not by debate. _Avoid_: restating the obvious

**Negation** — steering by prohibition, which drags the forbidden behaviour into context and makes it _more_ available. _Never write verbose comments_ makes verbosity the pattern just read. Cure: prompt the **positive**. A prohibition earns its place only as a hard guardrail you cannot phrase positively — and even then, pair it with the positive target. _Avoid_: don't-prompting, pink elephant

## Pruning

**Single source of truth** — each meaning in exactly one authoritative place, so a behaviour change is a one-place edit. **Duplication** is its violation. _Avoid_: canonical location

**Relevance** — whether a line still bears on what the skill does. A line loses it by never bearing on the task, or by going stale. Distinct from **no-op**: relevance asks whether a line bears on the task, not whether it changes behaviour. _Avoid_: staleness, load-bearing

---

Adapted from [`writing-great-skills/GLOSSARY.md`](https://github.com/mattpocock/skills/tree/main/skills/productivity/writing-great-skills) by Matt Pocock (MIT). Condensed; solo-factory paths substituted. See [THIRD-PARTY.md](../../../THIRD-PARTY.md).

# Writing Skills — the levers behind the checklist

A skill exists to wrangle determinism out of a stochastic system. **Predictability** — the agent taking the same _process_ every run, not producing the same output — is the root virtue; every lever below serves it. A brainstorming skill should _predictably_ diverge: its tokens vary, its behaviour doesn't.

Where `checklist.md` scores a skill on 12 dimensions, this file explains the mechanics those scores measure. **Bold terms** are defined in [skills-glossary.md](skills-glossary.md).

## Invocation

Two choices, trading different costs:

- A **model-invoked** skill keeps a **description**, so the agent can fire it autonomously _and_ other skills can reach it (you can still type its name too). It contributes to **context load** — the description sits in the window every turn. Mechanics: omit `disable-model-invocation`, write a description with rich trigger phrasing ("Use when user says…, or…").
- A **user-invoked** skill strips the description from the agent's reach: only the human, typing its name, can invoke it — and no other skill can. Zero context load, but it spends **cognitive load**: _you_ are the index that must remember it exists. Mechanics: `disable-model-invocation: true`; the `description` becomes human-facing.

Pick model-invocation only when the agent must reach the skill on its own, or another skill must. If it only ever fires by hand, make it user-invoked and pay no context load.

When user-invoked skills multiply past what you can remember, that piled-up cognitive load is cured by a **router**: one place that names the others and when to reach for each. In solo-factory that router is `rules/routing.md` — a rules file rather than a skill, so it loads every session.

## Writing the description

A model-invoked **description** does two jobs — state what the skill is, and list the **branches** that should trigger it. Every word increases **context load**, so a description earns even harder pruning than the body:

- **Front-load the skill's leading word** — the description is where it does its invocation work.
- **One trigger per branch.** Synonyms that rename a single branch are **duplication** — "build features using TDD … asks for test-first development" is one branch written twice. Collapse them; keep only genuinely distinct branches.
- **Cut identity that's already in the body.** Keep the description to triggers, plus any "when another skill needs…" reach clause.
- **Name the neighbour you are not.** `Do NOT use for X (use /x)` is a trigger too — it stops the agent firing this skill on the next skill's job.

## Information hierarchy

A skill is built from two content types — **steps** and **reference** — that mix freely: a skill can be all steps, all reference, or both. The core decision is which to use and where each sits on the **information hierarchy**, a ladder ranked by how immediately the agent needs the material:

1. **In-skill step** — an ordered action in `SKILL.md`, the primary tier: what the agent does, in order. Each step ends on a **completion criterion**, the condition that tells the agent the work is done. Make it _checkable_ (can the agent tell done from not-done?) and, where it matters, _exhaustive_ ("every modified model accounted for", not "produce a change list") — a vague criterion invites **premature completion**.
2. **In-skill reference** — a definition, rule, or fact in `SKILL.md`, consulted on demand. Often a legitimately flat peer-set (every rule of a review on one rung) — a fine arrangement, not a smell.
3. **External reference** — reference pushed out of `SKILL.md` into `references/`, reached by a **context pointer**, loaded only when the pointer fires.

A demanding completion criterion drives thorough **legwork** — the digging the agent does within the work — whether the skill has steps or not, since "every rule applied" binds flat reference just as "every step done" binds a sequence.

Push too little down and the top bloats; push too much and you hide material the agent actually needs. That tension is the whole decision.

**Progressive disclosure** is the move down the ladder — out of `SKILL.md` into `references/` — so the top stays legible. Some skills are used in more than one way, and each distinct way is a **branch**. Branching is the cleanest disclosure test: inline what every branch needs, push behind a pointer what only some branches reach. A **context pointer**'s _wording_, not its target, decides when and how reliably the agent reaches the material — a must-have file behind a weak pointer is a variance bug, so sharpen the wording before pulling the material back inline.

Where the ladder decides _how far down_ a piece sits, **co-location** decides _what sits beside it_ once there: keep a concept's definition, rules, and caveats under one heading rather than scattered, so reading one part brings its neighbours with it.

## When to split

**Granularity** is how finely you divide skills, and each cut spends one of the two loads, so split only when the cut earns it. Two cuts:

- **By invocation** — split off a model-invoked skill when you have a distinct **leading word** that should trigger it on its own, or another skill must reach it. You pay context load for the new always-loaded description, so that independent reach has to be worth it.
- **By sequence** — split a run of **steps** when the steps still ahead (a step's **post-completion steps**) tempt the agent to rush the one in front of it. Hiding only works across a real context boundary — a user-invoked hand-off or a subagent dispatch. An inline call leaves the later steps in context and clears nothing.

A large skill is not automatically a broken one. Splitting `plan`, `build`, or `review` costs a new description each and scatters a sequence the agent currently runs end-to-end. Prefer disclosing their **reference** into `references/` first; split only when you observe the rush.

## Pruning

Keep each meaning in a **single source of truth**: one authoritative place, so changing the behaviour is a one-place edit.

Check every line for **relevance**: does it still bear on what the skill does?

Then hunt **no-ops** sentence by sentence, not just line by line: run the no-op test on each sentence in isolation, and when one fails, delete the whole sentence rather than trim words from it. Be aggressive — most prose that fails should go, not be rewritten.

## Leading words

A **leading word** is a compact concept already living in the model's pretraining that the agent thinks with while running the skill (e.g. _lesson_, _fog of war_, _tracer bullets_, _red_). Repeated throughout the text, it accumulates a distributed definition and anchors a whole region of behaviour in the fewest tokens, by recruiting priors the model already holds. Coining your own works if you define it clearly, but a made-up word recruits no priors — you pay in definition tokens what a pretrained word gives free.

It serves predictability twice. In the body it anchors _execution_: the agent reaches for the same behaviour every time the word appears. In the description it anchors _invocation_: when the same word lives in your prompts, your docs, and your code, the agent links that shared language to the skill and fires it more reliably.

Hunt for opportunities to refactor skills onto leading words. A triad spelled out at three sites (**duplication**), a description spending a sentence to gesture at one idea — each is a passage begging to collapse into a single token:

- "fast, deterministic, low-overhead" → _tight_ — one quality restated across a phase, collapsed into a single pretrained word (a _tight_ loop).
- "a loop you believe in" → _red_ — converts a fuzzy gate into a binary observable state (the loop goes _red_ on the bug, or it doesn't).

Assume every skill is carrying restatements that leading words retire — go find them.

## Failure modes

Use these to diagnose issues the user is having with a skill.

- **Premature completion** — ending a step before it's genuinely done, attention slipping to _being done_. Defence, in order: sharpen the completion criterion first (cheap, local); only if it is irreducibly fuzzy _and_ you observe the rush, hide the post-completion steps by splitting.
- **Duplication** — the same meaning in more than one place. Costs maintenance and tokens, and inflates a meaning's prominence on the ladder past its real rank.
- **Sediment** — stale layers that settle because adding feels safe and removing feels risky. The default fate of any skill without a pruning discipline.
- **Sprawl** — a skill simply too long, even when every line is live and unique. Hurts readability and maintainability and wastes tokens. The cure is the ladder: disclose reference behind pointers, and split by branch or sequence so each path carries only what it needs.
- **No-op** — a line the model already obeys by default, so you pay load to say nothing. The test: does it change behaviour versus the default? A weak leading word (_be thorough_ when the agent is already thorough-ish) is a no-op; the fix is a stronger word (_relentless_), not a different technique.
- **Negation** — steering by prohibition backfires: _don't think of an elephant_ names the elephant and makes it more available, not less. Prompt the **positive** — state the target behaviour so the banned one is never spoken; keep a prohibition only as a hard guardrail you can't phrase positively, and even then pair it with what to do instead.

## Attribution

Adapted from [`writing-great-skills`](https://github.com/mattpocock/skills/tree/main/skills/productivity/writing-great-skills) by Matt Pocock (MIT, Copyright (c) 2026 Matt Pocock). Reworded for solo-factory's layout (`references/`, `rules/routing.md`) and trimmed to the levers the audit checklist scores. See [THIRD-PARTY.md](../../../THIRD-PARTY.md).