git:20260427.acce271 to v2.1.0

156 added, 598 removed. Audit A to A.

---

name: technical-writing

- description: Write clear internal technical documentation (specs, architecture, runbooks, API references, changelogs) for engineering and operations audiences. Use for repository-grounded, actionable docs—not marketing or vague overview decks unless the task requests them.

+ description: "Internal engineering docs: specs, ADRs, architecture, runbooks, migrations, rollout plans, and maintainer guides."

allowed-tools: Read Write Edit Glob Grep

+ license: MIT

metadata:

- tags: technical-writing, documentation, specs, architecture, runbooks, API-docs

- platforms: Claude, ChatGPT, Gemini, Cursor

+ tags: technical-writing, documentation, specs, architecture, adr, runbooks, migration, developer-docs, docs-as-code

+ platforms: Claude, ChatGPT, Gemini

+ version: "2.1.0"

+ modernization: 2026-04-13

+ hardening: 2026-04-17

---

# Technical Writing

- This skill guides **internal engineering documentation** (specs, architecture, runbooks, API references, changelogs)—not marketing or end-user product docs unless the task says otherwise.

+ Use this skill when the deliverable is **internal technical documentation for builders and operators**.

- **How to use it:** follow **Instructions** (Steps 1–5) in order. For copy-paste skeletons, use **Step 2** and **Document templates**. For the user’s final document, use normal Markdown and three backticks for code fences. In *this* skill file only, some templates use **four** leading backticks on the outer fence so inner triple-backtick samples do not break the fence pairing.

+ `technical-writing` is the documentation-cluster anchor for:

+ - technical specs

+ - product requirements documents (PRDs)

+ - architecture docs

+ - ADRs / decision records

+ - runbooks and incident procedures

+ - rollout / rollback / migration guides

+ - developer-facing implementation or maintenance guides

## When to use this skill

+ - A team needs a technical spec before implementation starts

+ - A team needs a PRD for product/feature requirements before design or implementation

+ - An engineer needs an architecture document or ADR that records trade-offs and decisions

+ - Ops needs a runbook, rollback guide, or incident response procedure

+ - A migration or rollout needs a durable written path with validation and rollback notes

+ - A developer-facing internal guide needs to explain how a system works and how to work on it safely

- - Writing technical specifications

- - Creating architecture documentation

- - Documenting system designs

- - Writing runbooks and operational guides

- - Creating developer documentation

- - API documentation

- - User manuals and guides

- - Release notes and changelogs

+ ## When not to use this skill

+ - **Published API docs, SDK docs, OpenAPI reference, developer portal content** → `api-documentation`

+ - **End-user onboarding, screenshots, tutorials, FAQs, help-center flows** → `user-guide-writing`

+ - **Release notes, `CHANGELOG.md`, migration announcements for customers/devs** → `changelog-maintenance`

+ - **Slides, pitch decks, roadmap presentations, architecture demos** → `presentation-builder`

+ - **Product positioning, launch copy, GTM messaging, marketing automation** → `marketing-automation`

+ - **The main job is deciding the feature or API itself before writing the doc** → `task-planning`, `api-design`, or the relevant planning skill first

## Instructions

- ### Step 1: Understand your audience

- **Developer audience**:

- - Focus on implementation details

- - Include code examples

- - Technical terminology is okay

- - Show how, not just what

- **DevOps/Operations audience**:

- - Focus on deployment and maintenance

- - Include configuration examples

- - Emphasize monitoring and troubleshooting

- - Provide runbooks

- **Manager/Stakeholder audience**:

- - High-level overview

- - Business impact

- - Minimal technical jargon

- - Focus on outcomes

- **End user audience**:

- - Simple, clear language

- - Step-by-step instructions

- - Visual aids (screenshots, videos)

- - FAQ section

- ### Step 2: Choose the right document type

- **Technical Specification**:

- ````markdown

- # [Feature Name] Technical Specification

- ## Overview

- Brief description of what this spec covers

- ## Problem Statement

- What problem are we solving?

- ## Goals and Non-Goals

- ### Goals

- - Goal 1

- - Goal 2

- ### Non-Goals

- - What we're explicitly not doing

- ## Solution Design

- ### High-Level Architecture

- ### Data Models

- ### API Contracts

- ### User Interface

- ## Implementation Plan

- ### Phase 1

- ### Phase 2

- ## Testing Strategy

- ## Security Considerations

