Skillwright
Build a skill as a harness extension, not a prompt.
prompting < harness engineering. Prose the model may honor is the first half;
machinery the harness runs (script, router, hook, exit code, sub-agent gate)
forces the rest. Write minimal prose, harden only instructions that measurably
fail. Most skills ship instruction-only and need no machinery — add it only when
you can name the ignored instruction; it costs cache misses, portability, and a
format contract.
Workflow
- [ ] 1. Baseline: run 2-3 real tasks with no skill; save failures verbatim
- [ ] 2. Trigger: write name + description to fire on those tasks (below)
- [ ] 3. Freedom: rate each instruction high / medium / low (below)
- [ ] 4. Draft: minimal prose SKILL.md, just enough to beat baseline
- [ ] 5. Harden: convert still-failing instructions to machinery -> references/hardening.md
- [ ] 6. Disclose: split over-limit content into one-level-deep references (below)
- [ ] 7. Verify: references/conventions.md, then `make check`; lint + run every script
- [ ] 8. Ship: references/checklist.md
Trigger (name + description)
Only name + description load at startup; the description decides firing. If a
skill never triggers, the description is wrong, not the body.
name: lowercase [a-z0-9-], max 64 chars, must equal the directory; no
claude / anthropic; never helper / utils / tools.description: third person, folded > block, max 1024 chars. State what it
does AND when to fire; embed the literal phrases the user types. Be pushy,
models under-trigger. Never a raw ": " in a plain scalar (breaks discovery).
Degree of freedom
Same dial as hardening: high = prose, low = an exact script. Match to fragility.
| Level |
When |
Form |
| High |
many valid paths; context decides |
numbered prose steps |
| Medium |
preferred pattern, some variance ok |
parameterized script |
| Low |
fragile, order-critical |
one exact command, "do not modify" |
Over-constrain an open task and you strangle the model; under-constrain a fragile
one and it walks off the cliff.
Progressive disclosure
Context is a shared budget. Assume the model knows general concepts; add only what
it lacks.
- SKILL.md under 100 lines (this collection's bar). Over that, split.
- References one level deep; nested refs get partially read.
- Table of contents atop any reference over 100 lines. Split by domain.
- Scripts are executed (only stdout costs tokens): say "run X" vs "see X".
- Descriptive filenames; forward slashes only.
Anti-patterns
Body before description. Machinery before a prose instruction has failed.
Explaining what the model knows. Nested refs, option menus, Windows paths, magic
constants. Assuming one harness's behavior is universal. Shipping without a
re-runnable baseline or a green make check.
1---2name: skillwright3description: Author a new Agent Skill (a SKILL.md plus optional references, scripts, and hooks) for any task or domain. Use when the user says "write a skill", "create a skill", "author a skill", "scaffold a skill", "new SKILL.md", "make a Claude Code skill", "turn this into a skill", "build an agent skill", or wants to design, review, or improve a skill. Covers the frontmatter trigger contract, degree-of-freedom calibration, progressive disclosure, converting prose into machinery (references/hardening.md), this collection's conventions (references/conventions.md), and the ship checklist (references/checklist.md).4---56# Skillwright78Build a skill as a harness extension, not a prompt.910`prompting < harness engineering`. Prose the model *may* honor is the first half;11machinery the harness *runs* (script, router, hook, exit code, sub-agent gate)12forces the rest. Write minimal prose, harden only instructions that measurably13fail. Most skills ship instruction-only and need no machinery — add it only when14you can name the ignored instruction; it costs cache misses, portability, and a15format contract.1617## Workflow1819```20- [ ] 1. Baseline: run 2-3 real tasks with no skill; save failures verbatim21- [ ] 2. Trigger: write name + description to fire on those tasks (below)22- [ ] 3. Freedom: rate each instruction high / medium / low (below)23- [ ] 4. Draft: minimal prose SKILL.md, just enough to beat baseline24- [ ] 5. Harden: convert still-failing instructions to machinery -> references/hardening.md25- [ ] 6. Disclose: split over-limit content into one-level-deep references (below)26- [ ] 7. Verify: references/conventions.md, then `make check`; lint + run every script27- [ ] 8. Ship: references/checklist.md28```2930## Trigger (name + description)3132Only name + description load at startup; the description decides firing. If a33skill never triggers, the description is wrong, not the body.3435- `name`: lowercase `[a-z0-9-]`, max 64 chars, must equal the directory; no36 `claude` / `anthropic`; never `helper` / `utils` / `tools`.37- `description`: third person, folded `>` block, max 1024 chars. State what it38 does AND when to fire; embed the literal phrases the user types. Be pushy,39 models under-trigger. Never a raw `": "` in a plain scalar (breaks discovery).4041## Degree of freedom4243Same dial as hardening: high = prose, low = an exact script. Match to fragility.4445| Level | When | Form |46|---|---|---|47| High | many valid paths; context decides | numbered prose steps |48| Medium | preferred pattern, some variance ok | parameterized script |49| Low | fragile, order-critical | one exact command, "do not modify" |5051Over-constrain an open task and you strangle the model; under-constrain a fragile52one and it walks off the cliff.5354## Progressive disclosure5556Context is a shared budget. Assume the model knows general concepts; add only what57it lacks.5859- SKILL.md under 100 lines (this collection's bar). Over that, split.60- References one level deep; nested refs get partially read.61- Table of contents atop any reference over 100 lines. Split by domain.62- Scripts are executed (only stdout costs tokens): say "run X" vs "see X".63- Descriptive filenames; forward slashes only.6465## Anti-patterns6667Body before description. Machinery before a prose instruction has failed.68Explaining what the model knows. Nested refs, option menus, Windows paths, magic69constants. Assuming one harness's behavior is universal. Shipping without a70re-runnable baseline or a green `make check`.
indrasvat