GitHub 发布 Agent Skills 实操指南：一次编写、跨 Agent 复用

GitHub Blog· Andrea Griffiths·2026-11-13 06:54· 2 小时前AI 评分65

一次构建，可在任何 Agent 上运行：Agent 技能实操指南

AI 导读

GitHub Blog 发布 Agent Skills 实操指南，讲解如何用 SKILL.md 把可重复任务指令沉淀为可跨 Agent 复用的版本化技能目录。

正文 · 原文

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

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

我在 GitHub Universe 2026 上与 Procore 数据工程高级经理 Shishir Tewari 现场探讨了这一主题。我们的演讲题为“一次构建，可在任何 Agent 上运行：Agent 技能实操指南”。

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

当技能具有明确的任务、输入和输出时，效果最佳。例如，假设你正在构建一个 Agent，用于对照原始请求检查 AI 生成的更改。如果同一个 Agent 评估自己的工作，它的解释可能会影响审查结果。借助 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 技能会发现源表和命名约定等细节，然后将其写入已解析的清单。其他技能会读取该清单以获取所需的项目上下文。

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

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

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

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

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

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

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

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

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

在技能之间共享执行路径

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

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

将检查和审批点放入工作流

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

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

构建代理技能的三个实践

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

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

向 GitHub Copilot 添加 agent skill >

文章 Build once, run on any agent: A practical guide to agent skills 首次出现在 The GitHub Blog。

来源：GitHub Blog · github.blog