GitHub 发布 agent skills 实践指南：一次编写，跨智能体运行

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

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

我在 GitHub Universe 2026 上与 Procore 数据工程高级经理 Shishir Tewari 就此主题进行了现场分享。我们的会议主题是“一次构建，随处运行：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 是一个示例，展示了如何将部分判断捕获到协同工作的 skill 中。

在支持台管道示例中，我们首先收到一个请求，要求提供统计已创建和已解决事件的指标。在构建管道之前，forge-init skill 会发现源表和命名约定等细节，然后将其写入已解析的清单。其他 skill 会读取该清单，以获取它们所需的项目上下文。

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

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

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

将项目配置排除在 skill 之外

我们不想把每个项目的名称、数据库或约定硬编码到技能中。在 Data Forge 支持台示例中，manifest 描述了项目、指标存储和平台，这样技能就能使用正确的项目细节，而无需将它们固化到指令中：

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

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

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

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

在技能之间共享执行路径

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

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

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

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

Proof Agent 示例将同样的原则应用于代码审查。GitHub Actions 工作流将原始请求和代码更改提供给验证器，但不提供编码代理自己的评估。验证器返回 PASS、FAIL 或 PARTIAL，并且必须引用更改文件中的证据。GitHub Action 对差异进行静态审查；它不执行代码或运行测试。在演示工作流中，我们将 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

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

构建代理技能的三项实践

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

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

向 GitHub Copilot 添加智能体技能 >

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