- ## Performance Considerations

- ## Monitoring and Alerting

- ## Rollout Plan

- ## Rollback Plan

- ## Open Questions

- ## References

- ````

- **Architecture Document**:

- ````markdown

- # System Architecture

- ## Overview

- High-level system description

- ## Architecture Diagram

- [Insert diagram]

- ## Components

- ### Component 1

- - Responsibility

- - Technology stack

- - Interfaces

- ### Component 2

- _Repeat the same subsections (responsibility, stack, interfaces) for each additional component._

- ## Data Flow

- How data moves through the system

- ## Key Design Decisions

- ### Decision 1

- - Context

- - Options considered

- - Decision made

- - Rationale

- ## Technology Stack

- - Frontend: React, TypeScript

- - Backend: Python, FastAPI

- - Database: PostgreSQL

- - Infrastructure: AWS, Docker, Kubernetes

- ## Scalability

- How the system scales

- ## Security

- Authentication, authorization, data protection

- ## Monitoring and Observability

- Metrics, logs, tracing

- ## Disaster Recovery

- Backup and recovery procedures

- ## Future Considerations

- ````

- **Runbook**:

- ````markdown

- # [Service Name] Runbook

- ## Service Overview

- What this service does

- ## Dependencies

- - Service A

- - Service B

- - Database X

- ## Deployment

- ### How to deploy

- ```bash

- ./deploy.sh production

- ```

- ### Rollback

- ```bash

- ./rollback.sh

- ```

- ## Monitoring

- ### Key Metrics

- - Request rate

- - Error rate

- - Latency

- ### Dashboards

- - [Production Dashboard](link)

- - [Alerts](link)

- ## Common Issues

- ### Issue 1: High latency

- **Symptoms**: Response time > 1s

- **Diagnosis**: Check database connection pool

- **Resolution**: Restart service or scale up

- ### Issue 2: Memory leak

- **Symptoms**: Memory usage growing over time

- **Diagnosis**: Check heap dump

- **Resolution**: Restart service, investigate in staging

- ## Troubleshooting

- ### How to check logs

- ```bash

- kubectl logs -f deployment/service-name

- ```

- ### How to access metrics

- ```bash

- curl https://api/metrics

- ```

- ## Emergency Contacts

- - On-call: [PagerDuty](link)

- - Team Slack: #team-name

- ````

- **API Documentation**:

- ````markdown

- # API Documentation

- ## Authentication

- All requests require authentication:

- ```bash

- curl -H "Authorization: Bearer YOUR_TOKEN" \

- https://api.example.com/endpoint

- ```

- ## Endpoints

- ### List Users

- ```

- GET /api/v1/users

- ```

- **Parameters**:

- |------|------|----------|-------------|

- **Example Request**:

- ```bash

- curl -X GET "https://api.example.com/api/v1/users?page=1&limit=20" \

- -H "Authorization: Bearer YOUR_TOKEN"

- ```

- **Example Response**:

- ```json

- {

- "data": [

- {

- "id": 1,

- "name": "John Doe",

- "email": "john@example.com"

- }

- ],

- "pagination": {

- "page": 1,

- "limit": 20,

- "total": 100

- }

- ```

- **Error Responses**:

- | Status | Description |

- |--------|-------------|

- | 400 | Bad Request |

- | 401 | Unauthorized |

- | 500 | Server Error |

- ````

- ### Step 3: Writing guidelines

- **Clarity**:

- - Use simple, direct language

- - One idea per sentence

- - Short paragraphs (3-5 sentences)

- - Define technical terms

- - Avoid jargon when possible

- **Structure**:

- - Use hierarchical headings (H1, H2, H3)

- - Break content into sections

- - Use lists for multiple items

- - Use tables for structured data

- - Add table of contents for long docs

- **Examples**:

- - Include code examples

- - Provide diagrams

- - Show before/after comparisons

- - Real-world scenarios

- **Completeness**:

- - Cover prerequisites

- - Include error handling

- - Document edge cases

- - Explain why, not just how

- - Link to related docs

- **Consistency**:

- - Consistent terminology

- - Consistent formatting

- - Consistent code style

- - Consistent structure

- ### Step 4: Visual aids

- **Architecture diagrams** (Mermaid):

- ```mermaid

- graph TB

- A[Client] -->|HTTP| B[Load Balancer]

- B --> C[Web Server 1]

- B --> D[Web Server 2]

- C --> E[Database]

- D --> E

- ```

