Loading skill
Install any skill in seconds. Free to start, no credit card required.
Get Started Free →naxodev/writing-technical-docs
Opinionated playbook for writing technical documentation pages — anchored in the Diátaxis framework.
Passed 11 of 17 test cases with the skill, and 8 of 17 without it.
and 2 more in the full report
5 fixed9 passed either way7 still failing1 broke
Tokens, turns and time describe resource use, not a dollar price.
One of 5 test cases the skill fixed. Same model, same prompt, with and without the skill.
I want a single documentation page for our CLI tool `db-migrate` that teaches beginners how database migrations work from scratch, contains an API signature table of every CLI flag, provides an imperative step-by-step procedure for running migrations in production, and explains our schema lock architecture. Please combine all of this into one document.
| Checked | Without skill | With skill |
|---|---|---|
| Output states that the mixed quadrant requirements must be split across separate pages. | Missed | Passed |
The instructions your model reads when the skill loads.
This skill produces production-grade technical documentation pages. It is deliberately opinionated to avoid the failure modes AI agents fall into when writing docs (hallucinated APIs, mode-mixing, sycophantic preamble, unverified claims).
If a project-local rule (CLAUDE.md, repo style guide, explicit user
instruction) contradicts this skill, the project-local rule wins.
Follow these steps in order. Skipping step 2 is the dominant cause of bad AI-written docs.
Pick the quadrant (Diátaxis). Every doc page serves exactly one of four needs. Mixing modes is the single most common reason docs feel "off."
| Quadrant | Reader is… | The page answers | Voice |
|---|---|---|---|
| Tutorial | Learning | "Teach me, step by step" | Hand-holding, "we" |
| How-to guide | Already competent | "How do I do X?" | Imperative, "you" |
| Reference | Looking something up | "What is the exact shape?" | Neutral, factual |
| Explanation | Building a mental model | "Why does this work?" | Discursive, "because" |
Quick decision tree:
Is the reader trying to learn?
├── yes → Tutorial
└── no → Is the reader trying to do a specific task?
├── yes → How-to guide
└── no → Is the reader trying to look up an exact shape?
├── yes → Reference (prefer auto-gen)
└── no → Explanation
If the answer is "all of the above," split the page. If unsure between how-to and tutorial, ask: does the reader already know the domain? Yes
test cases passed, vs 8 / 17 without
Published skills whose descriptions closely match this one, with their headline benchmark lift.
More skills from the same source and nearby in the registry, with their headline benchmark lift.