Menu
Professional technical writing expertise for clear, audience-appropriate documentation. Use when producing user-facing docs, API guides, onboarding materials, release notes, or any content that requires structured information architecture, consistent voice and tone, and accessibility across skill levels.
| name | technical-writer |
| description | Professional technical writing expertise for clear, audience-appropriate documentation. Use when producing user-facing docs, API guides, onboarding materials, release notes, or any content that requires structured information architecture, consistent voice and tone, and accessibility across skill levels. |
| summary_l0 | Produce audience-appropriate technical documentation with structured information architecture |
| overview_l1 | This skill provides professional technical writing expertise for clear, audience-appropriate documentation. Use it when producing user-facing docs, API guides, onboarding materials, release notes, or any content requiring structured information architecture, consistent voice and tone, and accessibility across skill levels. Key capabilities include information architecture design, audience analysis and tone calibration, user-facing documentation authoring, API guide and reference writing, onboarding material creation, release notes composition, style guide enforcement, and accessibility review for different skill levels. The expected output is polished, well-structured technical documentation with appropriate voice, clear hierarchy, and audience-appropriate language. Trigger phrases: technical writing, documentation, API guide, user docs, onboarding materials, release notes, information architecture, documentation style, audience-appropriate writing. |
Apply the principles and practices of professional technical writing to produce documentation that is clear, accurate, accessible, and maintainable. This skill covers the full lifecycle of documentation, from audience research through publishing and maintenance.
Use this skill when you need to:
Trigger phrases: "write documentation", "user guide", "API guide", "release notes", "style guide", "docs review", "onboarding material", "technical writing"
This skill focuses on the craft of writing and the documentation lifecycle. For architecture-specific artifacts (ADRs, design documents, system architecture overviews), use the technical-documentation skill instead.
Before writing a single word, identify who will read the document and what they need to accomplish.
Define at least one reader persona for every document. A persona captures:
Map each topic in your document to one of three tiers:
| Tier | Reader knows | Document provides |
|---|---|---|
| Prerequisite | Nothing about the topic | Conceptual introduction, glossary links, and "before you begin" checklist |
| Working | Core concepts but not your system | Task-oriented instructions with brief context |
| Expert | Your system well | Reference tables, configuration options, edge cases |
Write for the lowest tier in your audience unless the document is explicitly scoped to a higher tier (for example, an "Advanced Configuration" page).
Separate task content ("how to do X") from concept content ("what X is and why it matters"). Mixing the two forces readers to scan past theory when they need steps, or past steps when they need understanding.
Before drafting, create a content map that answers:
Use the Document Planning Template at the end of this skill to structure this analysis.
Good structure makes documentation scannable, navigable, and maintainable.
Present information in layers of increasing detail:
Follow these rules for headings:
For documents longer than three screen-heights, include a table of contents (TOC). If your publishing system generates one automatically, ensure it includes H2 and H3 levels only. Deeper headings in the TOC create noise.
Design documents as independent modules that can be:
Avoid duplicating content across pages. Instead, link to a single source of truth and summarize only when the reader needs a brief reminder.
Consistent style builds reader trust and reduces cognitive load.
Write in active voice. Active voice clarifies who performs the action and produces shorter sentences.
| Passive (avoid) | Active (prefer) |
|---|---|
| The configuration file is loaded by the server | The server loads the configuration file |
| Errors are returned when validation fails | The API returns errors when validation fails |
| The button should be clicked | Click the button |
Use imperative mood for instructions: "Run the install script" rather than "You should run the install script".
Maintain a glossary file alongside your documentation. Each entry includes:
Update the glossary whenever you introduce a new term.
For any documentation set with more than one author, create a project style guide. Use the Style Guide Template at the end of this skill as a starting point.
Measure readability using the Flesch-Kincaid Grade Level or the Hemingway readability score. Targets:
Test readability on a sample of paragraphs, not just the full document average.
Code-adjacent documentation has its own conventions.
Every API endpoint or public function reference should include:
user_email over x or fooFor functions and CLI tools, document:
For systems that return error codes, maintain a catalog with:
| Code | Name | Description | Common Cause | Resolution |
|---|---|---|---|---|
| 1001 | AUTH_EXPIRED | Authentication token has expired | Token not refreshed before TTL | Re-authenticate using the login endpoint |
| 1002 | RATE_LIMITED | Request rate exceeded | Too many requests in the window | Wait for the reset time indicated in the Retry-After header |
When your API or product has multiple live versions:
Visuals reduce reading time for complex relationships, flows, and comparisons.
| Information type | Best visual format |
|---|---|
| System components and their relationships | Architecture diagram (boxes and arrows) |
| Sequential process or workflow | Flowchart or sequence diagram |
| Decision logic | Decision tree or flowchart with branches |
| Data relationships | Entity-relationship diagram |
| Timeline or phases | Gantt chart or timeline graphic |
| Comparison of options | Table |
| Hierarchical structure | Tree diagram |
| Quantitative data | Bar chart, line chart, or pie chart |
When using screenshots:
Use a visual when:
Use text when:
Documentation requires the same rigor as code review.
A subject-matter expert should verify:
A peer or editor should verify:
Schedule periodic reviews to catch drift between documentation and the product:
Automate link checking in CI. Tools such as markdown-link-check, htmltest, or linkinator catch broken internal and external links before they reach readers.
Ensure documentation meets WCAG 2.1 AA guidelines:
Track readability over time. After each major revision:
Documentation is a living product, not a one-time deliverable.
Treat documentation like source code:
Set up a CI/CD pipeline for documentation:
For each release, write a changelog entry using these categories: Added, Changed, Deprecated, Removed, Fixed, Security. Write entries for the reader, not the developer. "Users can now export reports as PDF" is better than "Added PDF export handler in reports module".
When deprecating a feature or API:
Every document moves through these stages: Draft (in progress), Published (live and current), Stale (needs review), Deprecated (scheduled for removal), Archived (removed from navigation but accessible via direct link). Track lifecycle status in frontmatter or a content inventory spreadsheet.
# Document Plan: [Document Title]
## Target Audience
- **Primary persona**: [Role, knowledge level, goal]
- **Secondary persona**: [Role, knowledge level, goal]
## Content Type
- [ ] Tutorial (learning-oriented, follows a path)
- [ ] How-to guide (task-oriented, solves a specific problem)
- [ ] Reference (information-oriented, describes the system)
- [ ] Explanation (understanding-oriented, provides context)
## Scope
- **In scope**: [What this document covers]
- **Out of scope**: [What it does NOT cover, with links to where those topics live]
## Prerequisites
- [What the reader must know or have installed before starting]
## Outline
1. [Section title and one-sentence summary]
2. [Section title and one-sentence summary]
## Review Plan
- **Technical reviewer**: [Name] | **Editorial reviewer**: [Name] | **Target date**: [Date]
# Documentation Style Guide
## Voice and Tone
- **Voice**: [e.g., Authoritative but approachable. Write as a knowledgeable colleague, not a textbook.]
- **Tone shifts**: [e.g., Neutral for reference pages. Encouraging for tutorials. Direct and calm for troubleshooting.]
## Language Rules
- Use active voice for instructions
- Use present tense ("The server returns an error") not future tense ("The server will return an error")
- Use second person ("you") for task-oriented content
- Avoid jargon unless the term is defined in the glossary
- Spell out acronyms on first use: "command-line interface (CLI)"
## Formatting Standards
- **Headings**: Sentence case, no trailing punctuation
- **Lists**: Use numbered lists for sequential steps, bullet lists for unordered items
- **Code**: Inline code for identifiers, fenced blocks for multi-line examples
- **File paths**: Inline code format (`/etc/config.yaml`)
- **UI elements**: Bold for button labels and menu items ("Click **Save**")
- **Keyboard shortcuts**: Kbd format where supported, otherwise inline code (`Ctrl+C`)
## Terminology
| Use | Do not use | Reason |
|-----|-----------|--------|
| [Canonical term] | [Rejected alternatives] | [Why] |
## Code Example Standards
- Include the language identifier on every fenced code block
- Use realistic variable names
- Show expected output when non-obvious
- Test every example before publishing
## Image and Diagram Standards
- Maximum width: 800px
- Include alt text on every image
- Use SVG or PNG for diagrams (no JPEG for line art)
- Store source files for diagrams alongside the image (e.g., `.drawio` next to the exported `.png`)
# Documentation Review Checklist
## Document: [Title] | Reviewer: [Name] | Date: [Date]
### Accuracy
- [ ] Technical facts verified against the current product version
- [ ] Code examples tested and confirmed working
- [ ] Version numbers and compatibility ranges correct
- [ ] Links resolve to the intended destination
### Structure and Clarity
- [ ] Title clearly describes the document purpose
- [ ] Headings are descriptive and logically nested
- [ ] Active voice used; sentences average under 25 words
- [ ] Terminology consistent with the project glossary
- [ ] Prerequisites listed before the first step; next steps provided at the end
### Accessibility and Maintenance
- [ ] All images have alt text; tables have header rows
- [ ] Frontmatter includes last-reviewed date
- [ ] Deprecation notices present where applicable
### Verdict: [ ] Approved | [ ] Minor changes needed | [ ] Revisions required
Solution: Embed doc updates into the definition of done for feature work. No feature ships without updated docs.
Solution: Create a style guide and enforce it through editorial review. Run a prose linter such as Vale in CI.
Solution: Conduct card sorts or tree tests with real users to validate information architecture. Improve search, labels, and cross-references.
Solution: Test code examples in CI. Treat broken examples as build failures.
Solution: Target Flesch-Kincaid Grade Level 8-10. Avoid idioms and unnecessarily complex vocabulary.
| Rationalization | Reality |
|---|---|
| "I'll write for myself, the readers are technical too" | Skipping the persona step means writing at expert tier for an audience that includes beginners, who then abandon the doc. Writing for the lowest tier in the audience is what keeps the install guide usable on day one. |
| "Passive voice sounds more professional" | "The configuration file is loaded" hides who loads it, so the reader cannot tell whether they or the system must act. Active voice plus imperative mood is the difference between a step a reader can follow and one they have to decode. |
| "The code examples are obviously correct, no need to run them" | Untested examples drift the moment the API changes and a copy-paste failure is the fastest way to lose reader trust. Examples tested in CI are the only ones that stay correct across releases. |
| "Docs can be updated later, the feature ships now" | "Later" never comes, and the doc silently rots until a freshness audit or an angry support ticket surfaces it. Embedding doc updates in the definition of done is what prevents the drift. |
Version: 1.0.0 Last Updated: March 2026
This skill is optimized for an iterative approach:
AI agent architecture and development patterns including tool use, memory systems, planning loops, and multi-agent orchestration. Use when building AI agents, designing tool interfaces, or implementing agent evaluation.
Prompt engineering principles and techniques for LLM applications including system prompts, chain-of-thought, few-shot learning, and prompt evaluation. Use when designing prompts, optimizing LLM outputs, or building prompt pipelines.
API design principles for REST, GraphQL, and gRPC including versioning, pagination, error handling, and documentation. Use when designing new APIs, reviewing API contracts, or migrating between API styles.
System architecture design including requirements analysis, trade-off evaluation, ADRs, and system decomposition. Use when designing new systems, evaluating architectures, or documenting design decisions.
Business analysis expertise for translating business needs into technical requirements. Use when eliciting requirements from stakeholders, modeling business processes, writing functional specifications, performing gap analysis, defining data dictionaries, or creating acceptance test scenarios from business rules.
Product management analysis for engineering-informed decision framing. Use when a task needs product framing, feature prioritization based on user impact and engineering reality, scope control to prevent complexity creep, or structured now/next/later sequencing with explicit tradeoffs.