11-19 更新 实时
首页/ 技术栈/ 正文

一次构建,随处运行:智能体技能实用指南

技术栈 来源:GitHub Blog 2026-11-13 06:54 1 阅读 机器翻译

这周你有多少次向一个智能体重新解释同一个任务?有多少次去问那些掌握深厚机构知识的同事,某个具体问题该怎么解决?这些上下文不应该遗失在聊天记录里,也不该锁在某一个人的脑子里。智能体技能(agent skill)让你把可重复的指令固化下来,这样你和你的智能体都能复用它们。你今晚为自己写的技能,之后可以成为团队流水线的一部分。

一项智能体技能是一个以 SKILL.md 文件为中心的版本化目录,该文件描述何时以及如何完成一项可重复的任务。你可以在多个智能体之间共享这些指令,但环境仍然需要提供执行它们所需的工具、凭据和权限。举例来说,一项技能可以描述如何查询数据库,但它并不会授予对该数据库的访问权限。

在 GitHub Universe 2026 期间,我与 Procore 数据工程高级经理 Shishir Tewari 现场讨论了这个话题。我们的环节题为“Build once, run on any agent: a practical guide to agent skills”(一次构建,随处运行于任何智能体:智能体技能实用指南)。

一项技能在拥有明确的任务、输入和输出时效果最佳。举个例子,假设你正在构建一个智能体,用来对照原始请求检查 AI 生成的改动。如果由同一个智能体评估自己的工作,它的解释可能会影响这次审查。在 Proof Agent 中,我们使用一个独立的验证器来检查改动,并为其结论提供证据。该技能的 frontmatter 会写明任务名称并描述其用途:

--- name: proof-agent description: 对 AI 生成的工作进行对抗式验证。启动一个独立的验证器,检查虚假声明、损坏的代码和安全问题。 --- 其核心是一条简单的规则:自我验证不算验证。

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 的 support-desk 示例中,清单(manifest)描述了项目、指标存储和平台,这样技能就能使用正确的项目细节,而不必把它们写死到自身的指令中:

project: name: "support-desk" store_name: "support_metric_store" platform: engine: "duckdb" pipeline_framework: "spark_python" duckdb_dir: "warehouse" 借助解析后清单中发现的具体信息,其他技能不必再对项目自行做出假设。

要把发现的项目细节与团队标准区分开。forge-init 初始化技能可以检查现有的 schema 和代码模式;forge-lint 技能则提供在生成代码之前需要遵循的规则。在代码仓库中发现的某个模式并不会自动成为需要保留的规则,因此要让发现的细节可被审查,并在需要业务判断的地方让人来确认或修改。要检验可移植性,可以问:另一个团队能否使用自己的清单来使用这些技能,而无需重写它们?

forge-dbx 技能为其他 Data Forge 技能提供了访问数据平台的统一方式。它读取清单并选择 Databricks 或 DuckDB 适配器,这样每个技能就不需要各自维护连接和查询逻辑。

清单可以为本地 support-desk 演示选择 DuckDB,但它无法安装 DuckDB CLI,也无法授予数据库访问权限。这些仍然属于环境及其用户的配置职责。清单负责选择引擎;宿主负责提供访问权限。

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 各客户端在可用模型、工具、凭据和权限上可能有所不同。安装技能后,要检查客户端能否为预期任务识别该技能、是否加载其引用资料、能否使用所需工具,以及是否返回该技能所要求的证据。

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

向 GitHub Copilot 添加智能体技能 >

文章《一次构建,可在任何智能体上运行:智能体技能实用指南》首发于 The GitHub Blog。

译文由英文原文机器翻译,术语按行业惯例统一,可在文末展开原文核对。

查看英文原文(Build once, run on any agent: A practical guide to agent skills)

How many times this week did you re-explain the same task to an agent? How many times did you ask your colleague with deep institutional knowledge how to solve a specific problem? That context shouldn’t be lost in a chat or locked in one person’s head. Agent skills let you capture repeatable instructions so you and your agents can reuse them. The skill you write for yourself tonight can later become part of a team’s pipeline.

An agent skill is a versioned directory centered on a SKILL.md file that describes when and how to do a repeatable task. You can share those instructions across agents, but the environment still needs to provide the tools, credentials, and permissions to carry them out. A skill can describe how to query a database, for example, but it doesn’t grant access to that database.

I covered this topic live with Shishir Tewari, Senior Manager, Data Engineering at Procore, during GitHub Universe 2026. Our session was titled “Build once, run on any agent: a practical guide to agent skills”.

Define one job and when it applies

A skill works best when it has a clear job, input, and output. For example, let’s say you’re building an agent that checks AI-generated changes against the original request. If the same agent assesses its own work, its explanation might influence the review. With Proof Agent, we use a separate verifier to examine the changes and provide evidence for its findings. The skill’s frontmatter names the task and describes its purpose:

---
name: proof-agent
description: Adversarial verification of AI-generated work. Spawns an independent verifier to check for false claims, broken code, and security issues.
---

At the center is a simple rule: self-verification is not verification.

