关于 writing-runbooks
用于撰写运维手册、设置与发布流程、故障排查条目和检查清单的技能。它强调以实际执行为依据，提供有序步骤、可复制命令、回滚方式和结果验证。
主要功能
- 01按顺序组织运维步骤
- 02可复制命令并标明执行者
- 03前置条件与风险标记
- 04回滚方式与最终状态验证
- 05按症状组织故障排查
适用场景
- 01编写发布流程
- 02记录故障排查方法
- 03准备运维检查清单
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/writing-runbooks确认已加载。
详细介绍
编写运行手册
必需背景：technical-writing 技能（硬性规则、真实性规则、风格）。
概述
读者通常很赶时间，甚至可能正处于事故处理中。每份运行手册都应按顺序编写，每个步骤只执行一项操作，可直接复制粘贴，并在读者视线所在处标明危险。
根据真实操作编写：每个步骤都必须是实际执行过的操作，每种故障都必须是实际发生过的故障。在桌面上设想的流程只是草稿，不是运行手册。经过部分演练的流程可以发布，但必须如实标明各分支的状态：指出尚未运行的变体，将该分支标为草稿，并请首次实际执行该分支的人反馈。任何分支都没有实际运行过的流程，完全属于草稿。如果确实不知道命令所需的某个值，就保留醒目的方括号占位符，绝不可凭空编造；发布前应在实际运行时填写该值。真实性优先于可直接粘贴执行。
何时使用，以及何时不使用
凡是要由人员执行的内容，都应使用此技能：运行手册、设置和发布流程、故障排查条目、运维检查清单，以及系统中面向操作人员的字符串。对于设计原理（writing-design-docs）或无人执行的参考资料，请勿使用。如果某流程从未至少运行过一次，就先运行一次，或者将文档标为草稿；未经测试的流程被当作运行手册发布，问题在于流程本身，而不在于标注方式。
结构
- 标题应明确范围：“MVP 运行手册（Reddit）”“发布运行手册”。
- 开头说明本文与相关文档的关系（“本文说明操作顺序；每个步骤的详细信息见 X”），并指出本文不涵盖的内容。
- 开篇提供图例，说明各步骤的风险类型，并适用于每条命令：可随时安全运行／仅限操作人员执行（会写入生产环境）／终端外的手动步骤。若某步骤属于多种类型，应组合标记。
- 先给出简要的理想操作路径，再用编号章节列出相同步骤，供只需查看特定步骤的读者使用。
- 在任何命令之前，列出锁定版本的前置条件，并为每项提供检查命令。
- 使用有序编号步骤，每步只执行一项操作；采用现在时或祈使语气，并明确标出执行者。
- 每条命令都必须可直接复制粘贴执行，并使用具体的示例值（“常见路径：
/public_html/、/www/”）。在代码块中标明不同变体：
# safe mode
app sync run --channel=reddit --limit=100
# live mode (writes to the provider)
app sync run --live --approval-token=...
- 有序步骤应就地说明操作顺序错误会导致什么后果：“先部署 jar，再清理 DB；顺序错误会导致数据悄然丢失。”
- 每个会改变状态的流程都必须说明回滚方法；如果没有回滚方法，就明确说明这一点及其影响。
- 结尾添加“验证是否成功”部分，说明可观察到的最终状态，以及用于证明该状态的命令。
- 如果存在多种路径，首选路径应标为“（推荐）”；同一任务的 UI 和 CLI 应并列说明，而不是重复编写。
- 如果工具上线后运行手册会缩短，请说明：“X 上线后，步骤 2 到 4 将合并为一条命令，本文仅保留判断说明。”
故障排查条目
以症状为先：
## <symptom as the user sees it>
**Symptom**: verbatim error strings (searchable)
**Cause**: ...
**Fix**: exact commands
按诊断成本从低到高排列步骤。按故障类别分组条目。链接到详细文档，不要将其内容直接写入本文。
迁移与弃用指南
迁移指南是一份以变更本身为主题的操作手册：以上所有要求均适用，此外还有五条专属规则。迁移的论据写在设计文档中（writing-design-docs），弃用的决定记录在 ADR 中（recording-decisions），公告写在变更日志条目中（writing-changelogs）；本节只涵盖读者实际执行的指南。
- 历史是这里的内容，应正面陈述。 前后对比是本指南的职责，不算违规：这种文档类型正是「禁止历史回顾」这一硬性规则明确允许的例外。可以直接写「现在由标签取代手动提升版本号」；这句话在其他任何地方都禁止出现，但在这里不可或缺。
- 映射表是核心产物。 按行为、配置键、命令或 API 逐项列出新旧对应关系，每项一行。对确实需要说明的行用文字解释；迁移过程由表格承载。
- 每个步骤都必须说明回滚方式。 每个步骤都要写明如何撤销，或者明确说明该步骤不可逆，以及这会如何影响前后步骤的安排。
- 弃用约定必须写明日期。 哪些内容何时停止工作，届时未完成迁移的用户会受到什么影响，以及在此之前可通过何处绕过限制。「将在未来版本中移除」没有给出具体日期，在这里禁止使用。
- 编写时即设定失效条件。 迁移完成后，负责人应将指南重新归类为历史文档，并添加指向当前状态文档的已被取代横幅，绝不能悄然删除。必须在指南中写明完成条件。
面向操作人员的字符串
错误消息和日志行是阅读窗口最短的操作手册文字：补救措施应具体且可执行，并让错误状态清晰可见，而不是让工作流看起来运行正常。