一次构建，处处运行：Agent Skills 实战指南

这周你有几次向 agent 重新解释同一个任务？又有几次去请教那位熟悉内情的同事某个具体问题怎么解决？这些上下文不该埋没在聊天记录里，也不该只存在于某个人的脑子里。Agent skills 让你把可复用的指令沉淀下来，供你和你的 agent 反复使用。今晚为自己写的 skill，日后可能成为团队流水线的一部分。 Agent skill 是一个带版本管理的目录，核心是一个 SKILL.md 文件，描述某个可重复任务的执行时机和方式。这些指令可以在多个 agent 之间共享，但环境仍需提供执行所需的工具、凭证和权限。比如 skill 可以描述如何查询数据库，但它本身并不能授权访问该数据库。 在 GitHub Universe 2026 上，我和 Procore 数据工程高级经理 Shishir Tewari 在现场分享了这个主题，议题名为 “Build once, run on any agent: a practical guide to agent skills”。

定义单一职责及其适用场景

Skill 在职责、输入和输出都清晰明确时效果最好。举个例子，假设你要构建一个 agent，用来对照原始需求检查 AI 生成的改动。如果让同一个 agent 评估自己的产出，它的解释可能会影响审查结果。在 Proof Agent 中，我们用一个独立的验证器来检查改动，并为结论提供证据。Skill 的 frontmatter 声明了任务名称并描述其用途：

---
name: proof-agent
description: Adversarial verification of AI-generated work. Spawns an independent verifier to check for false claims, broken code, and security issues.
---

这里有一条核心原则：自我验证不算验证。

Proof Agent 的 SKILL.md 中的 When to Verify 部分说明了何时调用该 skill。其余指令则解释验证器审查哪些内容，以及结论中应包含哪些证据。

协调多个 skill 构建更大的工作流

当数据管道的正确性判断分散在四个人脑中时，那四个人就是开发路线图。管道每次变更都依赖他们的可用性和对数据结构的熟悉程度。Data Forge 展示了一个示例：如何将这些判断中的部分封装进协同工作的 skills。 在support-desk 管道示例中，我们从统计事件创建和解决数量的指标请求开始。在构建管道前，forge-init skill 会先发现源表和命名约定等细节，并将其写入已解析的 manifest。其他 skills 随后读取该 manifest，获取所需的项目上下文。 forge-builder skill 负责协调从 issue 到 pull request 的工作。它使用 forge-dbx 查询数据平台，并用 forge-lint 在设计构建管道时应用团队标准。过程中由人员审核相关决策，最终生成的 pull request 包含管道代码、架构变更和测试。 每个 skill 都有明确的责任范围，它们共享项目上下文而非独立重新发现信息。当某步骤需要变更时，可以只修改一个 skill，其余保持不变。 Skills 适合有边界、可重复且受益于可复用判断的工作，比如清单、发布、迁移或指标管道。如果工作流需要稳定接口、共享状态、审计跟踪、长时控制或模型外权限强制，则应用是更好的选择。

将项目配置排除在 skill 之外

我们不希望将每个项目的名称、数据库或约定硬编码到 skills 中。在 Data Forge 的 support-desk 示例中，manifest 描述项目、指标存储和平台，使 skills 能使用正确的项目细节，而无需将这些细节固化在指令中：

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

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

由于已发现的细节都记录在解析后的 manifest 中，其他技能就不必再各自对项目做出假设了。

要把已发现的项目细节和团队规范分开管理。forge-init 初始化技能负责检查现有的 schema 和代码模式；forge-lint 技能则提供代码生成前需要遵守的规则。仓库里发现某个模式，并不代表它就该被当作规则保留下来，因此要让这些发现的细节可供审阅，在涉及业务判断的地方由人来确认或修改。要检验可移植性，可以问一个问题：另一个团队能否用自己的 manifest 直接使用这些技能，而无需重写？

让技能共享执行路径

forge-dbx 技能为其他 Data Forge 技能提供了访问数据平台的统一途径。它会读取 manifest 并选择 Databricks 或 DuckDB 适配器，这样每个技能就无需自带连接和查询逻辑。

manifest 可以为本地支持工单演示选择 DuckDB，但它无法安装 DuckDB CLI，也无法授予数据库访问权限。这些仍是环境及其用户在部署阶段要做的事。引擎由 manifest 决定，访问由宿主提供。

在工作流中设置检查点和审批环节

Data Forge 的支持工单工作流共有七个阶段，每个阶段都设有人工检查点。工作流总览展示了各技能如何协作。每个阶段推进前，工作流会先确认上一阶段已完成；在执行 schema 变更前，还需要请求审批。

Proof Agent 示例把同样的原则应用到了代码审查上。GitHub Actions 工作流会给验证器提供原始需求和代码变更，但不提供编码 agent 自己的评估结论。验证器返回 PASS、FAIL 或 PARTIAL，并且必须引用变更文件中的证据作为依据。GitHub Action 只对 diff 做静态审查，不会执行代码或运行测试。在演示工作流中，我们把 block-on-fail 设为 false，因此审查结果只作参考。默认情况下，FAIL 会导致检查失败；如果该检查被设为必过项，就会阻止合并。这样做的目的是把测试结果和合并要求保留在你仓库的 CI 检查和规则中。

针对每个 agent 客户端打包，然后验证其环境配置

支持多个客户端可能意味着需要同步维护同一份指令的多份副本。在 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

不同客户端在可用模型、工具、凭据和权限方面可能存在差异。安装技能后，应验证客户端是否能识别该技能并将其用于目标任务、能否正确加载引用资源、是否具备调用所需工具的能力，以及能否返回技能所要求的执行证据。

构建 agent skills 的三项实践

1. 将业务上下文集中在单个文件中。将项目名称、数据模式和团队约定等特有信息统一维护在清单文件里，让每个 skill 读取该清单而非各自重复定义这些事实。这样团队就有了一个统一的可视位置来更新配置。
2. 为相关技能提供一致的平台使用方式。让相互关联的 skill 使用同一条路径来执行查询、任务和数据模式变更，而不是各自定义不同的命令和连接逻辑。这能降低理解工作流访问方式的门槛，也便于在各客户端中检查其实际行为。
3. 用指令引导工作，用检查验证结果。Skill 可以告知 agent 应遵循哪些规范、何时请求审批。在需要结合上下文或人类判断的决策节点加入人工审核环节；利用测试和 CI 检查在变更推进前尽早发现问题。如果某项检查必须阻断合并或部署，请在仓库规则中明确配置该要求。

从你最常解释的那个任务入手开始实践。写下它需要什么、在哪里停止、审阅者能看到什么。然后换一个 agent 试运行，并在不断摸索中迭代改进。