---
id: gh-writing-runbooks
name: "writing-runbooks"
url: https://skills.yangsir.net/skill/gh-writing-runbooks
author: riekelt
domain: writing
tags: ["runbook", "sop", "documentation", "troubleshooting", "migration"]
install_count: 17200
rating: 4.60 (120 reviews)
github: https://github.com/riekelt/technical-writer/tree/main/plugins/technical-writer/skills/writing-runbooks
---

# writing-runbooks

> 此技能用于编写运维文档，包括runbook、设置指南、发布流程、迁移指南、弃用指南、故障排查条目等。它提供runbook骨架、风险图例、症状优先的故障排查格式和迁移指南规则，确保在时间压力下可快速执行。适合任何需要按步骤执行的文档场景。

**Stats**: 17,200 installs · 4.6/5 (120 reviews)

## Before / After 对比

### 故障处理时间对比

**Before**:

用户在没有这个技能之前，依赖个人记忆或零散笔记处理故障。面对突发事故时，需要现场摸索步骤，查找命令和责任人，经常遗漏关键回滚步骤，平均处理时间长达数小时，且容易因操作顺序错误导致二次故障。

**After**:

此技能提供症状优先、步骤清晰、带风险图例和回滚方案的runbook。用户按照文档即可快速定位问题并执行操作，无需临场研究，平均故障处理时间显著缩短，操作错误率大幅下降。

| Metric | Before | After | Change |
|---|---|---|---|
| 平均故障恢复时间 | 120分钟 | 25分钟 | -79% |
| 操作错误率 | 30% | 5% | -83% |

## Readme

# Writing runbooks

**REQUIRED BACKGROUND:** the `technical-writing` skill (hard rules, truth rules, style).

## Overview

A runbook is read by someone in a hurry, often mid-incident. Every rule here serves that reader: order, one action per step, copy-pasteable commands, and danger marked where the eye already is.

Write from a real run: every step one actually taken, every failure named one that actually happened. A procedure imagined at the desk is a draft, not a runbook. Publish a partially exercised procedure with per-branch honesty: the runbook names the variant that has not run yet, marks that branch draft, and asks its first real runner to report back. A procedure with no real run behind any branch is a draft outright. When a value the commands need is genuinely unknown, the placeholder stays visibly bracketed rather than invented, and gets filled from a real run before publishing; truth outranks paste-readiness.

## When to invoke, and not

Invoke for anything a person will execute: runbooks, setup and release procedures, troubleshooting entries, operational checklists, and the operator-facing strings inside a system. Do NOT invoke for design rationale (`writing-design-docs`) or for reference material nobody executes. If the procedure has not been run at least once, either run it first or label the document a draft; publishing an untested procedure as a runbook is the defect, not the labeling.

## Structure

- Title carries the scope: "MVP runbook (Reddit)", "Release runbook".
- Open with what this document is relative to its siblings: "this doc is the sequence; deep detail per step lives in X." State what it does NOT cover.
- **Legend up front** when steps differ in risk, applied to every command: safe to run anytime / operator-only (writes to production) / manual step outside the terminal. Tags combine where a step is more than one thing.
- **TL;DR happy path first**, then the same steps broken out as numbered sections for when the reader needs only one.
- Version-pinned prerequisites before any command, each with a check command to confirm it.
- Numbered ordinal steps (not bullets), one action each, present tense or imperative, with a visible actor.
- Every command copy-pasteable as-is, with concrete example values ("common paths: `/public_html/`, `/www/`"). Label variants inside the code block:

```bash
# safe mode
app sync run --channel=reddit --limit=100

# live mode (writes to the provider)
app sync run --live --approval-token=...
```

- Ordered steps state the consequence of wrong ordering inline: "deploy jar, then DB cleanup; wrong order = silent data loss."
- Every state-changing procedure names its rollback, or states plainly that none exists and what that means.
- End with a "verify it worked" section: the observable end state and the command that proves it.
- Mark the preferred path "(recommended)" when several paths exist; document UI and CLI for the same task side by side rather than twice.
- If the runbook will shrink when tooling lands, say so: "when X lands, steps 2 to 4 become one command and this document keeps only the judgment."

## Troubleshooting entries

Symptom-first, because the reader arrives with an error message and no vocabulary:

```markdown
## <symptom as the user sees it>
**Symptom**: verbatim error strings (searchable)
**Cause**: ...
**Fix**: exact commands
```

Order diagnostic steps cheapest first. Group entries by failure class. Cross-link the deeper doc instead of inlining it.

## Migration and deprecation guides

A migration guide is a runbook whose subject is the change itself. Everything above applies, plus five rules of its own. Each surrounding document has its own skill: the argument for the migration is a design doc (`writing-design-docs`), the decision to deprecate is an ADR (`recording-decisions`), the announcement is a changelog entry (`writing-changelogs`). This section covers the guide the reader executes.

1. **History is the content here, stated positively.** The before/after comparison is the job, not a violation: this is the document class the no-history hard rule explicitly carves out. Write "the tag now replaces the manual version bump" freely; that sentence is banned everywhere else and load-bearing here.
2. **The mapping table is the core artifact.** Readers arrive knowing the old world; give them old → new per behavior, config key, command, or API, one row each. Prose explains the rows that need it; the table carries the migration.
3. **Rollback is mandatory, per step.** Every step names its undo, or states plainly that it is irreversible and what that means for the ordering around it. A migration guide without rollback paths is a proposal to strand people mid-migration.
4. **The deprecation contract carries dates.** What stops working, on which date, what happens to stragglers, and where the escape hatch is until then. "Will be removed in a future release" names no date and is banned here.
5. **Born with an expiry.** A migration guide is temporary by design: when the migration completes, the owner reclassifies it as historical and adds the superseded banner pointing at the current-state documentation, never deleting it silently. State the completion condition in the guide itself.

## Operator-facing strings

Error messages and log lines are runbook prose with the shortest reading window: keep remediation specific and actionable, and make error states visible rather than letting workflows appear healthy.


---
*Source: https://skills.yangsir.net/skill/gh-writing-runbooks*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-writing-runbooks/markdown*