把重复提示词封装成有验收条件的技能

反复给 AI 编程代理粘贴同一套要求，说明团队已经有了可复用的流程，只是还没把它整理出来。原文建议把这类提示词封装成 SKILL.md，但重点不是换个文件保存，而是写清触发条件、必要输入、执行顺序、审批边界，以及什么证据能证明任务完成。

这篇最有用的判断是：没有完成条件的 skill，不过是放进另一个目录的长提示词。对经常让 AI 审 PR、排查 CI 或准备发布的程序员，它提供了一套把个人经验变成可检查流程的方法。

什么样的提示词值得做成 skill

作者观察到，一条有效的聊天指令可能逐渐变成 70 行文本，被复制进 AGENTS.md，随后又因为太长而被删减，最后连关键约束也丢了。

他的筛选办法很直接：如果基本相同的指令已经粘贴过 3 次，就值得检查能否封装。但这只是经验阈值，原文没有证明第 3 次就是最佳时机。

适合封装的是上下文较多、步骤重复的任务，例如检查涉及计费、认证和权限的 PR，调查 CI 失败，审计 API，或者根据真实 diff 生成 changelog。这些工作的共同点是：每次处理的对象不同，但必须检查的事项相对稳定。

重命名一个变量通常不需要 skill。另一类不适合的任务，是每一步都得由人临时决定的模糊工作。流程尚未形成时，写进文件也不会自动获得可执行性。

值得保存的不是某次奏效的措辞，而是每次都必须执行的检查。

支付 PR 示例，怎样把「认真检查」变成具体动作

原文用一个假设中的 Stripe SaaS 团队举例。订阅、发票、checkout 和 webhook 发生变更时，团队希望稳定检查授权与租户边界、资金请求的幂等性、重复事件处理，以及支付失败后的状态变化。

一句「认真检查安全、webhook、幂等性和测试」覆盖了主题，却留下很多空白：哪些文件属于计费范围？测试必须执行吗？审查过程中能不能直接改代码？

作者建议建立 skills/payment-pr-reviewer/SKILL.md。其中，name 是 payment-pr-reviewer，description 则写入 Stripe、billing、subscriptions、invoices、checkout、payment webhooks 等词，并说明用于合并前的支付 PR 审查。作者把 description 看作分发入口：它帮助代理判断何时选择这个流程，而不只是介绍文件用途。

下面这段正文把审查要求变成了可核对的步骤：

## Required inputs

- PR diff and changed files
- billing test command: `pnpm test -- billing`
- existing authorization middleware
- webhook handler code when changed

## Review sequence

1. List changed billing-related files before making conclusions.
2. Trace every money-moving request to its authorization check.
3. Check idempotency keys and duplicate-event behavior.
4. For each changed webhook path, verify replay is safe.
5. Inspect existing tests and run the billing test command.
6. Report findings by severity, citing file and line references.

## Safety boundary

Do not change implementation code during review. Ask before running migrations,
calling external payment APIs, or changing production configuration.

## Done when

- all changed payment paths have been inspected;
- the billing test command has been run or a blocker is reported;
- findings explain impact, evidence, and a recommended next step;
- absence of findings is explicit, not implied.

要留意 Done when 中允许报告 blocker 的那一行：测试跑不了，就明确交代阻塞原因；不能把没有执行包装成验证通过。同时，没有发现问题也必须直说，不能让读者从沉默里推断结论。

这里的 pnpm test -- billing 是示例团队提供的验证命令，不是所有项目通用的支付测试入口。迁移到自己的仓库时，需要核实命令、测试范围和所需环境。

步骤顺序同样有意义。先列文件，再追踪资金请求与授权检查，最后结合测试输出报告，可以让结论有可追溯的依据。幂等性和重放安全也不是抽象术语：同一请求或 webhook 再来一次，系统应当避免重复扣款或产生错误状态。

skill、项目说明和 CI，分别负责什么

原文强调，这几类机制不能互相替代。

「项目使用 pnpm，采用 monorepo 布局」属于项目上下文，适合放在 AGENTS.md 一类说明里；「如何审查支付 PR」是按需执行的流程，适合做成 skill；「测试失败就阻止合并」则应该交给 CI。

这个区分很实用。把所有内容塞进同一个入口，容易变成作者所说的 600 行上下文文件，维护者很难判断哪些是背景、哪些必须执行、哪些只是参考。代理指令可以要求运行测试，但真正的合并限制仍需要系统执行。

作者给出的整理顺序是：收集旧提示词、相关 AGENTS.md 段落、两三个真实案例和验证命令；删掉代理能够自行查到的背景，保留曾经导致失败的例外；写清触发描述和审批边界；先定义完成证据，再细化步骤；最后找一个团队已经了解结果的历史任务试跑。

「先写完成条件」是其中最有价值的一步。如果连怎样证明成功都说不清，继续扩充步骤，往往只会得到更长的指令。

对于发布、部署、删除、付费操作、修改生产数据和发送外部消息，原文建议明确审批要求，也要求隐藏输出中的凭证，遇到破坏性操作失败时停止盲目重试。参考资料、模板和脚本则放在 SKILL.md 旁边，按需加载，避免核心流程不断膨胀。

我的判断

我认同作者把完成证据放在中心的位置。AI 很容易给出流畅的完成报告，而工程交接需要的是检查范围、执行结果、阻塞项和定位依据。把这些提前写进流程，比最后追加一句「再检查一下」更容易验收。

但原文没有提供成功率、缺陷漏检率或执行成本的对照数据。支付 PR 也是设想案例，并非展示过结果的团队实验。它支持的是一套合理的流程设计建议，还不足以证明换成 skill 后，代理就会稳定遵循全部步骤。

完成条件也有强弱之分。「测试命令执行过」不等于测试通过；「所有路径已检查」仍需要报告列出范围和依据。代码示例规定了最低交付要求，实际团队还应根据风险明确失败如何处理、哪些证据必须留下。

与直接粘贴提示词相比，skill 更方便版本管理和复用，但需要有人维护；与 AGENTS.md 相比，它更适合按任务触发；与脚本和 CI 相比，它适合描述需要阅读、判断和解释的过程。能用程序稳定验证的硬规则，仍应尽量交给程序。

作者最后提到 Terminal Skills 上的 agent-workflow-packager，声称它能生成带触发条件、示例、审批关卡和完成检查的合规 skill 目录。原文没有展开验证过程，不能据此认定生成结果可以直接用于自己的仓库。

能拿来做什么

• 从最近反复使用的 PR 审查或 CI 排障提示词中挑一个，整理触发条件、必要输入和完成证据，先封装一个范围明确的流程。
• 给前端或 Node 仓库里的审查流程填入真实测试命令，并要求报告执行结果、未覆盖范围和阻塞原因，避免代理自行猜测验证入口。
• 将审查权限写具体，例如允许读取 diff 和运行本地测试，修改实现代码、执行迁移或调用外部支付 API 则遵循团队既有授权规则。
• 用一个已经知道问题和处理结果的历史 PR 试跑，检查代理是否读全变更、找到预期风险并给出证据，再根据遗漏调整 skill。