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
/plugin marketplace add rsmdt/the-startup
/plugin install team@the-startupWhat 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-startupThis installs the whole team plugin with all its skills
2Skills CLI (Vercel)
npx skills add rsmdt/the-startup --skill technical-writing -a claude-code3Manually: put the files in place
~/.claude/skills/technical-writing/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/technical-writing/
1Skills CLI (Vercel)
npx skills add rsmdt/the-startup --skill technical-writing -a codex2Manually: put the files in place
.agents/skills/technical-writing/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add rsmdt/the-startup --skill technical-writing -a cursor2Manually: put the files in place
.cursor/skills/technical-writing/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install rsmdt/the-startup plugins/team/skills/development/technical-writing2Manually: put the files in place
.github/skills/technical-writing/SKILL.md1Skills CLI (Vercel)
npx skills add rsmdt/the-startup --skill technical-writing -a gemini-cli2Platform CLI
gemini skills install https://github.com/rsmdt/the-startup --path plugins/team/skills/development/technical-writingManually: put the files in place
.devin/skills/technical-writing/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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.