technical-writing

어떤 스킬인가요?

Write internal technical documentation for engineers and operators: technical specs, architecture docs, ADRs, runbooks, migration plans, and developer-facing implementation guides. Use when the main job is capturing a technical decision, system boundary, operating procedure, or rollout path for builders and maintainers. Triggers on: tech spec, design doc, architecture doc, ADR, runbook, migration guide, implementation guide, rollout doc, operational guide, and internal technical writing. End-user onboarding guides, tutorials, FAQs, and help-center flows belong here too. Route API portals to `api-documentation`, release notes to `changelog-maintenance`, decks to `presentation-builder`, and GTM messaging to `marketing-automation`.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

{
  "skill_name": "technical-writing",
  "evals": [
    {
      "id": 1,
      "prompt": "Write a technical spec for migrating our background jobs from cron to a queue worker system. Engineers need goals, constraints, rollout, rollback, and open questions before implementation starts.",
      "expected_output": "The skill activates in spec mode and structures the work around goals/non-goals, constraints, design, rollout, rollback, and open questions.",
      "assertions": [
        "Output classifies the request as a technical spec or equivalent pre-implementation design mode",
        "Output includes rollout and rollback guidance",
        "Output does not route this request to changelog-maintenance"
      ]
    },
    {
      "id": 2,
      "prompt": "Record an ADR explaining why we chose Postgres logical replication over dual writes for cross-region sync.",
      "expected_output": "The skill activates in ADR mode and keeps the document focused on context, decision, alternatives, and consequences.",
      "assertions": [
        "Output classifies the request as ADR mode",
        "Output includes alternatives considered and consequences",
        "Output does not expand into a full tutorial or API portal workflow"
      ]
    },
    {
      "id": 3,
      "prompt": "Create a runbook for when the payments worker backlog spikes and retries start timing out. Operators need immediate checks, mitigation steps, escalation, and recovery guidance.",
      "expected_output": "The skill activates in runbook mode and prioritizes operator action over essay-style explanation.",
      "assertions": [
        "Output classifies the request as runbook mode",
        "Output includes immediate checks, escalation, and recovery or rollback",
        "Output is framed for operators rather than end users"
      ]
    },
    {
      "id": 4,
      "prompt": "Write a beginner tutorial with screenshots that shows customers how to export their data.",
      "expected_output": "The skill handles the request in end-user guide mode because it is onboarding/help content rather than an internal spec.",
      "assertions": [
        "Output selects end-user guide mode instead of an internal spec/ADR/runbook shape",
        "Output explains the boundary with end-user tutorials",
        "Output does not claim this is an internal spec, ADR, runbook, migration guide, or internal developer guide"
      ]
    },
    {
      "id": 5,
      "prompt": "Refresh our public webhook quickstart and auth troubleshooting page for external developers using the new signing flow.",
      "expected_output": "The skill routes the request to api-documentation because the main job is published developer-facing API documentation.",
      "assertions": [
        "Output routes the request to api-documentation or explicitly declines technical-writing as the main skill",
        "Output explains that published API/SDK/docs-portal work is out of scope for technical-writing",
        "Output does not frame the request as an internal spec, ADR, runbook, migration guide, or internal developer guide"
      ]
    },
    {
      "id": 6,
      "prompt": "Update our release notes and CHANGELOG.md for the v4.2 rollout, including upgrade notes for customers and a short summary for developers.",
      "expected_output": "The skill routes the request to changelog-maintenance because the main job is release-history and audience-specific release communication.",
      "assertions": [
        "Output routes the request to changelog-maintenance or explicitly declines technical-writing as the main skill",
        "Output explains the boundary with release notes or CHANGELOG.md maintenance",
        "Output does not claim the request is primarily an internal spec, architecture doc, ADR, runbook, or internal guide"
      ]
    }
  ]
}

# Docs-as-Code and Maintenance Notes

## Why this matters
Write the Docs frames docs-as-code as using the same tools and workflows as software development. In practice that means internal technical docs should behave like maintained artifacts, not one-off prose dumps.

## Practical rules
1. Keep docs close to the system they describe when possible.
2. Prefer reviewable Markdown or text formats over opaque binaries for technical docs.
3. Record dates, status, and owners for decision-heavy documents.
4. Link to source-of-truth code, dashboards, or commands instead of copying volatile details everywhere.
5. Update the doc when a rollout, runbook, or migration path changes materially.

## Good patterns by mode
- **Spec**: version alongside the implementation branch or proposal directory.
- **Architecture doc**: keep higher-level than code comments, but revisit after major topology changes.
- **ADR**: one file per decision; immutable record plus follow-up links works better than silent rewrite.
- **Runbook**: optimize for incident scanning; short sections beat dense narrative.
- **Migration guide**: keep preconditions and validation checkpoints near the step list.

## Maintenance triggers
Refresh the document when:
- the implementation plan changed materially
- operational commands or owners changed
- a migration gained new compatibility constraints
- an ADR was superseded by a later decision
- the document keeps being explained verbally because the written version is too vague