The When to Verify section in Proof Agent’s SKILL.md says when to invoke the skill. The remaining instructions explain what the verifier reviews and what evidence to include in its findings.

Coordinate multiple skills for a larger workflow

When the judgment that makes a data pipeline correct lives in four different people’s heads, those four people are the roadmap. Each change to the pipeline depends on their availability and knowledge of the data. Data Forge is an example of how to capture parts of that judgment in skills that work together.

In the support-desk pipeline example, we start with a request for metrics that count incidents created and resolved. Before building the pipeline, the forge-init skill discovers details such as source tables and naming conventions, then writes them to a resolved manifest. The other skills read that manifest for the project context they need.

The forge-builder skill then coordinates the work from the issue through to a pull request. It uses forge-dbx to query the data platform and forge-lint to apply the team’s standards as it designs and builds the pipeline. A person reviews the proposed decisions along the way, and the resulting pull request contains the pipeline code, schema changes, and tests.

Each skill has a defined responsibility, and they share project context instead of rediscovering it independently. When a step changes, you can change one skill and leave the rest alone.

Skills fit bounded, repeatable work that benefits from reusable judgment, such as a checklist, release, migration, or metric pipeline. If a workflow needs a stable interface, shared state, an audit trail, long-running control, or permissions enforced outside the model, an application is a better fit.

Keep project configuration out of the skill

We don’t want to hardcode every project’s names, database, or conventions into the skills. In the Data Forge support-desk example, a manifest describes the project, metric store, and platform so the skills can use the right project details without baking them into their instructions:

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

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

With the discovered details in the resolved manifest, the other skills don’t have to make their own assumptions about the project.

Keep discovered project details separate from team standards. The forge-init initialization skill can inspect existing schemas and code patterns; the forge-lint skill supplies the rules to follow before code is generated. A pattern found in a repository isn’t automatically a rule to preserve, so make discovered details reviewable and let people confirm or change them where business judgment is needed. To check portability, ask: could another team use these skills with its own manifest without rewriting them?

Share execution paths between skills

The forge-dbx skill gives the other Data Forge skills one way to access the data platform. It reads the manifest and selects a Databricks or DuckDB adapter, so each skill doesn’t need its own connection and query logic.

The manifest can choose DuckDB for the local support-desk demo, but it can’t install the DuckDB CLI or grant database access. Those remain setup responsibilities for the environment and its user. The manifest picks the engine; the host provides the access.

Put checks and approval points in the workflow

The Data Forge support-desk workflow has seven phases, with a human checkpoint at each one. The workflow overview shows how the skills fit together. Before a phase proceeds, the workflow checks that the previous phase is complete; before schema changes run, it asks for approval.

The Proof Agent example applies the same principle to code review. A GitHub Actions workflow gives the verifier the original request and code changes, but not the coding agent’s own assessment. The verifier returns PASS, FAIL, or PARTIAL and must cite evidence in the changed files. The GitHub Action does a static review of the diff; it doesn’t execute code or run tests. In the demo workflow, we set block-on-fail: false so findings were advisory. By default, a FAIL fails the check, which blocks the merge if the check is required. The aim is to keep test results and merge requirements in your repository’s CI checks and rules.

Package for each agent client, then verify its setup

Supporting multiple clients can mean keeping several copies of the same instructions in sync. In the Data Forge example, we keep skills/*/SKILL.md as the source and use a packaging script to generate client-specific files: .claude-plugin/plugin.json for Claude Code, .cursor-plugin/plugin.json for Cursor, and .github/agents/*.agent.md for GitHub Copilot. The script also includes a check mode for CI:

node scripts/package.mjs --check

Clients can differ in their available models, tools, credentials, and permissions. After installing a skill, check that the client recognizes it for the intended task, loads its references, can use the required tools, and returns the evidence the skill calls for.

Three practices for building agent skills

  1. Put business context in one file. Keep project-specific names, schemas, and conventions in a manifest, and have each skill read it instead of duplicating those facts. This gives the team one visible place to update configuration.
  2. Give related skills one consistent way to use the platform. Have related skills use the same path to run queries, jobs, and schema changes instead of each defining its own commands and connection logic. This makes the workflow’s access easier to understand and its behavior easier to check in each client.
  3. Use instructions to guide the work, and checks to verify it. A skill can tell an agent which standards to follow and when to ask for approval. Add human review at decisions that need context or judgment, and use tests and CI checks to catch issues before a change moves forward. If a check must block a merge or deployment, configure that requirement in your repository’s rules.

Start with the task you’re tired of explaining. Write down what it needs, where it stops, and what a reviewer sees. Then try it with another agent and improve it as you learn what works.

The post Build once, run on any agent: A practical guide to agent skills appeared first on The GitHub Blog.

正文保留英文原文,标题与摘要由机器翻译。

本文由采集器自动同步

原文发布于 GitHub Blog(Build once, run on any agent: A practical guide to agent skills),标题、摘要与正文由机器翻译,术语按行业惯例统一,未经人工逐句校订。

阅读原文 ↗