GitHub 介绍 agent skills 实践:把重复任务写成 SKILL.md 跨客户端复用
Build once, run on any agent: A practical guide to agent skills
GitHub 在 GitHub Universe 2026 的一场分享中介绍了 agent skills 的用法,即把可重复任务写成以 SKILL.md 为核心的版本化目录,再通过打包脚本生成 Claude Code、Cursor、GitHub Copilot 各自的客户端文件。
把重复任务写成带版本号的 SKILL.md,在 Claude Code、Cursor、GitHub Copilot 之间打包复用,团队不用再向同一个人反复解释同一套做法。

这周你有多少次把同一个任务反复讲给智能体听?又有多少次去问那位对内部情况了如指掌的同事,某个具体问题该怎么解决?这些上下文不该丢在聊天记录里,也不该只锁在某一个人的脑子里。智能体技能(agent skill)让你把可重复的指令记录下来,供你和你的智能体反复使用。你今晚为自己写的技能,日后可能成为团队流水线的一部分。
智能体技能是一个带版本号的目录,核心是一个 SKILL.md 文件,用来说明一项可重复的任务在什么情况下做、该怎么做。这些指令可以在不同智能体之间共享,但执行任务所需的工具、凭据和权限仍要由环境提供。比如,技能可以描述如何查询某个数据库,但它本身并不授予对该数据库的访问权限。
在 GitHub Universe 2026 上,我与 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 就是一个例子,展示如何把其中部分判断沉淀到相互配合的技能里。
在服务台管道示例中,我们先接到一个需求:统计创建和解决的事件数量。在搭建管道之前,forge-init 技能会先摸清源表、命名规范等细节,然后写入一份已解析的清单(manifest)。其他技能则读取这份清单,获取所需的项目上下文。
接着,forge-builder 技能负责协调从 issue 到 pull request 的整个流程。它用 forge-dbx 查询数据平台,用 forge-lint 在设计并搭建管道时落实团队规范。过程中有人会审核提出的决策,最终生成的 pull request 中包含管道代码、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 初始化技能可以检查现有的 schema 和代码模式;forge-lint 技能则提供生成代码前要遵循的规则。在仓库里发现的模式并不自动就是应当保留的规则,所以要让发现的细节可审查,并在需要业务判断的地方让人确认或修改。要检验可移植性,可以问:另一个团队能否用自己的 manifest 使用这些技能,而无需重写?
让技能之间共享执行路径
forge-dbx 技能为其他 Data Forge 技能提供了一种访问数据平台的方式。它读取 manifest,并选择 Databricks 或 DuckDB 适配器,这样每个技能就不必各自实现连接和查询逻辑。
manifest 可以为本地支持台演示选择 DuckDB,但它无法安装 DuckDB CLI 或授予数据库访问权限。这些仍然是环境及其用户的设置职责。manifest 选择引擎;宿主提供访问权限。
在工作流中设置检查点和审批点
Data Forge 支持台工作流有七个阶段,每个阶段都设有人工检查点。工作流概览展示了各技能如何衔接。在进入下一阶段前,工作流会检查上一阶段是否完成;在执行 schema 变更前,它会请求批准。
Proof Agent 示例把同样的原则应用到代码审查上。GitHub Actions 工作流把原始请求和代码变更交给验证器,但不提供编码智能体自己的评估。验证器返回 PASS、FAIL 或 PARTIAL,并且必须引用变更文件中的证据。GitHub Action 对 diff 做静态审查;它不执行代码,也不运行测试。在演示工作流中,我们把 block-on-fail: 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 的检查模式:
node scripts/package.mjs --check不同客户端在可用模型、工具、凭据和权限上可能不同。安装技能后,要检查客户端能否针对预期任务识别它、加载其引用、使用所需工具,并返回技能要求的证据。
构建智能体技能的三点实践
- 把业务上下文放在一个文件里。把项目特定的名称、schema 和约定放在 manifest 中,让每个技能读取它,而不是重复这些事实。这样团队就有了一个可见的位置来更新配置。
- 让相关技能用统一的方式使用平台。让相关技能走同一条路径来执行查询、任务和架构变更,而不是各自定义命令和连接逻辑。这样工作流的访问方式更容易理解,其行为在每个客户端里也更容易核查。
- 用指令引导工作,用检查验证结果。技能可以告诉智能体该遵循哪些标准、何时请求批准。在需要背景信息或判断的决策点加入人工审核,并用测试和 CI 检查在变更推进之前发现问题。如果某项检查必须阻止合并或部署,就在仓库的规则里配置这一要求。
从你已经懒得再解释的那项任务开始。写下它需要什么、在哪里停下,以及审核者会看到什么。然后换一个智能体试一遍,边做边了解哪些做法有效,再据此改进。
文章 Build once, run on any agent: A practical guide to agent skills 首发于 The GitHub Blog。
来源:GitHub Blog · github.blog