## Anti-patterns
- giant catch-all docs that combine tutorial, reference, marketing, and ops content
- stale commands with no verification note
- copying API portal content into an internal spec instead of linking it
- hiding rollback or escalation details at the bottom of a long narrative

# Technical Writing Modes and Boundaries

Use `technical-writing` for **internal technical documentation**. The fastest way to avoid overlap is to classify the document by the action it enables.

## Canonical modes

### 1. Technical spec
Use when a team needs a pre-implementation design artifact.

Typical signals:
- goals / non-goals
- scope boundaries
- constraints
- rollout / rollback planning
- open questions before coding

### 2. Architecture document
Use when the goal is explaining system structure, boundaries, and trade-offs.

Typical signals:
- components and responsibilities
- request / data flow
- integration boundaries
- failure modes and operational concerns

### 3. ADR
Use when a single meaningful decision needs a durable record.

Typical signals:
- options considered
- rationale for the chosen approach
- consequences and follow-up actions
- decision status and date

### 4. Runbook
Use when someone must operate, diagnose, recover, or escalate.

Typical signals:
- symptoms and checks
- access requirements
- standard operating procedure
- escalation path
- rollback or recovery

### 5. Migration guide
Use when moving from an old system/state to a new one.

Typical signals:
- compatibility or breaking changes
- step ordering
- validation after each stage
- rollback path
- communication notes

### 6. Internal developer guide
Use when maintainers need implementation-facing explanation that is not an end-user tutorial.

Typical signals:
- local development workflow
- subsystem concepts
- ownership and boundaries
- operational or implementation pitfalls

## Boundary table

| If the request is mainly about... | Use |
|---|---|
| Published API docs, OpenAPI reference, SDK examples, developer portal UX | `api-documentation` |
| End-user onboarding, screenshots, how-to guides, help-center flows, FAQs | owned here, in end-user guide mode |
| Release notes, semantic versioning, CHANGELOG.md hygiene | `changelog-maintenance` |
| Deciding the API or feature design before turning it into docs | `api-design`, `task-planning`, or a planning skill |

## Common failure modes
- Turning an ADR into a full 12-section design doc
- Writing a runbook like an essay instead of an action checklist
- Mixing internal developer guidance with customer-facing tutorial tone
- Using `technical-writing` as a fallback when the request is actually about API publishing or changelog upkeep

# Technical Writing Mode Structures

Use these as default section skeletons after `technical-writing` picks the primary mode.

## Technical spec
```markdown
# <Feature / Change> Technical Specification

## Overview
## Problem
## Goals
## Non-goals
## Constraints
## Proposed design
## Interfaces / dependencies
## Risks and mitigations
## Rollout and rollback
## Open questions
```

## Architecture document
```markdown
# <System> Architecture

## Context
## Responsibilities and boundaries
## Components
## Data / request flow
## Key decisions
## Failure modes
## Operational considerations
## Known limits / future changes
```

## ADR
```markdown
# ADR: <Decision title>

- Status:
- Date:
- Owners:

## Context
## Decision
## Alternatives considered
## Consequences
## Follow-up actions
```

## Runbook
```markdown
# <Service> Runbook

## Purpose
## Preconditions / access
## Signals and symptoms
## Immediate checks
## Standard operating procedure
## Escalation path
## Rollback / recovery
## References
```

## Migration guide
```markdown
# <Migration> Guide

## Scope
## Preconditions
## Compatibility / breaking changes
## Step-by-step migration
## Validation
## Rollback
## Communication notes
```

## Internal developer guide
```markdown
# <Topic> Developer Guide

## What this system does
## When to use / not use it
## Key concepts
## Local development or operational workflow
## Common pitfalls
## Troubleshooting / escalation
## Related docs
```

# Technical Documentation Quality Checklists

## Universal checklist
- The audience is explicit.
- The document tells the reader what decision or action it enables.
- Assumptions and unknowns are labeled.
- Terms are consistent with the codebase or operating environment.
- Related docs are linked instead of duplicated.

## Spec checklist
- Goals and non-goals are both present.
- Constraints are concrete.
- Risks and mitigations are named.
- Rollout and rollback are included when the change can ship.
- Open questions are separated from accepted decisions.

## Architecture doc checklist
- Component boundaries are clear.
- Interfaces / data flow are explained.
- Trade-offs and limits are named.
- Security / performance / operations notes are included only where relevant.
- The doc does not turn into a complete code walkthrough.

## ADR checklist
- Context explains why the decision matters now.
- Alternatives considered are real, not strawmen.
- Consequences include downsides.
- Status and date are recorded.
- Follow-up actions are explicit.

## Runbook checklist
- Preconditions and access requirements are listed first.
- Signals / symptoms are easy to scan.
- Immediate checks come before deep background.
- Recovery / rollback / escalation are explicit.
- The procedure is executable under time pressure.

## Migration checklist
- Scope and compatibility notes appear before the steps.
- Validation checkpoints exist.
- Rollback criteria are clear.
- Communication dependencies are named.
- Breaking changes are not hidden in footnotes.

