GitHub 指南：如何编写可跨 Agent 复用的 agent skills

Agent skills 将可重复的工程工作捕获到团队可以审查和复用的文件中，而工具、项目上下文和权限则仍然取决于运行它们的宿主。

2026年11月12日

6 分钟

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

Agent skill 是一个带版本管理的目录，其核心是一个 SKILL.md 文件，描述何时以及如何完成一项可重复的任务。你可以跨智能体共享这些指令，但环境仍需要提供执行它们所需的工具、凭据和权限。例如，技能可以描述如何查询数据库，但它并不会授予对该数据库的访问权限。

在 GitHub Universe 2026 上，我与 Procore 数据工程高级经理 Shishir Tewari 就这个话题进行了现场讨论。我们这场演讲的题目是 “一次构建，运行于任意智能体：agent skills 实战指南”。

定义一项明确的工作及其适用时机

当一项技能有清晰的工作、输入和输出时，它的效果最好。举例来说，假设你正在构建一个智能体，用于对照原始请求检查 AI 生成的变更。如果同一个智能体评估自己的工作，它的解释可能会影响审查。在 Proof Agent 中，我们使用一个独立的验证器来检查变更，并为其发现提供证据。该技能的 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 部分说明了何时调用该技能。其余指令解释了验证器审查什么内容，以及在其发现中应包含哪些证据。

为更大的工作流协调多个技能

当使数据流水线正确运行所需的判断存在于四个不同人的头脑中时，这四个人就是路线图本身。流水线的每次变更都依赖于他们的可用性和对数据的了解。Data Forge 展示了如何把这类判断的一部分捕获到协同工作的技能中。

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

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

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

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

不要把项目配置写进 skill

我们不想把每个项目的名称、数据库或约定硬编码到 skills 中。在 Data Forge 支持工单的示例中，一份清单描述了项目、指标存储和平台，这样 skills 就能使用正确的项目细节，而不必把它们写进各自的指令中：

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

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

由于解析后的清单中包含了已发现的细节，其他 skills 就不必对项目做出各自的假设了。

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

forge-dbx skill 为其他 Data Forge skills 提供了访问数据平台的统一方式。它读取清单并选择 Databricks 或 DuckDB 适配器，因此每个 skill 都不需要自己的连接和查询逻辑。

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

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

Data Forge 支持工单工作流有七个阶段，每个阶段都有一个人工检查点。工作流概览展示了这些 skills 如何协作。在某个阶段继续之前，工作流会检查上一个阶段是否已完成；在运行模式变更之前，它会请求审批。

Proof Agent 示例将同样的原则应用于代码审查。一个 GitHub Actions 工作流会向验证器提供原始请求和代码变更，但不提供编码智能体自己的评估。验证器返回 PASS、FAIL 或 PARTIAL，并且必须引用变更文件中的证据。GitHub Action 对 diff 进行静态审查；它不执行代码，也不运行测试。在演示工作流中，我们设置了 block-on-fail: false，因此发现的问题仅供参考。默认情况下，FAIL 会使检查失败，如果该检查是必需的，则会阻止合并。其目的是把测试结果和合并要求保留在你仓库的 CI 检查和规则中。

为每个智能体客户端打包，然后验证其设置

支持多个客户端可能意味着要同步维护多份相同的指令。在 Data Forge 示例中，我们把 skills/*/SKILL.md 作为源，并使用打包脚本生成客户端专属文件：.claude-plugin/plugin.json 用于 Claude Code，.cursor-plugin/plugin.json 用于 Cursor，.github/agents/*.agent.md 用于 GitHub Copilot。该脚本还包含一个用于 CI 的检查模式：

node scripts/package.mjs --check

不同客户端在可用模型、工具、凭证和权限方面可能存在差异。安装 skill 之后，请检查客户端是否能为预期任务识别该 skill、加载其参考资料、使用所需的工具，并返回该 skill 所要求的证据。

构建智能体 skills 的三个实践

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

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

作者：

Andrea Griffiths

Andrea 是 GitHub 的高级开发者布道师，在开发者工具领域拥有十多年的经验。她将深厚的技术功底与让先进技术更易于普及的使命相结合。在从军队服役和建筑管理转型为软件开发之后，她为弥合复杂工程概念与实际落地之间的鸿沟带来了独特的视角。她和她的威尔士伴侣、两个儿子以及两只狗住在佛罗里达州，在那里她继续通过 GitHub 的全球计划推动创新并支持开源。欢迎在线关注她：@acolombiadev。

我们也提供新闻通讯

在我们专为开发者打造的双周新闻通讯中发现技巧、技术指南和最佳实践。