把工程流程写成可跨 Agent 复用的技能

每次换一个 AI 编程助手，都要重新解释项目约定、验收标准和操作步骤，这些上下文就很难成为团队资产。GitHub 这篇文章给出的办法，是把边界清楚、反复执行的任务写成 Agent skills，再用项目配置、共享工具入口和 CI 把它接进工作流。

它最有价值的地方，是划清了几条边界：指令可以复用，权限需要环境提供；模型可以审查，合并门禁需要仓库规则执行。对正在积累团队 AI 编程规范的程序员，这比收集更多提示词更值得花几分钟读。

一个 skill 应该管多大一件事

Agent skill 是一个可做版本管理的目录，核心文件是 SKILL.md，用来说明某个可重复任务何时执行、怎样执行。好的 skill 要有明确的职责、输入和输出，读完应该知道它负责到哪里，以及完成后能交付什么。

作者举的第一个例子是 Proof Agent。它的 frontmatter 将任务命名为 proof-agent，职责是对 AI 生成的工作做对抗式验证，启动独立验证者，检查虚假声明、损坏的代码和安全问题。

这个设计针对的是一种常见偏差：编写代码的 agent 已经形成了自己的解释，再让它评价自己的工作，审查容易受到这套解释影响。Proof Agent 因此把验证交给另一个角色，并在 When to Verify 部分规定触发时机，其余指令说明检查范围和证据要求。

让 agent 再检查一遍，不足以构成独立验证。

不过，单个 skill 的边界仍然要清楚。原文认为，它适合检查清单、发布、迁移、指标流水线这类范围有限、可以重复执行、又需要复用判断经验的工作。如果流程需要稳定接口、共享状态、审计记录、长时间运行控制，或者必须在模型之外强制执行权限，就更适合做成应用程序。

这条边界很实用：任务需要几份文档协作，并不代表它已经具备可靠工作流系统的能力。

多个 skill 怎样协作，才不会各猜各的

第二个例子 Data Forge 处理的是数据流水线。需求是统计支持工单的创建和解决数量，难点不只在生成代码，还包括找到源表、理解命名习惯，以及应用团队标准。

它把工作拆成几个职责明确的 skill：

• forge-init 发现源表、命名约定等信息，写入解析后的清单，即 resolved manifest。
• forge-builder 从 issue 推进到 pull request，协调流水线的设计和构建。
• forge-dbx 提供访问数据平台的统一入口。
• forge-lint 提供生成代码前应遵循的团队标准。

这些 skill 读取同一份项目上下文，避免每个角色重新调查、重新猜测。过程中由人审阅关键决策，最终 pull request 包含流水线代码、schema 变更和测试。某个步骤调整时，也可以只修改对应的 skill。

项目差异则放进 manifest。下面这段配置解决的是「通用指令如何知道当前项目叫什么、使用什么平台」：

project:
  name: "support-desk"
  store_name: "support_metric_store"

platform:
  engine: "duckdb"
  pipeline_framework: "spark_python"
  duckdb_dir: "warehouse"

要看清 engine: "duckdb" 这一行：它选择执行引擎，却不会安装 DuckDB CLI，更不会授予数据库访问权限。pipeline_framework: "spark_python"、duckdb_dir: "warehouse" 等字段同样只是项目配置，具体执行能力仍由环境提供。

forge-dbx 读取 manifest，选择 Databricks 或 DuckDB adapter，让其他 skill 共用连接与查询路径。这样修改平台访问方式时，不必到每份指令里分别修改命令。

还有一个容易被忽略的区分：仓库里发现的做法，不自动等于团队应该继续遵守的规则。

forge-init 可以发现现有 schema 和代码模式，forge-lint 则提供应执行的标准。发现结果应当允许人审阅，涉及业务判断的地方由人确认或调整。否则，自动提取项目习惯，也可能把历史问题写成新的规范。

写一次跨客户端运行，还缺哪些检查

Data Forge 的支持工单示例有七个阶段，每个阶段都设置人工检查点。推进前检查上一阶段是否完成，执行 schema 变更前请求批准。

Proof Agent 则通过 GitHub Actions 接收原始需求和代码变更，不接收编码 agent 对自身工作的评价。验证者返回 PASS、FAIL 或 PARTIAL，并且必须引用变更文件中的证据。

但这里有个关键限制：这个 GitHub Action 只对 diff 做静态审查，不执行代码，也不运行测试。它的发现不能替代仓库原有的测试结果。

演示工作流设置了 block-on-fail: false，因此审查结果只提供建议。默认情况下，FAIL 会使检查失败；只有将该检查设为必需检查，才会阻止合并。判断结果与执行约束是两层机制，合并或部署要求需要在仓库 CI 和规则里落实。

跨客户端复用也需要工程处理。Data Forge 将 skills/*/SKILL.md 作为源文件，通过打包脚本生成 Claude Code 的 .claude-plugin/plugin.json、Cursor 的 .cursor-plugin/plugin.json，以及 GitHub Copilot 的 .github/agents/*.agent.md。

下面的命令用于 CI 检查客户端产物与源文件是否同步：

node scripts/package.mjs --check

关键是 --check 参数：它帮助检查打包产物的一致性，但不能证明 skill 在每个客户端都能正确完成任务。

安装后还要确认客户端能否在预期任务中识别 skill、加载引用资料、调用所需工具，并返回规定的证据。不同客户端的模型、工具、凭据和权限可能不同，文件生成成功只是其中一步。

我的判断

我认同这套方案对知识的拆分：项目事实放 manifest，团队标准由专门的 skill 提供，执行入口统一封装，最终约束交给 CI 和仓库规则。每一层都有可检查的载体，出了问题更容易定位。

与把所有约定塞进一个长提示词相比，这样更容易维护，也更适合多人共同修改。不过，它有一个前提：团队确实存在重复任务，并且能把输入、输出和停止条件描述清楚。偶发任务未必值得建立完整的 skill 体系。

「Build once, run on any agent」也需要保留条件。原文展示了多客户端打包方案，却没有提供不同模型、不同客户端之间的成功率或一致性对照数据。可迁移的是指令与部分组织方式，执行效果仍需逐个环境验证。

独立验证者的设计有道理，但独立角色不等于判断一定可靠。原文没有给出它相对单 agent 自查的误报率、漏报率或缺陷检出对照，因此目前更适合把它视为一种有理由的工程实践，不能据此宣称审查质量已经得到量化证明。

同样，七个阶段各设人工检查点，是这个数据流水线示例的安排。文章没有证明七次确认适合所有任务。一般团队应根据业务决策和操作影响设置检查点，否则也可能增加等待成本。

能拿来做什么

• 从一项反复解释的 AI 编程任务开始，例如核对改动是否覆盖原始需求。写清输入、触发条件、检查范围和输出证据，再尝试交给另一个 agent 执行。
• 把项目名称、目录位置和平台配置集中到 manifest，让相关 skill 共同读取；将现有代码习惯与正式团队标准分开记录，避免自动继承历史问题。
• 如果接入独立代码审查，让验证者读取原始需求和 diff，并要求引用文件证据。继续保留真实测试，把必须阻止合并的条件配置为仓库必需检查。
• 如果团队同时使用 Claude Code、Cursor 和 GitHub Copilot，可以借鉴 Node 打包脚本维护单一指令来源，再用 node scripts/package.mjs --check 检查同步情况，并分别验证各客户端的工具与证据输出。