## Internal guide checklist
- Ownership / boundary / when-to-use is stated early.
- Local or operational workflow is concrete.
- Common pitfalls are called out.
- Reader assumptions match engineer / maintainer skill level.
- It avoids end-user tutorial language unless intentionally linking outward.

---
name: technical-writing
description: >
  Write internal technical documentation for engineers and operators: technical
  specs, architecture docs, ADRs, runbooks, migration plans, and
  developer-facing implementation guides. Use when the main job is capturing a
  technical decision, system boundary, operating procedure, or rollout path for
  builders and maintainers. Triggers on: tech spec, design doc, architecture
  doc, ADR, runbook, migration guide, implementation guide, rollout doc,
  operational guide, and internal technical writing. End-user onboarding guides, tutorials, FAQs, and
  help-center flows belong here too. Route API portals to
  `api-documentation`, release
  notes to `changelog-maintenance`, decks to `presentation-builder`, and GTM
  messaging to `marketing-automation`.
allowed-tools: Read Write Edit Glob Grep
compatibility: >
  Best for repositories and docs-as-code workflows where the output lives in
  Markdown, ADR directories, architecture docs, runbooks, migration docs, or
  internal knowledge bases.
license: MIT
metadata:
  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

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

`technical-writing` is the documentation-cluster anchor for:
- technical specs
- architecture docs
- ADRs / decision records
- runbooks and incident procedures
- rollout / rollback / migration guides
- developer-facing implementation or maintenance guides

Read these support docs before choosing the mode or boundary:
- [references/document-modes-and-boundaries.md](references/document-modes-and-boundaries.md)
- [references/mode-structures.md](references/mode-structures.md)
- [references/quality-checklists.md](references/quality-checklists.md)
- [references/docs-as-code-and-maintenance.md](references/docs-as-code-and-maintenance.md)

## When to use this skill
- A team needs a technical spec before implementation starts
- 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

## When not to use this skill
- **Published API docs, SDK docs, OpenAPI reference, developer portal content** → `api-documentation`
- **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: Classify one primary mode
Normalize the request into one primary mode before drafting.

```yaml
technical_writing_mode:
  primary_mode: spec | architecture | adr | runbook | migration | internal-guide
  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
```

Use one primary mode per run:
- `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

### 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:

| 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 | owned here, in end-user guide mode |
| 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 |

### 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

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

### Step 4: Choose the smallest fitting structure
Use [references/mode-structures.md](references/mode-structures.md) and only keep the sections that fit the chosen mode.

### 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.

### 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

### 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.

### Step 8: Return a brief or the finished artifact
Preferred summary shape before full drafting:

```markdown
# Technical Writing Brief

## Mode
- Primary mode:
- Why it fits:
- Audience:

## Source material used
- Repo/docs/evidence:
- Assumptions / gaps:

## Draft structure
1. section
2. section
3. section

## Writing notes
- Key decisions / actions enabled:
- Risks / unknowns:
- Route-outs kept out of scope:
```

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

## Examples

### 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.

**Good output direction**
- mode: `spec`
- audience: engineers
- include goals, non-goals, constraints, design, rollout, rollback, open questions
- keep API portal publishing out of scope

### Example 2: Architecture decision capture
**Input**
> We chose Postgres logical replication over dual writes. Record the decision and alternatives in an ADR.

**Good output direction**
- mode: `adr`
- capture context, decision, alternatives, consequences, follow-up
- keep the document short and decision-focused

### Example 3: Incident runbook
**Input**
> Write a runbook for when the payments worker backlog spikes and retries start timing out.

**Good output direction**
- mode: `runbook`
- include symptoms, immediate checks, operating steps, escalation, rollback / recovery
- optimize for operator speed, not essay-style explanation

### Example 4: Boundary with API docs
**Input**
> Refresh our public webhook quickstart and auth troubleshooting page for external developers.

**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. 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.

## 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/)

N:technical-writing
D:Write internal technical documentation for engineers and operators: technical specs, architecture docs, ADRs, runbooks, migration plans, and developer-facing implementation guides. Use when the main job is capturing a technical decision, system boundary, operating procedure, or rollout path for builders and maintainers. Triggers on: tech spec, design doc, architecture doc, ADR, runbook, migration guide, implementation guide, rollout doc, operational guide, and internal technical writing. End-user onboarding guides, tutorials, FAQs, and help-center flows belong here too. Route API portals to `api-documentation`, release notes to `changelog-maintenance`, decks to `presentation-builder`, and GTM messaging to `marketing-automation`.
G:technical-writing docs spec architecture adr runbook migration developer-docs
U[6]:
  Technical specs before implementation
  Architecture docs and ADRs
  Runbooks and incident procedures
  Migration and rollout guides
  Internal developer guides
  Boundary routing across documentation skills
S[4]{n,action}:
  1,Classify one primary mode
  2,Gather technical evidence
  3,Use the smallest fitting structure from references/mode-structures.md
  4,Run the quality check and keep route-outs explicit