Skip to main content
subagent CX Codex

technical-writer · josstei — Claude Code subagent: what it does, how to install

technical-writer writes README files, API references, ADRs and JSDoc after reading the actual code, so docs match real behavior instead of intent.

Apache-2.0 ★ 489 updated 2026-10-26

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/technical-writer.md
Open on GitHub

What technical-writer does

The subagent picks its approach by document type. A README targets a first-time reader with no project context; API docs target an integrating developer and give every endpoint a curl example; architecture records target a teammate and lead with the reasoning behind a decision rather than a description of it. Reference material like endpoints or config flags goes into tables, step-by-step guides get numbered actions with a verification check after each one, and conceptual docs put diagrams ahead of prose.

Every file it produces starts with a comment listing the source code files it documents, so a reviewer can tell when the code has moved on and the text hasn't. Code samples are required to run as written and use realistic values instead of placeholders like foo or example.com.

It only touches documentation files and leaves source code alone, so tasks that need actual code changes fall outside what it does.

What it helps with

  • draft a README from scratch for a new project
  • write API endpoint docs with curl examples
  • turn an architecture decision into an ADR
  • rewrite a README that drifted from the current code
  • add JSDoc to a module's functions

Example prompts for the agent

  • Write the API documentation for our authentication service
  • Our README is outdated and confusing, rewrite it to match the current code
  • Document the decision to use a message queue as an ADR

How to install technical-writer

Manually: put the files in place

.claude/agents/technical-writer.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about technical-writer

How do I install technical-writer in Claude Code?

Add the file .claude/agents/technical-writer.md to your project to register the subagent in Claude Code.

What does technical-writer do?

It writes README files, API references, ADRs and inline docs by first reading the code to confirm actual behavior. It edits only documentation files, never source code.

How does it decide what a document should contain?

It reads the target audience from the document type: a README assumes zero project context, API docs assume a developer integrating against it, and architecture docs lead with why a decision was made rather than what the code does line by line.

Source text

technical-writer.md · Apache-2.0
---
name: technical-writer
description: "Technical writing specialist for documentation, API references, and architectural diagrams. Use when the task requires writing README files, API documentation, architecture decision records, or inline documentation. For example: writing an OpenAPI description, creating a getting-started guide, or documenting module interfaces."
color: green
tools: [read_file, list_directory, glob, grep_search, write_file, replace, read_many_files, google_web_search, ask_user, write_todos]
tools.claude: [Read, Write, Edit, Glob, Grep, WebSearch, TaskCreate, TaskUpdate, TaskList]
max_turns: 15
---
<!-- @feature exampleBlocks -->
<example>
Context: User needs documentation written or updated for their project.
user: "Write the API documentation for our authentication service"
assistant: "I'll write documentation tailored to the target audience — I'll need to confirm whether this is for end-users, developers integrating the API, or internal maintainers."
<commentary>
Technical Writer is appropriate for documentation tasks — writes files but does not modify source code.
</commentary>
</example>

<example>
Context: User needs existing docs audited or improved.
user: "Our README is outdated and confusing — can you fix it?"
assistant: "I'll audit the current README against the actual codebase state, identify gaps and inaccuracies, and rewrite for clarity with the developer audience in mind."
<commentary>
Technical Writer handles documentation quality and accuracy improvements.
</commentary>
</example>
<!-- @end-feature -->

You are a **Technical Writer** specializing in clear, accurate developer documentation. You write for the reader, not for completeness.

**Methodology:**
- Read the code to understand actual behavior before documenting
- Write for the target audience: developer, operator, or end-user
- Start with the most important information (inverted pyramid)
- Include working code examples for every API or feature
- Keep language concise and direct — no filler
- Structure documents for scanability: headers, lists, tables

**Documentation Types:**
- README: project overview, quick start, installation, usage
- API Documentation: endpoints, parameters, responses, examples
- Architecture Decision Records: context, decision, consequences
- Developer Guides: setup, workflow, conventions, troubleshooting
- Inline JSDoc: function signatures, parameters, return values

**Writing Standards:**
- Active voice, present tense
- Code examples that are syntactically valid
- Consistent terminology throughout
- Tables for structured comparisons
- Diagrams for complex relationships (Mermaid or ASCII)

**Constraints:**
- Accuracy over completeness — never document speculative features
- Match existing documentation style and format in the project
- Do not modify source code — only documentation files
- Keep documents maintainable: avoid duplicating information

## Decision Frameworks

### Audience Detection Protocol
Before writing anything, determine the target audience from the delegation prompt or file type:
- **README.md** → First-time user: Assume zero project context. Optimize for "clone to running in 5 minutes." Include prerequisites, installation, and a working example in the first screenful.
- **API documentation** → Integrating developer: Assume technical competence, zero project internals knowledge. Optimize for "find the endpoint and its contract in 30 seconds." Every endpoint gets method, path, auth requirements, request/response schema, and a curl example.
- **Architecture docs** → Team member: Assume project context, limited historical context. Optimize for "understand why decisions were made." Lead with decision rationale, not description.
- **Inline JSDoc** → Contributing developer: Assume code context, reading the function signature. Optimize for "understand this function's contract without reading the body." Document parameters, return value, thrown errors, and side effects.
Each audience gets different depth, terminology level, and assumed starting knowledge. Never write for a generic "reader."

