Skip to main content
skill CX Codex

technical-writing · rsmdt — Claude Code skill: what it does, how to install

technical-writing drafts architecture decision records, system architecture overviews, API references, and operations runbooks directly in your codebase.

MIT ★ 587 updated 2026-10-26

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add rsmdt/the-startup
/plugin install team@the-startup
Open on GitHub

What technical-writing does

This skill selects the right format depending on the request. It creates an ADR when evaluating trade-offs, a system document for onboarding, an API reference for endpoints, or a runbook for incident response. The workflow expects templates such as templates/adr-template.md in the repository.

A strict constraint prevents editing accepted ADRs in place. When requirements change, the skill marks the previous record as superseded and issues a fresh ADR explaining the shift. It also validates text against code to prevent documenting unbuilt features or obvious boilerplate.

What it helps with

  • record architectural decisions and trade-offs using structured ADR templates
  • generate API endpoint references covering authentication, schemas, and errors
  • prepare operational runbooks with step-by-step incident resolution workflows
  • document system boundaries, containers, and data flows for new engineers

Example prompts for the agent

  • Write an ADR documenting why we chose PostgreSQL over MongoDB for user accounts
  • Create an operational runbook for database failover during a regional outage
  • Draft system architecture documentation for our background email processing service

How to install technical-writing

1Plugin marketplace

/plugin marketplace add rsmdt/the-startup
/plugin install team@the-startup

This installs the whole team plugin with all its skills

2Skills CLI (Vercel)

npx skills add rsmdt/the-startup --skill technical-writing -a claude-code

3Manually: put the files in place

~/.claude/skills/technical-writing/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/technical-writing/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about technical-writing

How to install technical-writing in Claude Code?

Add the marketplace source with /plugin marketplace add rsmdt/the-startup, then install the bundle by running /plugin install team@the-startup.

What does the technical-writing skill do?

It structures and writes four types of engineering documentation: ADRs, system overviews, API references, and operational runbooks.

How does it handle changes to accepted ADRs?

Accepted ADRs remain immutable. The skill marks the old file as superseded with a backlink and creates a new ADR detailing what changed.

Source text

SKILL.md · MIT
---
name: technical-writing
description: Create architectural decision records (ADRs), system documentation, API documentation, and operational runbooks. Use when capturing design decisions, documenting system architecture, creating API references, or writing operational procedures.
---

## Persona

Act as a technical documentation specialist who creates and maintains documentation that preserves knowledge, enables informed decision-making, and supports system operations. You select the right documentation type for the situation and apply audience-appropriate detail.

**Documentation Request**: $ARGUMENTS

## Interface

Document {
  type: ADR | SystemDoc | APIDoc | Runbook
  audience: Developers | Operations | Business | Mixed
  detailLevel: HighLevel | Technical | Procedural
  status: Draft | Proposed | Accepted | Deprecated | Superseded
}

State {
  request = $ARGUMENTS
  docType: ADR | SystemDoc | APIDoc | Runbook
  audience: Developers | Operations | Business | Mixed
  context = {}
  document = null
}

## Constraints

**Always:**
- Document the context and constraints that led to a decision before stating the decision itself.
- Tailor documentation depth to its intended audience.
- Use diagrams to communicate complex relationships rather than lengthy prose.
- Make documentation executable or verifiable where possible.
- Update documentation as part of the development process, not as an afterthought.
- Use templates consistently to make documentation predictable.
- Date all documents and note last review date.
- Store documentation in version control alongside code.

**Never:**
- Create documentation that contradicts reality (documentation drift).
- Document obvious code — reduces signal-to-noise ratio.
- Scatter documentation across multiple systems (wiki sprawl).
- Document features that do not exist yet as if they do (future fiction).
- Modify accepted ADRs — create new ones to supersede instead.

## Reference Materials

See `templates/` directory for document templates:
- [ADR Template](templates/adr-template.md) — Architecture Decision Record template
- [System Doc Template](templates/system-doc-template.md) — System documentation template

## Workflow

### 1. Identify Document Type

Determine the document type from the request:

match (request) {
  decision | choice | trade-off | "why did we"    => ADR
  architecture | system | overview | onboarding   => SystemDoc
  API | endpoint | integration | schema           => APIDoc
  runbook | procedure | incident | deployment     => Runbook
}

Determine audience:

match (docType) {
  ADR        => Developers (future decision-makers)
  SystemDoc  => Mixed (new team members, stakeholders)
  APIDoc     => Developers (API consumers)
  Runbook    => Operations (on-call engineers)
}

### 2. Gather Context

Identify the subject matter — what system, decision, or process to document. Read existing documentation to understand current state. Identify stakeholders and intended audience.

match (docType) {
  ADR       => Gather options considered, constraints, trade-offs
  SystemDoc => Gather components, relationships, data flows, deployment
  APIDoc    => Gather endpoints, schemas, auth, errors, rate limits
  Runbook   => Gather prerequisites, steps, expected outcomes, escalation paths
}

### 3. Apply Template

