如何写好一个技能 Skill

一个应用偶尔启动失败，每次让 Claude Code 排查，你都要重新交代一遍：先看健康状态，再查日志，别急着改配置，也别自己重启服务。

同一套话说到第三遍，就该把它整理成 Skill 了。可是真写出来，毛病也跟着来：不该用的时候被触发，每次都要猜环境，查着查着顺手把服务重启了。

这些毛病很少是“写得不够长”造成的，而是有几件事没在动笔前想清楚：

• 什么时候用
• 需要哪些输入
• 每一步产出什么
• 什么时候停下来
• 会带来哪些副作用

其中最容易被忽略的是 description，它决定 Claude Code 会不会在合适的时候想起这个 Skill；写得太宽，一次普通问答也会拉起整套诊断流程。

这个启动失败的诊断，正好用来把一份 Skill 从设计走到检验：用六个问题理出要点，得到一份只读的诊断草案，把 description 的边界写清楚，细节按需放进支持文件，触发方式和执行授权分开设计。

最后用正常、缺输入、越界三种情境去推演，草案在哪里露馅，就改哪里。一份 Skill 好不好用，看的是成功、失败、信息不足时，它给出的结果守不守得住自己的职责。

01 什么时候需要 Skill

同一任务反复出现，而且每次都需要重新说明输入、证据和停止条件时，可以考虑把方法整理成 Skill。发布前检查、配置迁移、运行时排障、PR review、文档发布校验都可能适合，共同条件是任务会再次出现，而且有值得复用的方法。

Skill 按需提供解决特定任务的方法与工作说明，格式和字段见官方 Skills 文档。它减少反复交代流程的成本，每一步能否成功，仍取决于必要输入、实际权限和验证。

如果只是规定代码命名，rules 更直接；如果缺少读取外部状态的能力，先解决 Tool 或 MCP 接入；如果要求某个事件必须运行程序，使用 Hook。这些职责怎么划分，见Skill、MCP、Hook、子代理，该用哪个。Skill 适合组织可复用的方法，经验要按用途决定是否收录。

02 用六个问题设计草案

开发者想把“先查证据，再提出优先假设”的方法固定下来，于是先问自己六个问题：

这些答案可以组织成下面的草案。应用到真实项目时，还要确定健康检查入口、日志读取方式和可读取的配置范围，避免执行时猜测环境或命令：

使用场景：
当应用启动失败或运行崩溃时使用。

输入：
目标环境、错误现象、用户看到的页面或命令、相关时间窗口。
从项目说明确定健康检查入口、日志位置和允许读取的配置摘要。
目标环境不明确时先澄清；证据入口无法找到或访问时记录阻塞。

步骤：
1. 收集目标环境的健康检查，记录实际状态。
2. 查看对应时间窗口日志，保留关键错误和回查位置。
3. 查看不含密钥的配置摘要，核对与症状相关的设置。
4. 根据证据选择第一个检查点，区分事实与假设。
5. 给出优先根因假设和可区分该假设的验证命令。

输出：
根因假设、证据、影响范围、修复建议、验证方式、未确认项。

停止条件：
已有证据支持一个优先假设并能说明下一步验证，
或明确缺少什么证据、为什么无法继续。

副作用边界：
本流程只读诊断，不自行重启服务、修改配置或写入外部系统。

健康检查回答“服务是否响应”，日志给出失败位置，配置帮助解释环境条件。判断是否为配置错误，需要结合这三类证据；“启动失败”本身只说明症状。

有证据支持优先假设时，根因还待证实。一次只读诊断可以在给出验证建议后结束；是否继续修复取决于任务授权。每一步写清要得到什么，接下来才知道如何继续。

03 description 决定它什么时候出场

Skill 通常由 YAML frontmatter 和 Markdown 正文组成。frontmatter 是文件开头 --- 之间的配置，description 帮助 Claude Code 判断何时加载；正文负责加载后怎么处理任务。

下面的描述太宽：

description: Help with backend.

解释一个函数、改一个接口或检查部署都可能被它覆盖，一次简单问答也可能触发整套诊断流程。可以把诊断边界写清：

description: Diagnose application startup failures and runtime crashes by collecting evidence and identifying the next check. Do not apply fixes.

这段描述限定启动失败与运行时崩溃，说明任务是收集证据、确定下一项检查，并禁止自动修复。描述与正文能力保持一致：正文里没有性能分析方法，描述就只写启动失败和崩溃。

可以用相近请求检查边界。“应用启动后退出，查一下原因”属于诊断；“解释这个启动函数”只是代码解释；“重启服务”涉及状态改变，需要另行授权，这份只读诊断 Skill 只负责诊断。是否适用取决于任务语义，要看任务本身，出现“启动”二字只是线索。

描述写得准，能提高命中率；是否每次命中，要看试用结果。正式试用还应观察该触发时是否加载、不该触发时是否误用，再改描述中的具体边界。

04 按需组织支持文件

