Technical Writing

Technical writing

Use for repository documentation, including READMEs, guides, references, flow docs, specifications, and technical PR descriptions. Read the applicable AGENTS.md first; it owns documentation destinations, length limits, and repository terminology. This skill needs no global tools or skill installation.

Establish the reader and evidence

1. Identify the reader, intended action or decision, page scope, and source of truth. Read current code, schemas, tests, command output, and the relevant diff.
2. Choose the requested mode: create from evidence, edit while preserving useful facts and the author's intent, or review with findings before proposed fixes.
3. Lead with what the reader can accomplish and one recommended path. Mention implementation first when explaining architecture or internals is the task.
4. Verify claims, examples, defaults, paths, and failure behavior. Label material uncertainty and name the missing evidence; polished prose is not verification.
5. Before handing off any writing, complete the required plain-language pass.

Write precise prose

• Use present tense, active voice, concrete nouns, and one term per concept. Expand unfamiliar abbreviations at first use; use established product names.
• Define unfamiliar concepts through their owner, action, and observable role. Replace “the controller handles deployment” with what it reads, decides, and starts, when those details matter to the reader.
• Make every sentence help the reader decide, act, or understand a boundary. Delete repeated background, meta-commentary, and generic benefits.
• Treat all, only, and never as literal claims. Name the surface they cover. Use must for requirements and can for options; preserve consequential limits.
• Use sentence-case, action-specific article headings and descriptive links. Explain why when it changes a decision or prevents a failure.
• Give each contract, default, and behavior one owning page. Link its definition from other pages rather than copying it into competing references.
• Make diagrams agree with prose: actors and resources are nodes, containment uses regions, and arrows describe interactions. Do not imply deployment proof from source alone or rely on color alone to convey meaning.

Always deslop the writing

Run this pass whenever you write, edit, or review prose, including small changes, PR descriptions, and review findings. The user does not need to request it. For edits, clean up the prose in scope and read the surrounding text for flow. For a review-only task, clean up your feedback and flag wording in the document when it obscures meaning; do not silently rewrite the source.

• Name who does what and under which conditions. Replace vague verbs and noun piles such as “performs readiness observation” with “checks whether the workload is ready.” Prefer familiar words; define necessary technical terms.
• Delete filler, canned transitions, empty claims, and repeated explanations. Remove contrasts or caveats the reader does not need. Avoid invented labels.
• Put the main point first. Split a sentence when the reader has to untangle several actions, actors, or conditions; give each paragraph one main point.
• Check the edit against the original and the evidence. Preserve scope, required actions, permissions, warnings, failure behavior, and uncertainty. Do not make an unsupported claim sound certain or cut a useful detail merely to shorten it.

Organize and name development docs

When adding, grouping, moving, or renaming documentation, read Organization and naming. Choose one home based on the reader's task. Use short sidebar labels and give the article enough context to make sense when opened directly. Check repository guidance and the current navigation before treating a proposed layout as implemented.

Choose the smallest useful page

Keep quickstarts and main guides focused on the normal supported workflow. Put platform-specific failures, uncommon environment workarounds, and extended diagnostic steps in the owning troubleshooting page or section. Link to that guidance with a short, symptom-based pointer beside the affected step; do not front-load the main guide with edge cases. Keep required prerequisites, security boundaries, destructive effects, and recovery needed for the normal workflow beside the action they affect.

Omit empty or irrelevant sections. Split independently useful topics when a page mixes too many reader tasks. Keep the root documentation map and affected links current, following repository page ownership and length limits.