GitHub 博客:构建一次即可在任何智能体运行的 agent 技能实践指南
Build once, run on any agent: A practical guide to agent skills
GitHub 员工 Andrea Griffiths 在 GitHub 博客发表 agent 技能实践指南,讲解如何将重复任务封装为可跨智能体复用的技能。
本文给出了将重复任务封装为可移植智能体技能的具体方法,团队可借鉴其清单与校验点设计来沉淀业务知识。
本周你有多少次向智能体重新解释同一项任务?你有多少次向拥有深厚机构知识的同事请教如何解决某个具体问题?这些上下文不应丢失在聊天记录中,也不应只锁在某个人的脑海里。智能体技能(Agent skills)让你能够捕获可重复的指令,以便你和你的智能体可以复用它们。你今晚为自己编写的技能,日后可能成为团队流水线的一部分。
智能体技能是一个以 SKILL.md 文件为中心的版本化目录,该文件描述了何时以及如何执行可重复的任务。你可以跨智能体共享这些指令,但环境仍需提供执行它们所需的工具、凭据和权限。例如,一个技能可以描述如何查询数据库,但它并不授予对该数据库的访问权限。
我在 2026 年 GitHub Universe 大会上与 Procore 数据工程高级经理 Shishir Tewari 进行了现场探讨。我们的会话标题为 “一次构建,任意智能体运行:智能体技能实用指南”。
定义一项任务及其适用时机
当技能具有明确的任务、输入和输出时,其效果最佳。例如,假设你正在构建一个用于将 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 展示了如何将这些判断的一部分捕获在协同工作的技能中。
在 support-desk 流水线示例 中,我们从统计已创建和已解决事件数量的指标请求开始。在构建流水线之前,forge-init 技能会发现源表和命名约定等详细信息,并将其写入已解析的清单(manifest)。其他技能读取该清单以获取所需的项目上下文。
随后,forge-builder 技能协调从问题到拉取请求(pull request)的工作。它使用 forge-dbx 查询数据平台,并使用 forge-lint 在设计和构建流水线时应用团队标准。在此过程中,人员会审查拟议的决策,最终生成的拉取请求包含流水线代码、模式(schema)更改和测试。
每个技能都有明确的职责,它们共享项目上下文,而不是独立地重新发现它。当某个步骤发生变化时,你可以更改一个技能,而保持其他部分不变。
技能适用于有界、可重复且受益于可复用判断的工作,例如检查清单、发布、迁移或指标流水线。如果工作流需要稳定的接口、共享状态、审计跟踪、长时间运行的控制或在模型外部强制执行的权限,则应用程序是更好的选择。
将项目配置排除在技能之外
我们不想将每个项目的名称、数据库或约定硬编码到技能中。在 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 博客。
来源:GitHub Blog · AI & ML · github.blog