- **Sequence diagrams**:

- ```mermaid

- sequenceDiagram

- Client->>+Server: Request

- Server->>+Database: Query

- Database-->>-Server: Data

- Server-->>-Client: Response

- ```

- **Flowcharts**:

- ```mermaid

- flowchart TD

- A[Start] --> B{Is valid?}

- B -->|Yes| C[Process]

- B -->|No| D[Error]

- C --> E[End]

- D --> E

- ```

- **Code blocks** with syntax highlighting:

- ```python

- def calculate_total(items: List[Item]) -> Decimal:

- """Calculate total price of items."""

- return sum(item.price for item in items)

- ```

- **Screenshots**:

- - Use for UI documentation

- - Annotate important parts

- - Keep up-to-date with UI changes

- **Tables**:

- | :-------- | :--- | :------ | :---------- |

- | timeout | int | 30 | Request timeout in seconds |

- | retries | int | 3 | Number of retry attempts |

- ### Step 5: Review and refine

- **Self-review checklist**:

- - [ ] Clear purpose stated upfront

- - [ ] Logical flow of information

- - [ ] All terms defined

- - [ ] Code examples tested

- - [ ] Links work

- - [ ] Diagrams are clear

- - [ ] No typos or grammar errors

- - [ ] Consistent formatting

- - [ ] Table of contents (if needed)

- - [ ] Last updated date

- **Get feedback**:

- - Have someone from target audience review

- - Test instructions (can they follow them?)

- - Check for missing information

- - Verify accuracy

- **Maintain documentation**:

- - Update with code changes

- - Version your docs

- - Archive outdated docs

- - Regular review cycle

- ## Document templates

- ### Technical Spec Template

- ````markdown

- # [Feature Name] Technical Spec

- **Author**: [Your Name]

- **Date**: [Date]

- **Status**: [Draft/Review/Approved]

- ## Overview

- [1-2 paragraphs describing what this document covers]

- ## Background

- [Context and motivation]

- ## Goals

- - Goal 1

- - Goal 2

- ## Non-Goals

- - What we're not doing

- ## Detailed Design

- [Technical details]

- ## Alternatives Considered

