GitHub 发布 agent skills 实践指南:一次编写,跨智能体运行
Build once, run on any agent: A practical guide to agent skills
GitHub 发布一份 agent skills 实践指南,介绍如何用 SKILL.md 目录封装可复用任务指令,并在 Claude Code、Cursor 和 GitHub Copilot 等客户端间共享。文中以 Proof Agent 和 Data Forge 为例,说明技能应各自承担明确职责、把项目配置放进 manifest 而非硬编码,并在每个阶段设置人工检查点。作者还给出打包脚本思路,为不同客户端生成对应插件文件,并建议安装后验证客户端能否识别技能并调用所需工具。
正文 · AI 翻译
本周你有多少次向智能体重复解释同一个任务?有多少次向拥有深厚机构知识的同事请教如何解决某个具体问题?这些上下文不应丢失在聊天记录里,也不应锁在某一个人的头脑中。Agent skills 让你能够捕获可重复的指令,以便你和你的智能体可以复用它们。你今晚为自己编写的技能,日后可以成为团队流水线的一部分。
Agent skill 是一个以 SKILL.md 文件为中心的版本化目录,该文件描述了何时以及如何执行一项可重复的任务。你可以在多个智能体之间共享这些指令,但环境仍然需要提供执行这些指令所需的工具、凭据和权限。例如,一个技能可以描述如何查询数据库,但它并不授予对该数据库的访问权限。
我在 GitHub Universe 2026 上与 Procore 数据工程高级经理 Shishir Tewari 就此主题进行了现场交流。我们的会议主题是“一次构建,在任何智能体上运行:agent skills 实用指南”。
定义一个任务及其适用场景
当一个技能具有明确的任务、输入和输出时,它的效果最好。例如,假设你正在构建一个智能体,用于对照原始请求检查 AI 生成的更改。如果同一个智能体评估自己的工作,它的解释可能会影响审查结果。在 Proof Agent 中,我们使用一个独立的验证器来检查更改并为其发现提供证据。该技能的 frontmatter 命名了任务并描述了其用途:
其核心是一条简单的规则:自我验证不是验证。
Proof Agent 的 SKILL.md 中的“何时验证”部分说明了何时调用该技能。其余指令解释了验证器审查什么,以及在其发现中应包含哪些证据。
为更大的工作流协调多个技能
当决定数据管道正确性的判断分散在四个人的头脑中时,这四个人就是路线图。管道的每一次变更都取决于他们的可用性和对数据的了解。Data Forge 是一个示例,展示了如何将部分判断捕获到协同工作的技能中。
在支持台管道示例中,我们从请求统计已创建和已解决事件的指标开始。在构建管道之前,forge-init 技能会发现源表和命名约定等细节,然后将它们写入已解析的清单。其他技能读取该清单以获取所需的项目上下文。
随后,forge-builder 技能协调从问题到拉取请求的整个工作。它使用 forge-dbx 查询数据平台,并使用 forge-lint 在设计和构建管道时应用团队标准。在此过程中,由人工审查所提出的决策,最终生成的拉取请求包含管道代码、模式变更和测试。
每个技能都有明确的职责,它们共享项目上下文,而不是各自独立地重新发现。当某个步骤发生变化时,你可以只修改一个技能,而让其余技能保持不变。
技能适用于有边界、可重复且受益于可复用判断的工作,例如检查清单、发布、迁移或指标管道。如果工作流需要稳定的接口、共享状态、审计追踪、长时间运行的控制,或在模型之外强制执行的权限,那么应用程序是更合适的选择。
将项目配置排除在技能之外
我们不希望将每个项目的名称、数据库或约定硬编码到技能中。在 Data Forge 支持台示例中,清单描述了项目、指标存储和平台,以便技能可以使用正确的项目细节,而无需将它们固化到指令中:
借助已解析清单中发现的细节,其他技能不必对项目做出自己的假设。
将发现的项目细节与团队标准分开。forge-init 初始化技能可以检查现有的模式和代码模式;forge-lint 技能提供在生成代码之前要遵循的规则。在仓库中发现的模式并不自动成为要保留的规则,因此请让发现的细节可供审查,并在需要业务判断的地方让人确认或更改它们。要检查可移植性,请问:另一个团队能否在不重写这些技能的情况下,用自己的清单使用它们?
在技能之间共享执行路径
forge-dbx 技能为其他 Data Forge 技能提供了一种访问数据平台的方式。它读取清单并选择 Databricks 或 DuckDB 适配器,因此每个技能都不需要自己的连接和查询逻辑。
清单可以为本地支持台演示选择 DuckDB,但它无法安装 DuckDB CLI 或授予数据库访问权限。这些仍然是环境及其用户的设置职责。清单选择引擎;主机提供访问权限。
在工作流中设置检查和审批点
Data Forge 支持台工作流有七个阶段,每个阶段都有一个人工检查点。工作流概览展示了这些技能如何协同工作。在某个阶段继续之前,工作流会检查上一阶段是否完成;在运行模式变更之前,它会请求批准。
Proof Agent 示例将同样的原则应用于代码审查。GitHub Actions 工作流会向验证器提供原始请求和代码变更,但不提供编码智能体自身的评估。验证器返回 PASS、FAIL 或 PARTIAL,并且必须引用变更文件中的证据。该 GitHub Action 对 diff 进行静态审查;它不会执行代码或运行测试。在演示工作流中,我们将 block-on-fail: false 设为 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 的检查模式:
客户端在可用模型、工具、凭据和权限方面可能有所不同。安装技能后,请检查客户端能否针对预期任务识别该技能、加载其引用、使用所需工具,并返回该技能所要求的证据。
构建智能体技能的三项实践
将业务上下文放在一个文件中。将项目特定的名称、模式和约定保留在清单中,并让每个技能读取该清单,而不是重复这些事实。这为团队提供了一个可见的配置更新位置。
为相关技能提供一种一致的平台使用方式。让相关技能使用相同的路径来运行查询、作业和模式变更,而不是各自定义自己的命令和连接逻辑。这样可以让工作流的访问方式更易于理解,其行为也更容易在每个客户端中检查。
使用指令来指导工作,使用检查来验证工作。技能可以告诉智能体应遵循哪些标准,以及何时请求批准。在需要上下文或判断的决策点加入人工审查,并使用测试和 CI 检查在变更推进之前发现问题。如果某项检查必须阻止合并或部署,请在仓库的规则中配置该要求。
从你已经厌倦了解释的任务开始。写下它需要什么、在哪里停止,以及审查者会看到什么。然后用另一个智能体尝试它,并在了解哪些做法有效后不断改进。