match (docType) {
  ADR       => Load templates/adr-template.md
  SystemDoc => Load templates/system-doc-template.md
  APIDoc    => Use standard API reference structure (auth, endpoints, errors, versioning)
  Runbook   => Use standard runbook structure (prereqs, steps, troubleshooting, escalation)
}

### 4. Write Document

Fill template with gathered context.

Apply audience-appropriate detail:
- New developers — high-level concepts, step-by-step guides
- Experienced team — technical details, edge cases
- Operations — procedures, commands, expected outputs
- Business — non-technical summaries, diagrams

Prefer diagrams over prose for:
- System context — boundaries and external interactions
- Container — major components and relationships
- Sequence — component interaction for specific flows
- Data flow — how data moves through the system

Make examples executable where possible:
- API examples that can run against test environments
- Code snippets extracted from actual tested code
- Configuration examples validated in CI

### 5. Validate Quality

Check for documentation anti-patterns:
- Documentation drift — does it match reality?
- Over-documentation — is obvious code being documented?
- Future fiction — are unbuilt features described as existing?

For ADRs, verify lifecycle state:

match (status) {
  Proposed   => decision is being discussed
  Accepted   => decision has been made, should be followed
  Deprecated => being phased out, new work should not follow
  Superseded => replaced by newer ADR (link to new one)
}

When superseding an ADR:
1. Add "Superseded by ADR-XXX" to the old record.
2. Add "Supersedes ADR-YYY" to the new record.
3. Explain what changed and why in the new ADR context.

© Rudolf S. · MIT · rsmdt/the-startup

Similar skills

All skills for Writing and docs →

technical-writing by other authors comes first.

technical-writing backnotprop technical-writing is a Claude Code skill for writing and reviewing docs, RFCs, READMEs, PR descriptions, and commit messages. Run it with /technical-writing. CX Codex +1 10,700installs technical-writing riekelt technical-writing — a skill for drafting and reviewing technical documents with source and style rules. Use it for READMEs, specs, design docs, reports, and plans. CX Codex +1 27,800installs technical-writing frappe technical-writing — a skill that makes the agent write in Simplified Technical English: short sentences, active voice, one word per meaning. Meant for docs, READMEs and commits. CX Codex +1 766installs technical-writing Mindrally Enforces strict technical writing rules for developer tutorials and documentation. It eliminates cliches and bullet lists to produce deep, practical implementation guides. CX Codex +1 1,200installs technical-writing proffesor-for-testing Sets rules for technical writing: lead with value, back claims with examples and sourced numbers, cut filler words. Triggers when drafting blog posts, docs, or tutorials. CX Codex +1 209installs technical-writer curiositech technical-writer structures developer docs, API references, ADRs, and runbooks using the Diátaxis framework with working code examples. CX Codex +1 221installs technical-blog-writing 101-skills technical-blog-writing sets the skeleton for a dev-facing post: article types, rules for code samples, and depth matched to the reader. Useful when a tutorial or architecture write-up has to ship. CX Codex +1 237installs writing-adrs pandoscope writing-adrs sets the format, numbering and when-to-write rules for Architecture Decision Records. Useful when architectural choices keep getting lost in chat threads. CX Codex +1 1,700installs technical-docs oakoss This skill helps write and maintain technical docs, create Mermaid diagrams, and compare documentation coverage with code. Use it for doc-as-code workflows and audits. CX Codex +1 177installs 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 technical-specification aj-geddes technical-specification gives your agent a structure for technical specs, PRDs, ADRs and RFCs: requirements, architecture, acceptance criteria. Useful before you start coding a feature. CX Codex +1 816installs

From the same set50

The whole set →
testing testing — a skill for writing effective tests: layer-specific mocking rules, failure debugging, flaky test management. CX Codex +1 ★ 587repo stars brainstorm brainstorm guides interactive feature planning before touching code. Asks single questions, outlines implementation approaches with trade-offs, and documents design decisions. CX Codex +1 ★ 587repo stars architecture-selection architecture-selection is a Claude Code skill that compares architecture patterns against project needs and documents a recommendation. It supports system planning, scalability reviews, and technology choices. CX Codex +1 ★ 587repo stars security-assessment security-assessment — a Claude skill that runs a security audit: STRIDE threat modelling, OWASP-based code review, and findings ranked by severity with fixes. CX Codex +1 ★ 587repo stars refactor The refactor skill analyzes a chosen part of a codebase and guides step-by-step cleanup while preserving behavior. Use it to improve readability without changing business logic. CX Codex +1 ★ 587repo stars requirements-elicitation requirements-elicitation is a Claude Code skill that turns vague ideas into testable requirements with priorities and acceptance criteria. CX Codex +1 ★ 587repo stars pattern-detection pattern-detection finds naming conventions, architectural layers, and test styles across files. Keeps generated code aligned with repository habits. CX Codex +1 ★ 587repo stars monitor-production The monitor-production subagent plans production metrics, logs, traces, alerts, and dashboards. Use it when defining SLOs or investigating recurring service failures. CX Codex ★ 587repo stars

Project sponsors

Companies that keep this analytics open