一次构建，随处运行：agent 技能实用指南

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

智能体技能是一个以 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: 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。其他技能会读取该 manifest，以获取所需的项目上下文。

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

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

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

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

写成 {{NAME_ab12cd34}} 这样的值是真实值的占位符。在回复和工具调用中都应完全按照原样使用它们：它们会在任何内容运行之前被填入真实值。不要要求验证它们，也不要用示例替换它们。

文章标题：一次构建，在任意 agent 上运行：agent skills 实用指南

我们不想把每个项目的名称、数据库或约定硬编码到 skills 中。在 Data Forge 支持台示例中，清单描述了项目、指标存储和平台，这样 skills 就能使用正确的项目详细信息，而无需将它们固化到指令中：

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

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

借助已解析清单中发现的详细信息，其他 skills 不必再对项目做出自己的假设。

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

在 skills 之间共享执行路径

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

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

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

Data Forge 支持台工作流有七个阶段，每个阶段都有一个人工检查点。工作流概览展示了这些 skills 如何组合在一起。在某个阶段继续之前，工作流会检查上一阶段是否完成；在运行 schema 更改之前，它会请求批准。

Proof Agent 示例将同样的原则应用于代码审查。GitHub Actions 工作流将原始请求和代码更改提供给验证器，但不提供编码 agent 自己的评估。验证器返回 PASS、FAIL 或 PARTIAL，并且必须引用更改文件中的证据。GitHub Action 对 diff 进行静态审查；它不执行代码或运行测试。在演示工作流中，我们设置了 block-on-fail: false，因此发现是建议性的。默认情况下，FAIL 会使检查失败，如果该检查是必需的，则会阻止合并。目的是将测试结果和合并要求保留在仓库的 CI 检查和规则中。

为每个 agent 客户端打包，然后验证其设置

支持多个客户端可能意味着要让同一指令的多个副本保持同步。在 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
      

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

构建 agent skills 的三项实践

• 将业务上下文放在一个文件中。将项目特定的名称、schema 和约定保留在清单中，并让每个 skill 读取它，而不是复制这些事实。这为团队提供了一个可见的配置更新位置。

• 为相关 skills 提供一种一致的方式来使用平台。让相关 skills 使用相同的路径来运行查询、作业和 schema 更改，而不是各自定义自己的命令和连接逻辑。这使工作流的访问更容易理解，其行为在每个客户端中更容易检查。

• 用指令指导工作，用检查验证工作。技能可以告诉智能体应遵循哪些标准，以及何时请求批准。在需要背景信息或判断的决策处加入人工审核，并使用测试和 CI 检查在变更推进前发现问题。如果某项检查必须阻止合并或部署，请在仓库规则中配置该要求。

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

将智能体技能添加到 GitHub Copilot >

标签：

• GitHub Copilot

• GitHub Universe

作者：

Andrea 是 GitHub 的高级开发者倡导者，在开发者工具领域拥有超过十年的经验。她将技术深度与一项使命相结合：让先进技术更易获取。从军旅生涯和建筑管理转向软件开发后，她以独特视角将复杂工程概念与实际实施连接起来。她与威尔士伴侣、两个儿子和两只狗住在佛罗里达州，并在那里继续通过 GitHub 的全球计划推动创新并支持开源。可在网上通过 @acolombiadev 找到她。

写成 {{NAME_ab12cd34}} 形式的值是真实值的占位符。请完全按书写原样使用它们，无论是在回复中还是在工具调用中：它们会在任何内容运行之前被填入真实值。不要要求验证它们，也不要用示例替换它们。