write-great-skill

编写出色的技能

技能是一个文件夹，用来教 Agent 执行一套它无法自行掌握的流程。只有在遇到相应情况时，Agent 才会加载它。你的任务是：把用户脑中的流程梳理出来，区分判断与操作，然后整理成一个能在合适请求下触发的文件夹。

步骤

1. 访谈。 每次只问一个问题，并附上你建议的答案：

   • 触发条件： 什么情况会启动这项任务？用户会输入哪些确切措辞？收集 3-5 种真实说法。
   • 知识： 用户知道哪些模型不知道的内容？命令、路径、步骤顺序、系统名称、常见原因。
   • 禁止事项： 哪些事绝不能发生？每个答案都要变成硬性规则或注意事项。
   • 操作步骤： 哪些步骤每次都相同（命令、检查、固定格式的文件）？每项都要做成脚本。
   • 存放位置： 仅限此仓库（通过 git 共享的 .claude/skills/<name>/），还是适用于所有仓库（~/.claude/skills/<name>/）？其他工具也有采用相同格式的技能文件夹。

   如果用户已经提供了材料（检查清单、操作手册、文档），或者没人能回答（无头模式运行），就从材料中提取答案，写下你的假设，然后继续。满足以下条件即可完成：能列出每个步骤，并标明它属于判断还是机械操作。

2. 先编写描述。 Agent 决定是否加载技能时只能看到描述；描述含糊就不会被选中。

   • 用面向模型的语言，采用用户的措辞。第一句话用不超过 57 个字符概括任务（Hermes 只显示这么多）。接着写 Use when …，列出步骤 1 中的说法，再说明技能会做什么以及绝不会做什么。
   • 不超过 1,024 个字符（Agent Skills 规范的限制）。Claude Code 会将列表截断在 1,536 个字符。
   • 不会被选中：帮助处理部署。 会被选中：部署到生产环境或预发布环境。Use when 用户说 deploy、ship、release、push to prod 或 roll back。

   满足以下条件即可完成：步骤 1 中的每种说法都出现在描述中，或有近似说法。

3. 根据 references/skill-template.md 起草文件夹。 SKILL.md 是简短的入口文件（尽量少于 100 行）；scripts/ 存放机械操作；references/ 存放仅某个步骤需要的长篇材料；examples/ 存放一个完整示例。只有在步骤指引 Agent 查看辅助文件时，Agent 才会读取该文件。

   • 判断写成指令，操作写成脚本。 模型并非确定性系统：用散文写出的每个步骤每次执行都可能不同。将命令序列、检查和固定格式的文件放入 scripts/，并在 SKILL.md 中使用准确的命令行调用。
   • 以技能名称命名执行技能主要操作的脚本（scripts/<name>.sh），每个辅助脚本则按其步骤命名（scripts/<step>.sh，例如预检脚本）。
   • 脚本遇到第一个错误就停止（set -euo pipefail），检查参数和前置条件，并打印每个步骤。执行 push、打标签、部署、发布或发送操作的脚本默认进行 dry run，只有使用 --yes 才会实际执行；SKILL.md 必须说明先展示 dry run 并获得批准。
   • 每个步骤都要包含：用祈使句描述操作、提供准确的命令、路径或名称，然后写上 Done when …，并附上 Agent 可以验证的检查项。
   • 在需要相应参考资料的步骤中链接该资料，只需一层链接。
   • 添加 ## Gotchas，纳入步骤 1 中所有“禁止事项”以及用户提到的所有陷阱。

   满足以下条件即可完成：每个机械操作步骤都通过脚本调用；每个脚本都通过 bash -n（或其语言对应的语法检查），且执行 dry run 或 --help 时没有副作用。要实际测试 git push，请将目标指向本地裸克隆（git clone --bare . <tmp>/origin.git）。绝不要用用户的真实账户（云服务、密码管理器、支付服务提供商、生产环境）测试脚本：应改为查看工具的 --help。

4. 删掉 Agent 已经知道的内容。 对每一行都问：没有这行，Agent 还会这样做吗？像“编写整洁的代码”“使用有意义的名称”或“遵循最佳实践”这样的内容毫无影响，删掉它们。没有某行也不会改变行为，就说明它不起作用，却会在每次运行时占用上下文。把篇幅留给能让 Agent 偏离默认行为的内容：这个系统的事实、这个团队的执行顺序、那些陷阱。完成标准：每一行都提到一个命令、路径、数字或名称，或者一条没有它 Agent 就会违反的规则。

5. 检查。 运行 node <this-skill>/scripts/check-skill.mjs <new-skill-folder>。它会检查 frontmatter、名称、描述的长度和首句、指向缺失文件的链接、没有可执行权限的脚本、TODO 标记、SKILL.md 的长度，以及填充性短语。完成标准：命令以状态码 0 退出，并且每条警告都已修复或说明了原因。

6. 与用户一起审核。 展示文件夹树、描述和每个脚本。逐项检查 references/review-checklist.md。询问：“你需要这个时会输入哪些词？”将缺失的词放到描述开头。无头模式：在报告末尾列出未解决的问题。完成标准：用户已批准，或已列出未解决的问题。

7. 测试触发条件（需要 claude CLI）。在安装该技能的文件夹中，运行 <this-skill>/scripts/fires.sh <skill-name> "<request>" ... --not "<request>"，使用 3 个未提及技能名称、但应该触发技能的请求，然后使用 --not 和 1 个不应触发技能的请求。如果未触发，请将用户遗漏的词添加到描述开头，然后重新运行。完成标准：脚本输出 PASS（3 个请求中 3 个均触发，且负面请求未触发）。

为 Agent 编写内容

• 使用简短的祈使句：“运行”“停止”“询问”。每句只包含一条指令。
• 写得具体：写 npm run build，而不是“构建项目”；写“最多重试 3 次”，而不是“重试几次”。
• 同一事物只用一个词。如果第 2 步说“发布分支”，第 5 步就不要说“部署分支”。
• 用示例代替形容词：展示一个好的输出，而不是要求“清晰”或“健壮”。
• 不要写引言、动机段落或“这个技能可以帮助你”。直接从任务开始。

注意事项

• 描述是触发条件，不是摘要。正文写得再完美，如果描述含糊，技能也不会运行。
• 适用于每次对话的规则应放在 CLAUDE.md 或 AGENTS.md 中，而不是技能里。技能应包含流程。
• 名称只能包含小写字母、数字和单个连字符，最多 64 个字符，并且必须与文件夹名称一致。
• 除非某个步骤说明何时读取，否则 Agent 不会读取 references/ 中的文件。
• 切勿将机密放入技能中。脚本应从环境变量或工具的凭据存储中读取机密。
• 注意事项部分会不断增长：每次 Agent 在某个技能中出错时，都要在该技能的注意事项中添加一行。

最后验证时间：2026-10-03，使用 Claude Code 2.1.288（TicketBay 发布技能 12/12、从头编写的密钥轮换操作手册 9/9、自动选择 5/5（已安装 144 个技能），以及仅限项目技能 5/5）

灵感来自 Matt Pocock 的 writing-for-agents（MIT）。