Documentation skill
Technical Writer Skill
Review and improve documentation for clarity, structure, and novice comprehension.
On this page
Install command
AI DevKit installs its built-in skills as one curated set. Run this once to install technical-writer with the rest of the built-in workflow skills.
npx ai-devkit@latest skill add --built-inWhat it does
Use technical-writer when documentation needs to become clearer, more helpful, or easier for a new user to follow. It reviews docs as a reader and proposes concrete fixes before rewriting.
When to use it
- Improve README, docs, and guides
- Find unclear assumptions or missing setup steps
- Make technical writing easier for novice users
Supported agents
- Claude Code
- Codex
- Cursor
- opencode
The SKILL.md file
This is what your agent reads when the skill runs. View it on GitHub (opens in a new tab)
Review documentation as a novice would experience it. Suggest concrete improvements.
Hard Rules#
- Do not rewrite documentation until the user approves the suggested fixes.
- Suggest concrete fix text, not vague advice.
Review Dimensions (rate 1-5)#
- Clarity: Can a novice understand it without outside help?
- Completeness: Are prerequisites, examples, and edge cases covered?
- Actionability: Can users copy-paste commands and follow along?
- Structure: Does it flow logically from simple to complex?
Priority#
- High: Blocks novice users from succeeding.
- Medium: Causes confusion but workaround exists.
- Low: Polish and nice-to-have.
Red Flags and Rationalizations#
| Rationalization | Why It's Wrong | Do Instead |
|---|---|---|
| "Developers will figure it out" | Novice users won't | Write for the least experienced reader |
| "The code example speaks for itself" | Examples without context confuse | Add what it does and when to use it |
| "Too much detail clutters the doc" | Missing detail blocks users | Include prerequisites and edge cases |
Output Template#
## [Document Name]
| Aspect | Rating | Notes |
|--------|--------|-------|
| Clarity | X/5 | ... |
| Completeness | X/5 | ... |
| Actionability | X/5 | ... |
| Structure | X/5 | ... |
**Issues:**
1. [High] Description (line X)
2. [Medium] Description (line X)
**Suggested Fixes:**
- Concrete fix with example text