- [Other approaches and why we didn't choose them]

- ## Timeline

- - Week 1: ...

- - Week 2: ...

- ## Open Questions

- - Question 1

- - Question 2

- ## Features

- - Feature 1

- - Feature 2

- ## Installation

- ### Prerequisites

- - Node.js (current LTS) or the version in the repository

- - Package manager: npm, pnpm, or yarn as used by the project

- ### Setup

- ```bash

- git clone https://github.com/user/project.git

- cd project

- npm install

- ```

- ## Usage

- ```bash

- npm start

- ```

- ## Configuration

- Environment variables:

- - `API_KEY`: Your API key

- - `PORT`: Server port (default: 3000)

- ## Development

+ ### Step 1: Classify one primary mode

+ Normalize the request into one primary mode before drafting.

- ```bash

- npm run dev

- npm test

+ ```yaml

+ technical_writing_mode:

+ audience: engineers | operators | mixed | unknown

+ source_of_truth: repo | incident-notes | existing-doc | mixed | unknown

+ lifecycle_state: draft | review | rewrite | maintenance

+ docs_surface: markdown-repo | docs-site | wiki | unknown

+ review_need: decision-signoff | operational-accuracy | handoff-clarity | unknown

```

- ## Deployment

- [Deployment instructions]

- ## Contributing

- [Contributing guidelines]

- ## License

+ Use one primary mode per run:

+ - `prd` → product requirement, personas, stories, acceptance criteria, success metrics, risks

+ - `spec` → planned change, goals, constraints, design, rollout, rollback, open questions

+ - `architecture` → system structure, boundaries, interfaces, trade-offs, failure modes

+ - `adr` → one material decision with options and rationale

+ - `runbook` → operate, diagnose, recover, escalate

+ - `migration` → move from old to new safely with validation and rollback

+ - `internal-guide` → implementation-facing explanation for maintainers

- MIT

+ ### Step 2: Confirm audience and route-outs

+ Answer three questions before writing:

+ 1. Who will act on this document?

+ 2. What decision or action should it enable?

+ 3. Which neighboring skills must stay out of scope?

- ````

+ Quick route-out table:

- ### Changelog Template

+ | If the request sounds like... | Use |

+ |---|---|

+ | Publish docs for an API, SDK, webhook, or developer portal | `api-documentation` |

+ | Write a tutorial, onboarding guide, or FAQ | `user-guide-writing` |

+ | Summarize shipped changes or maintain `CHANGELOG.md` | `changelog-maintenance` |

+ | Make slides for a launch, roadmap, or architecture review | `presentation-builder` |

+ | Write launch or product messaging | `marketing-automation` |

+ | Decide the API or feature design before writing docs | `api-design`, `task-planning`, or another planning skill |

- ````markdown

- # Changelog

+ ### Step 3: Gather the minimum technical evidence

+ Do not draft from vibes alone. Pull the smallest credible evidence set first:

+ - current behavior or architecture notes

+ - interfaces, schemas, commands, or operational signals

+ - rollout or operational constraints

+ - known failure modes and recovery steps

+ - unresolved questions or trade-offs

- ## [1.2.0] - 2026-01-15

+ If evidence is missing, label assumptions explicitly instead of pretending the document is authoritative.

- ### Added

- - New feature X

- - Support for Y

+ ### Step 4: Choose the smallest fitting structure

+ Use the mode rules below and only keep the sections that fit the chosen document.

- ### Changed

- - Improved performance of Z

- - Updated dependency A to v2.0

+ ### Step 5: Apply mode-specific writing rules

+ - **Specs** must separate goals from non-goals.

+ - **Architecture docs** must explain boundaries and trade-offs, not every code path.

+ - **ADRs** must capture one decision, not become a full design doc.

+ - **Runbooks** must optimize for fast action under pressure.

+ - **Migration guides** must foreground compatibility, validation, and rollback.

+ - **Internal guides** must explain implementation reality, not customer education or marketing value props.

- ### Fixed

- - Bug where user could not log in

- - Memory leak in background task

+ ### Step 6: Keep it docs-as-code friendly

+ Default to reviewable, repo-friendly writing:

+ - stable headings

+ - concise bullet lists where operators scan

+ - explicit commands, paths, owners, and prerequisites

+ - dated decisions and status for ADR-like docs

+ - links to source-of-truth docs instead of duplicated narrative when possible

- ### Deprecated

- - Old API endpoint /v1/users (use /v2/users)

+ ### Step 7: Run the quality check

+ Before finalizing, verify:

+ 1. The audience is named or obvious.

+ 2. The document states what decision or action it enables.

+ 3. Assumptions and unknowns are labeled.

+ 4. Commands, interfaces, validation, rollback, or escalation are concrete where relevant.

+ 5. Neighboring documentation skills are not being absorbed.

+ 6. The title and section layout match the chosen mode.

- ### Removed

- - Legacy authentication method

+ ### Step 8: Return a brief or the finished artifact

+ Preferred summary shape before full drafting:

- ### Security

- - Fixed XSS vulnerability in comments

+ ```markdown

+ # Technical Writing Brief

- ## [1.1.0] - 2025-10-01

- …

- ````

+ ## Mode

+ - Primary mode:

+ - Why it fits:

+ - Audience:

- ## Writing tips

+ ## Source material used

+ - Repo/docs/evidence:

+ - Assumptions / gaps:

- ### Use active voice

+ ## Draft structure

+ 1. section

+ 2. section

+ 3. section

- ```text

- ✅ Good: "The system sends a notification"

- ❌ Bad: "A notification is sent by the system"

+ ## Writing notes

+ - Key decisions / actions enabled:

+ - Risks / unknowns:

+ - Route-outs kept out of scope:

```

- ### Be concise

- ```text

- ✅ Good: "Click Save to save changes"

- ❌ Bad: "In order to save your changes, you should click on the Save button"

- ```

+ If the user already asked for the finished artifact, produce the chosen document directly with the matching structure above.

- ### Use examples

+ ## Examples

- ````

- ✅ Good:

- "Set the timeout in seconds:

- ```yaml

- timeout: 30

- ```

+ ### Example 1: Internal design doc before implementation

+ **Input**

+ > Write a technical spec for moving our worker queue from Redis lists to Redis streams. Engineers need goals, constraints, rollout, and rollback before coding.

- ❌ Bad:

- "Configure the timeout parameter appropriately"

- ````

+ **Good output direction**

+ - mode: `spec`

+ - audience: engineers

+ - include goals, non-goals, constraints, design, rollout, rollback, open questions

+ - keep API portal publishing out of scope

- ### Break down complexity

+ ### Example 2: Architecture decision capture

+ **Input**

+ > We chose Postgres logical replication over dual writes. Record the decision and alternatives in an ADR.

- ```text

- ✅ Good:

- "To deploy:

+ **Good output direction**

+ - mode: `adr`

+ - capture context, decision, alternatives, consequences, follow-up

+ - keep the document short and decision-focused

- 1. Build the image

- 2. Push to registry

- 3. Update deployment

- 4. Verify rollout"

+ ### Example 3: Incident runbook

+ **Input**

+ > Write a runbook for when the payments worker backlog spikes and retries start timing out.

- ❌ Bad:

- "Deploy by building and pushing the image to the registry, then update

- the deployment and verify the rollout succeeded"

- ```

+ **Good output direction**

+ - mode: `runbook`

+ - include symptoms, immediate checks, operating steps, escalation, rollback / recovery

+ - optimize for operator speed, not essay-style explanation

- ## Common mistakes to avoid

+ ### Example 4: Boundary with API docs

+ **Input**

+ > Refresh our public webhook quickstart and auth troubleshooting page for external developers.

- 1. **Assuming knowledge**: Define terms, explain context

- 2. **Outdated docs**: Keep in sync with code

- 3. **Missing examples**: Always include examples

- 4. **No visuals**: Use diagrams for complex concepts

- 5. **Poor structure**: Use headings and sections

- 6. **Passive voice**: Use active voice

- 7. **Too much jargon**: Write for your audience

- 8. **No version info**: Date docs, note versions

- 9. **Missing error cases**: Document what can go wrong

- 10. **No maintenance**: Update regularly

+ **Good output direction**

+ - route to `api-documentation`

+ - explain that the main job is published developer-facing API docs, not internal technical documentation

## Best practices

- 1. **Write for your audience**: Match their knowledge level

- 2. **Start with why**: Explain the purpose

- 3. **Show, don't just tell**: Use examples

- 4. **Be consistent**: Terminology, style, structure

- 5. **Test your docs**: Can someone follow them?

- 6. **Version your docs**: Track with code versions

- 7. **Use templates**: Consistency across docs

- 8. **Link related docs**: Help readers find more info

- 9. **Update with code**: Docs are part of the code

- 10. **Review regularly**: Quarterly doc review

- ## Tools

- **Diagram tools**:

- - Mermaid (markdown-based)

- - Draw.io

- - Lucidchart

- - PlantUML

- **Documentation platforms**:

- - GitBook

- - Docusaurus

- - MkDocs

- - Sphinx

- **Style checkers**:

- - Grammarly

- - Hemingway Editor

- - Vale

- **Screenshot tools**:

- - Snagit

- - CloudApp

- - Loom (for videos)

- ## Examples (where to look in this skill)

- - **Spec or design write-up:** use the **Technical Specification** and **Detailed Design** patterns in **Step 2** and the **Technical Spec Template** in **Document templates**; fill `[placeholders]` with repo-specific names and decisions.

- - **Runbook or ops doc:** use the **Runbook** block in **Step 2**; replace links, service names, and commands with the user’s environment.

- - **API reference:** use the **API Documentation** block in **Step 2**; add endpoints, request/response bodies, and error tables from the actual API.

- - **Release notes:** use **Changelog Template**; set versions and dates to match the project’s release process.

+ 1. Choose the document mode before writing the body.

+ 2. Keep internal technical docs decision- and action-oriented.

+ 3. Write only the sections the mode needs; do not force every template into every document.

+ 4. Separate internal design / ops docs from API portals, user help, release notes, decks, and GTM copy.

+ 5. Prefer docs-as-code structure: reviewable Markdown, stable headings, and source-linked facts.

+ 6. Label assumptions and unresolved questions explicitly.

+ 7. For runbooks and migrations, make rollback and escalation easy to find.

+ 8. When the request changes audience, route out instead of stretching the internal-docs lane.

- Do not leave HTML comments or “TODO” placeholders in the document you hand off—either complete a section or remove it and say what is out of scope.

+ ## References

+ - [Diátaxis](https://diataxis.fr/)

+ - [Write the Docs — Docs as Code](https://www.writethedocs.org/guide/docs-as-code/)

+ - [Write the Docs — How to write software documentation](https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/)

+ - [Architectural Decision Records](https://adr.github.io/)

+ - [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)