GitHub 发布跨智能体技能复用实践指南

这周你有多少次向 agent 重新解释同一个任务？有多少次向拥有深厚机构知识的同事请教如何解决某个具体问题？这些上下文不应丢失在聊天记录里，也不应锁在某一个人的脑子里。Agent skills 让你能够捕获可复用的指令，让你和你的 agent 都能重复使用。你今晚为自己编写的 skill，日后可以成为团队流水线的一部分。

Agent skill 是一个以 SKILL.md 文件为核心的版本化目录，该文件描述了何时以及如何执行一项可重复的任务。你可以在多个 agent 之间共享这些指令，但环境仍需提供执行这些指令所需的工具、凭据和权限。例如，一个 skill 可以描述如何查询数据库，但它并不授予对该数据库的访问权限。

定义一个任务及其适用场景

当一个 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.
---

其核心是一条简单的规则：自我验证不等于验证。

协调多个 skill 以支撑更大的工作流

当决定数据管道正确性的判断分散在四个人的头脑中时，这四个人就是路线图。管道的每一次变更都依赖于他们的可用性和对数据的了解。Data Forge 是一个示例，展示了如何将部分判断捕获到协同工作的 skill 中。

在支持台流水线示例中，我们从一个指标请求开始，该指标用于统计创建和解决的事件数量。在构建流水线之前，forge-init 技能会发现源表和命名约定等细节，然后将其写入已解析的清单。其他技能会读取该清单，以获取所需的项目上下文。

随后，forge-builder 技能会协调从 issue 到 pull request 的整个工作。它使用 forge-dbx 查询数据平台，并使用 forge-lint 在设计和构建流水线时应用团队标准。在此过程中，会有人审查所提出的决策，最终生成的 pull request 包含流水线代码、schema 变更和测试。

每个技能都有明确的职责，它们共享项目上下文，而不是各自独立地重新发现。当某个步骤发生变化时，你可以只修改一个技能，而让其余技能保持不变。

技能适用于有边界、可重复的工作，这些工作受益于可复用的判断，例如检查清单、发布、迁移或指标流水线。如果工作流需要稳定的接口、共享状态、审计轨迹、长时间运行的控制，或在模型之外强制执行的权限，那么应用程序是更合适的选择。

将项目配置排除在技能之外

我们不希望将每个项目的名称、数据库或约定硬编码到技能中。在 Data Forge 支持台示例中，一个清单描述了项目、指标存储和平台，以便技能可以使用正确的项目细节，而无需将其固化到指令中：

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

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

借助已解析清单中发现的细节，其他技能不必对项目做出自己的假设。

将发现的项目细节与团队标准分开。forge-init 初始化技能可以检查现有的 schema 和代码模式；forge-lint 技能则提供在生成代码之前需要遵循的规则。在仓库中发现的模式并不会自动成为需要保留的规则，因此要让发现的细节可供审查，并在需要业务判断的地方让人来确认或修改它们。要检查可移植性，可以问：另一个团队能否在不重写这些技能的情况下，用自己的 manifest 来使用它们？

forge-dbx 技能为其他 Data Forge 技能提供了一种访问数据平台的方式。它读取 manifest 并选择 Databricks 或 DuckDB 适配器，这样每个技能就不需要各自维护连接和查询逻辑。

manifest 可以为本地 support-desk 演示选择 DuckDB，但它无法安装 DuckDB CLI 或授予数据库访问权限。这些仍然是环境及其用户的配置职责。manifest 选择引擎；主机提供访问权限。

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

Data Forge support-desk 工作流包含七个阶段，每个阶段都有一个人工检查点。工作流概览展示了这些技能如何协同工作。在某个阶段继续之前，工作流会检查上一阶段是否完成；在 schema 变更执行之前，它会请求审批。

Proof Agent 示例将同样的原则应用于代码审查。GitHub Actions 工作流将原始请求和代码变更提供给验证器，但不提供编码代理自身的评估。验证器返回 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

不同客户端在可用模型、工具、凭据和权限方面可能有所不同。安装技能后，请检查客户端能否针对预期任务识别该技能、能否加载其引用内容、能否使用所需工具，以及能否返回该技能所要求的证据。

构建智能体技能的三项实践

1. 将业务上下文放在一个文件中。 将项目特定的名称、schema 和约定保留在清单文件中，让每个技能读取该文件，而不是重复这些事实。这样团队就有了一个可见的配置更新位置。
2. 让相关技能以一致的方式使用平台。 让相关技能使用相同的路径来执行查询、作业和 schema 变更，而不是各自定义自己的命令和连接逻辑。这样工作流的访问方式更容易理解，其行为也更容易在每个客户端中检查。
3. 用指令指导工作，用检查验证工作。 技能可以告诉智能体应遵循哪些标准，以及何时请求批准。在需要上下文或判断的决策点加入人工审核，并使用测试和 CI 检查在变更推进之前发现问题。如果某项检查必须阻止合并或部署，请在仓库的规则中配置该要求。

从那个你已经厌倦了解释的任务开始。写下它需要什么、在哪里停止，以及审核者会看到什么。然后用另一个智能体试一试，并在了解哪些做法有效后不断改进它。

向 GitHub Copilot 添加智能体技能 >

文章 一次构建，随处运行：智能体技能实用指南 首次发表于 The GitHub Blog。