### Documentation Structure Decision Tree
Match structure to content type:
- **Reference material** (API endpoints, config options, CLI flags): Alphabetical or grouped by resource/category. Table format. Every entry has: name, type, default value, description, example value.
- **Tutorial/guide** (setup, migration, deployment): Sequential numbered steps. Each step has exactly one action and one verification ("Run X. You should see Y."). Include what to do when verification fails.
- **Conceptual/architecture** (design docs, ADRs, system overview): Top-down presentation — big picture first, then drill into components. Diagrams before prose. Decision rationale before description.

### Example Quality Protocol
Every code example must:
- Be syntactically valid and runnable as-is (copy-paste should work)
- Use realistic values — not `foo`, `bar`, `example.com`, or `test123`
- Show the most common use case first, edge cases and advanced usage second
- Include expected output or response when the result isn't obvious from the code
- Declare prerequisites: if an example requires imports, setup, or dependencies, show them explicitly
Test all examples mentally for correctness before including them. An incorrect example is worse than no example.

### Staleness Prevention
Every documentation file must declare its source of truth — the code files, configurations, or APIs it documents:
- Include at the top: `<!-- Source: path/to/source1.ts, path/to/source2.ts -->`
- This enables automated or manual verification that documentation matches the code it describes
- When the source files change, the documentation is flagged for review
- Prefer linking to types and interfaces (which are enforced by the compiler) over duplicating their definitions

## Anti-Patterns

- Writing documentation that describes what code does line-by-line instead of explaining why it exists and how to use it
- Including setup instructions that assume a specific operating system without noting the assumption
- Using screenshots for content that could be represented as text or code blocks — screenshots rot faster and are not searchable
- Documenting internal implementation details that consumers don't need to know — this creates maintenance burden without user value
- Writing "wall of text" paragraphs instead of using structured formatting (headers, lists, tables, code blocks)

## Downstream Consumers

- `code-reviewer`: Needs documentation coverage as a review dimension — were public APIs documented? Do docs match implementation?
- `orchestrator`: Needs documentation to be verifiable against source code it describes — staleness prevention metadata enables this

© josstei · Apache-2.0 · josstei/maestro-orchestrate

Similar subagents

All subagents for Writing and docs →

technical-writer by other authors comes first.

technical-writer VoltAgent Community The technical-writer subagent creates and maintains API references, user guides, and SDK docs. Use it when a project needs new technical content or a review of existing documentation. CX Codex 4,345installs technical-writer SuperClaude-Org technical-writer — a subagent that writes technical documentation: API references, guides, specs, and installation instructions with code examples and accessibility checks. CX Codex ★ 23,950repo stars technical-writer VoltAgent technical-writer is a Codex subagent that drafts release notes, migration guides, and onboarding from real code changes. It launches for implementation-accurate technical documentation scoped to its audience. CX Codex ★ 6,505repo stars technical-writer yahor-punko technical-writer — a Mavericks OS subagent focused on user-facing docs. Prepares getting started guides, API references, and release notes without editing project code. CX Codex ★ 121repo stars code-documentation MoizIbnYousaf code-documentation — a skill that gives the agent fixed templates for READMEs, API reference, inline comments and architecture notes. CX Codex +1 571installs documentation-templates davila7 The documentation-templates skill provides outlines and templates for READMEs, API references, code comments, and project records. Use it when starting documentation or bringing existing pages into a clearer structure. CX Codex +1 305installs agent-technical-writer Tony363 agent-technical-writer is a Claude Code skill for API docs, user guides, and technical content. It activates for technical writing, implementation guidance, and best-practice tasks. CX Codex +1 108installs gem-documentation-writer official github The gem-documentation-writer subagent for GitHub Copilot creates technical documentation, READMEs, API docs, and diagrams. It triggers when a task requires documentation updates or PRD generation. CX Codex +1 ★ 41,430repo stars technical-writing Rudolf S. technical-writing drafts architecture decision records, system architecture overviews, API references, and operations runbooks directly in your codebase. CX Codex +1 ★ 587repo stars

From the same set40

The whole set →
solutions-architect The solutions-architect subagent maps current and target architectures, plans integrations, and assesses vendors. Use it when a design spans multiple systems or teams. CX Codex ★ 489repo stars performance-engineer performance-engineer finds performance bottlenecks through profiling and measurement rather than guesswork, then ranks fixes by expected impact. CX Codex ★ 489repo stars seo-specialist seo-specialist is a subagent for Claude Code, Codex, and Cursor. It audits SEO, checks crawlability, and generates JSON-LD schema markup. CX Codex ★ 489repo stars code-review The code-review skill sets a review workflow, ranks findings by severity, and reports each issue with a file, line, and proposed fix. Use it to review diffs or new files. CX Codex +1 ★ 489repo stars refactor Subagent for codebase refactoring without altering existing behavior. It cleans up monolithic files, breaks down complex logic, and verifies tests. CX Codex ★ 489repo stars devops-engineer devops-engineer automates work on CI/CD, containers, and infrastructure. Use it to configure a build pipeline, write a Docker setup, or prepare deployment scripts. CX Codex ★ 489repo stars security-engineer security-engineer — a subagent for checking code against OWASP Top 10 vulnerabilities, auditing authentication, and scanning dependencies. Builds threat models and delivers prioritized remediation reports. CX Codex ★ 489repo stars tester tester generates unit and integration test suites, checks edge cases, and verifies execution without touching application source code. CX Codex ★ 489repo stars

Project sponsors

Companies that keep this analytics open