运行手册设计与编写Skill：把老工程师脑子里的经验，变成人人照着能做的标准操作手册
- 一句话定位：这是一套专门用来“写运行手册”的 AI 技能，它把故障排查、事件响应、例行维护、新人带教四类操作，统一成结构清晰、可直接执行的文档模板。
- 核心能力：提供最小可行手册与全面手册两套结构，内置决策树、预期输出、检查清单、回滚方案、修订历史等要素，并给出目录组织和反模式提示。
- 适用人群：SRE、运维工程师、值班工程师、技术负责人，以及需要沉淀操作经验的技术团队。
- 最大差异点：它不仅给出模板，还给出“好写法”和“差写法”的对照，以及紧急响应、常规维护、知识转移三种常见写作模式，帮助避免写出“重启一下那个东西”式的模糊手册。
- 使用门槛：技能本身不面向用户直接调用（user-invocable: false），由主流程或对话自动调用；用户只需要用自然语言描述服务、任务和痛点，即可获得结构化产出。
该技能叫什么？如何下载安装 AI 技能提升开发效率？
技能中文名：运行手册设计与编写Skill 技能英文名：runbooks-structure 技能ID：14010
它要解决的问题非常具体：团队里最懂系统的人，往往最没时间写文档；而真正需要文档的值班工程师、新同事，又往往在看到一段“检查一下 ingress 就行”的文字后无从下手。结果是同一类故障每次都要找老人救火，事件复盘写不深，知识沉淀不下来。这个技能的作用，就是把“某位老工程师的口头经验”转换成包含前提条件、诊断步骤、决策分支、验证标准、回滚方式和联系信息的可执行手册。
关于安装，需要说明的是，该技能详情中并未提供具体的安装命令、下载地址或收费信息，因此以下为通用思路，具体入口与命令以官方说明为准：
- 确认安装前提：需要一个支持 AI 技能的客户端或平台（例如支持 SKILL 规范的 AI 编程助手、桌面端应用或企业内部技能仓库），并确认当前账号具备技能导入权限。
- 准备技能包：该技能以标准技能目录形式分发，核心是一个描述文件（包含名称、描述、可用工具声明）。本技能声明的可用工具包括 Read（读取）、Write（写入）、Edit（编辑）、Bash（执行命令）、Grep（文本检索）、Glob（文件匹配），说明它需要读取项目文件、写入文档并做检索校验的能力。
- 执行安装：在技能市场按技能ID
14010或英文名runbooks-structure搜索并添加；或通过平台提供的“导入技能/上传技能包”入口上传技能目录。具体操作路径以官方说明为准。 - 验证是否生效：新建一次对话，输入“帮我为订单服务写一份最小可行的故障排查运行手册”。若返回结果稳定包含“概述 / 前提条件 / 步骤 / 验证 / 回滚”五个部分，说明技能已正常加载；若返回的是一段散乱建议，则说明技能未生效，需要检查技能是否已启用。
- 建立目录习惯：安装完成后，建议在仓库中先建立
runbooks/目录，并按templates/、services/、infrastructure/、on-call/的层级规划位置，后续所有生成内容直接写入即可。
该技能的主要功能和特点
- 两套结构化模板：一是“最小可行运行手册”，包含概述、前提条件、步骤、验证、回滚五段，几分钟就能写完一份；二是“全面运行手册模板”，在五段基础上补充最后更新时间、所有者、严重程度、预计时间、何时使用、架构上下文、常见原因、诊断步骤、解决选项、后续行动、相关手册、联系信息、修订历史等要素。
- 面向真实值班场景的写作模式：内置紧急响应（含寻呼、通知利益相关者、开启维护模式、沟通模板）、常规维护（提前一周、提前一天的准备清单，维护中步骤，维护后收尾）、知识转移（学习目标、跟学、实践、实操、认证签字）三类模式。
- 决策树写法：要求把“如果成功走哪步、如果失败走哪步”显式写出，例如“如果 pod 处于 CrashLooping 状态，继续步骤 2；否则跳到步骤 3”，避免手册变成线性流水账。
- 强制预期输出：每段命令都要求给出“预期输出”和“看到异常时该查什么”，例如执行健康检查后应返回 200 OK，出现 connection refused 时应检查安全组、数据库状态与凭据。
- 检查清单化：部署前清单、维护后验证清单、生产部署准入清单等，均以可勾选形式呈现，便于在高压场景下逐项确认。
- 反模式提示：明确指出三类常见写法错误——遗漏上下文、跳过验证步骤、假设读者懂行话，并给出好写法与差写法的对照。
- 工程化的组织方式：给出 runbooks 目录树，按服务、基础设施、值班三类归档，并要求 README 作为索引，避免文档越写越散。
- 可落地的协作要素：修订历史表格、负责人、Slack 频道、升级路径、相关手册互相跳转，让手册具备“维护生命周期”而不只是一次性文档。
与普通文档工具相比，它强在“结构约束”：普通工具给你一张白纸，它给你一套经过运维实践检验的骨架和验收标准。
如何使用该技能？
该技能 user-invocable: false，意味着它通常不作为一个显式命令被手动唤起，而是由主助手或上层技能在处理“写运行手册、写 SOP、写排障文档、写值班手册”这类请求时自动调用。实际使用可以按以下步骤进行：
第 1 步：描述对象与场景 用一句话说明“哪个服务 / 什么任务 / 什么触发条件”。 示例输入：“为 api-gateway 服务的高延迟问题写一份运行手册，触发条件是 P95 延迟超过 500ms 的告警，读者是夜班值班工程师。”
第 2 步：选择模板深度 告诉它你要“最小可行版”还是“全面版”。值班用、要贴进告警系统的手册，选最小可行版；要纳入团队知识库、需要长期维护的，选全面版。
第 3 步：补充环境信息 提供访问方式（VPN、控制台、kubectl 集群名）、常用命令风格、监控工具名称（如 Datadog、CloudWatch、PagerDuty）、沟通渠道（如 #incidents 频道）。信息越具体，产出的步骤越能直接执行。
第 4 步：获取结构化产出 正常产出会按“概述 → 何时使用 → 前提条件 → 上下文 → 诊断步骤 → 解决步骤 → 验证 → 回滚 → 后续行动 → 相关手册 → 联系信息 → 修订历史”组织，并在关键命令后附“预期输出”和“决策点”。
第 5 步：人工校验与落地
逐条检查：命令是否与实际环境一致、验证标准是否可量化（如错误率 < 1%、P95 < 200ms）、回滚是否真的可执行。确认后写入 runbooks/services/<服务名>/<问题>.md，并在 README 索引中登记。
第 6 步：持续迭代 每次事件结束后，在修订历史中追加一行“日期 / 作者 / 更改”，并把新增的诊断分支补进决策树。手册的价值来自持续修订，而不是一次写成。
同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势 | 不足 |
|---|---|---|---|---|---|---|
| runbooks-structure（运行手册设计与编写Skill） | 结构化运行手册专用生成技能 | 双模板体系、决策树、预期输出、检查清单、反模式校验、目录组织建议 | 需在支持技能的 AI 平台导入，按技能ID或名称添加；具体以官方说明为准 | 故障排查、事件响应、例行维护、值班手册、新人带教 | 结构约束强，产出可直接落地；覆盖协作与维护要素 | 不直接执行运维操作，仅负责“写清楚”；环境信息需人工补充 |
| 通用大模型对话直接写 SOP | 通用文本生成 | 自由生成任意格式文档 | 零门槛，打开即用 | 一次性、临时性的文档草稿 | 灵活、无学习成本 | 结构不稳定，容易漏掉验证与回滚；每次产出风格不一致 |
| Confluence / Notion 等文档平台模板 | 文档协作与知识库 | 页面模板、权限管理、搜索、评论协作 | 需部署或订阅，配置模板需要管理员 | 团队知识库长期运营 | 协作与检索能力强 | 模板本身不会“教你怎么写”，质量取决于写作者经验 |
| 传统 Word / Markdown 模板库 | 静态文档模板 | 固定格式占位 | 极低，下载即用 | 制度类、合规类文档 | 简单、可控 | 无智能补全，决策树与预期输出仍需人工编写 |
该技能的典型应用场景与实际体验情况
场景一：值班工程师夜间排障 角色是刚接手值班的一线工程师，痛点是凌晨告警时不知道该先看哪里、看到报错如何判断。使用方式是让技能生成“诊断步骤 + 决策点 + 预期输出”的手册，例如先查 pod 状态，若 CrashLooping 则查日志、若 Pending 则查节点资源、若 Running 则查 DNS。实际体验：上手难度低，产出逻辑接近资深工程师的思路，显著减少“打电话找人”的次数；注意事项是命令中的命名空间、标签选择器必须替换为真实值。
场景二：SRE 处理生产事件 角色是事件负责人，痛点是高压下容易漏掉通知和记录。使用“紧急响应”模式生成的手册会包含“5 分钟内完成”的立即行动区、每 10 分钟一次的沟通模板（含影响面与预计恢复时间）。实际体验：沟通模板尤其好用，能避免事件频道里信息碎片化；注意事项是寻呼与升级路径需按团队实际值班表填写。
场景三：月度数据库例行维护 角色是运维负责人，痛点是维护窗口前后的准备与收尾容易遗漏。手册会拆成“1 周前 / 1 天前 / 维护步骤 / 维护后”四段，包含快照创建、更新应用、监控重启、验证服务健康、发布完成通知。实际体验：检查清单形式非常适合多人协作时逐项确认；注意事项是时间表与时区必须明确标注。
场景四：新人入职知识转移 角色是新入职工程师或带教人，痛点是“跟着看一遍就上手”缺乏验收标准。手册模式包含学习目标、跟学、实践、实操三阶段，以及“完成 5 次暂存部署 + 1 次有监督生产部署”的认证清单。实际体验：把模糊的“熟悉部署流程”变成可勾选的成长路径，带教效率提升明显；注意事项是认证人签字栏需真正被执行，否则容易流于形式。
该技能能为用户带来的价值
第一，降低文档门槛。写运行手册最难的不是写，而是知道该写什么。技能通过固定骨架把“结构问题”一次性解决，让不擅长写作的工程师也能产出合格手册。
第二，缩短平均恢复时间。手册中包含决策树与预期输出，值班人员无需在告警时刻临场推理，按分支走即可定位问题，减少排查过程中的试错。
第三，减少对关键人员的依赖。把口头经验转为文档后，同类问题不再必须找同一个人，团队整体的响应能力从“个人能力”变成“组织能力”。
第四，提升事件复盘质量。修订历史、后续行动清单、相关手册互链，让每次事件都能沉淀为文档增量，形成正向循环。
第五，降低新人上手成本。知识转移模式的认证清单，把“多久能独立值班”从主观判断变为客观标准。
长期来看，一个持续维护的运行手册库，本身就是团队最值钱的资产之一；而这个技能解决的正是“从 0 到 1 写出第一版”和“从 1 到 N 保持结构一致”这两个最难坚持的环节。
常见问题 FAQ
Q1：这个技能怎么安装？需要付费吗？
在支持 AI 技能的平台中，按技能ID 14010 或英文名 runbooks-structure 搜索添加，或通过技能导入入口上传技能包即可。具体安装路径、是否需要订阅或付费，以官方说明为准，本技能详情中未提供价格信息。
Q2：为什么它标着 user-invocable: false？我是不是用不了？ 不是用不了，而是它作为一项“后台能力”存在，由主流程在识别到写运行手册、写 SOP、写排障文档等意图时自动调用。你只需要用自然语言提出需求，不需要记住特殊命令。
Q3：它会不会直接帮我执行 kubectl 或改生产配置？ 不会。它的定位是“写清楚文档”，声明的工具（读、写、编辑、执行命令、检索、文件匹配）主要用于读取项目文件、写入手册文档和做一致性校验。真正的运维操作仍由人执行。
Q4：适合谁用？小团队有必要写运行手册吗？ 适合 SRE、运维工程师、值班人员、技术负责人。团队越小越有必要——人少意味着没有冗余人力去“救火”，一份写得清楚的排障手册能直接减少半夜被叫起来的次数。
Q5：和直接用大模型写 SOP、或用 Confluence 模板相比，怎么选？ 如果只是偶尔写一份文档，通用对话足够；如果要把运行手册作为团队长期资产来运营，需要结构统一、可验证、可回滚、可追溯修订，那么这个技能的结构约束和反模式校验会明显更省心。两者也可以组合：用它生成初稿，再放进团队的文档平台协作维护。