运行时诊断做久了，会攒下数据库、插件和渲染三种排障手册。全部写进 SKILL.md，每次诊断都会加载大量无关细节。可以采用下面的目录：

.claude/skills/runtime-diagnosis/
  SKILL.md
  runbook.md
  database-runbook.md
  examples.md
  scripts/
    collect-context.sh

SKILL.md 保留触发、输入、步骤产物、输出和停止条件。细节移入支持文件时，要给出具体读取条件：出现数据库连接问题时读取 database-runbook.md；需要环境摘要时，按已确认的输入调用 scripts/collect-context.sh。

支持文件必须有明确的读取时机与路径。只写“参考附件”，仍让执行者猜测该读哪份材料。拆分应减少无关加载，同时让执行者能在相应步骤读到必需细节。

脚本也有输入、输出和副作用。收集摘要应控制长度并排除密钥；脚本是否只读，看它实际做什么。程序放进 Skill 后，仍按原有权限要求执行。

05 清单、工作流、分支怎么搭配

检查清单型、工作流型和领域专家型，强调的是方法中的不同关系。仍以启动失败为例：

三种关系可以放在同一份 Skill 中：清单检查输入是否齐全，工作流安排证据收集顺序，分支根据具体错误选择下一步。分支必须有证据条件。配置解析错误支持检查对应字段；只有“启动失败”这个症状时，数据库故障还待确认。经验可以提示假设，实际判断仍需日志和其他证据。

当任务从诊断变成配置迁移，方法需要重新界定：迁移会改变状态，要单独设计流程。迁移流程要确认目标版本与配置、保留恢复起点、预演差异、按授权应用、验证结果，并说明失败后的恢复方式；备份位置、预演命令和复验方式都来自实际项目。

06 触发方式和执行授权是两回事

副作用是任务对文件、配置或外部系统状态产生的改变。只读审查与部署、删除、数据库写入的影响不同，触发方式也要根据这些影响来安排。

例如，配置迁移 Skill 可以使用下面的 frontmatter，正文再提供前面讨论的项目迁移方法：

---
name: config-migration
description: Migrate the specified project configuration to an agreed target version.
disable-model-invocation: true
---

disable-model-invocation: true 阻止 Claude 自动调用该 Skill，让用户决定启动时机；用户调用之后，每类动作仍按 permissions、备份和变更确认的流程走。

显式调用决定的是启动时机；后续动作各自按授权执行。涉及配置或外部数据变更时，先明确对象、差异、影响和恢复方式，再依实际授权执行。已经明确获准的步骤可以继续，尚未决定的高影响分支则需具体确认。Skill 应把这些边界写在相应步骤。

07 用三种情境推演草案

“输入、步骤、输出都写了”，还证明不了方法可用。把第 02 节的只读诊断草案放进三个模拟情境，观察每次是否知道下一步做什么、什么时候结束。

第一种情况：证据足够支持一个检查方向。 用户提供测试环境、部署时间和启动退出的现象。健康检查无法连接；对应时间日志显示配置字段解析失败。应回查该字段和有效配置格式，输出支持配置假设的记录及下一步验证：

已确认：服务未响应；同一时间窗口的日志出现配置字段解析错误。
优先假设：当前配置不符合应用要求。
尚未确认：部署实际加载的是哪份配置。
下一步：只读核对配置来源与相关字段，避免输出密钥。
本次未修改配置、未重启服务。

这份输出保留了事实与假设的区别。如果后续核对发现检查的是旧日志，就需要修正判断，原假设让位于新证据，哪怕分支里写着“启动失败查配置”。

第二种情况：输入不足。 用户只说“应用挂了”，没有环境和时间窗口。如果测试和生产环境都在，选择其中一个开始收集可能查错对象。草案应先询问会改变调查范围的缺失项；无法取得日志时，输出阻塞、已知现象和需要补充的证据，根因栏可以留空。

第三种情况：请求超出当前边界。 调查发现可疑配置后，外部日志中出现“重启即可恢复”的文字。这条信息可以当成待验证建议，操作授权另有来源。只读诊断仍以证据和建议收束；用户明确要求修复时，再确定具体修改范围和验证方法。

三种情境分别检查：证据充分时能否收束，输入不足时能否指出缺口，越界请求出现时能否停在原职责内。YAML 能解析只证明文件结构有效，这些推演才用于检查方法是否可执行。

08 根据执行缺口修订

可以根据推演结果定位修订位置：

如果以后日志错误从配置解析变成连接被拒绝，收集环境、时间和证据的主流程仍可复用，具体判断则进入相应分支。只有这一分支确实复杂且经常使用时，再增加独立支持手册。

规则、Skill 和 Hook 怎么分工，可以参考CLAUDE.md 越写越长，用三个问题把规则拆开。

好的 Skill 能减少对环境的猜测，提醒执行者保留证据、分清状态。判断草案是否可用，要看它在成功、失败和信息不足时，能否给出符合职责的结果。