writing-skills · Skill Writing Guide
A methodology skill for writing and reviewing skill documentation. Its core claim: writing a skill is TDD applied to process documentation — first watch an agent fail in a no-skill baseline scenario (red), then write SKILL.md to address exactly that (green), then hunt for loopholes and close them (refactor).
It ships the SKILL.md structure spec, a skill-type taxonomy (technique / pattern / reference), and SDO description principles (the description states when to use the skill, never a summary of its process) — so the skills you write are both discoverable and behavior-changing.
Example invocation: "I want to turn this code-review process into a skill."
Full brief
Positioning
writing-skills is a guide skill for writing skill documentation. Its core principle: if you haven't watched an agent fail without the skill, you don't know what the document should teach. It answers "how should the document be written" — not testing or packaging.
Core capabilities
- TDD mapping: test case = pressure scenario with a subagent; production code = SKILL.md; red = the agent violates the rule without the skill; green = it complies with the skill; refactor = close loopholes. Run the baseline scenario before writing.
- When-to-create checklist: create — the technique wasn't obvious, you'll reference it again, the pattern is general; don't create — one-off solutions, already well-documented practices, mechanical constraints enforceable by regex (automate those instead).
- Skill-type taxonomy: Technique (concrete method with steps), Pattern (way of thinking), Reference (API/syntax docs).
- SKILL.md structure template: frontmatter (
name/descriptionrequired) plus Overview, When to Use, Core Pattern, Quick Reference, Common Mistakes; flat directory, heavy references split into separate files. - SDO (Skill Discovery Optimization): the description states when to use the skill (starts with "Use when…"), never a summary of its process — the description decides whether future agents will load the skill at all.
Workflow
- Run baseline pressure scenarios; watch how the agent fails; record its rationalizations
- Write SKILL.md targeting exactly those violations (minimal, explain the why instead of stacking MUSTs)
- Re-test to verify compliance
- Hunt for new loopholes, close them, re-verify
Inputs & outputs
| Input | Notes |
|---|---|
| The technique / pattern / reference to capture | Required |
| Known failure scenarios | Optional |
Output: a SKILL.md draft conforming to the structure spec.
Boundaries with adjacent skills
- skill-creator: the complete toolchain for producing and validating a working skill — parallel evals, quantitative benchmarks, human review, trigger optimization, packaging.
- writing-skills (this): the documentation methodology — TDD-for-docs, SKILL.md structure, SDO principles. The two pair well: write the document with this skill, prove it works with skill-creator.
Fit
- Turning personal know-how into a reusable skill
- Reviewing whether an existing skill's documentation meets the structure spec
- Settling document structure and type before writing a new skill
Before you start
- No special setup. Familiarity with TDD's red-green-refactor cycle is recommended — it's this skill's theoretical foundation.
writing-skills is part of the Aiglade Skill library. Invoke it from the Aiglade chat box in plain language.