Skip to main content

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.

bash
npx ai-devkit@latest skill add --built-in

What 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#

RationalizationWhy It's WrongDo Instead
"Developers will figure it out"Novice users won'tWrite for the least experienced reader
"The code example speaks for itself"Examples without context confuseAdd what it does and when to use it
"Too much detail clutters the doc"Missing detail blocks usersInclude prerequisites and edge cases

Output Template#

text
## [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
esc