AI Pulse

向Agent重复解释任务?写成一个技能文件,让团队复用你的指令

向Agent重复解释任务?写成一个技能文件,让团队复用你的指令

这周你有多少次向 agent 重新解释同一个任务?又有多少次需要去问那位掌握深层业务知识的同事某个具体问题怎么解决?这些上下文不应该丢在聊天记录里,也不应该锁在某个人的脑子里。Agent skills(智能体技能)能帮你把可重复执行的指令沉淀下来,让你和你的 agent 都能复用。你今晚给自己写的技能,以后可能成为团队流水线的一部分。

一个 agent skill 是一个带版本管理的目录,核心是 SKILL.md 文件,它描述一项可重复任务在什么时候做、怎么做。你可以在不同 agent 之间共享这些指令,但执行时仍然需要环境提供相应的工具、凭据和权限。比如,技能可以描述如何查询数据库,但它本身不会授予数据库访问权限。

定义单一职责和适用时机

技能在职责、输入和输出都清晰时效果最好。假设你要构建一个 agent,用来检查 AI 生成的变更是否符合原始需求。如果让同一个 agent 自我评估自己的产出,它的解释可能会影响评审结果。在 Proof Agent 中,我们使用一个独立的 verifier(校验器)来审查变更,并为结论提供证据。技能 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”(何时验证),说明何时调用这个技能;其余指令则说明 verifier 要审查什么,以及结论中需要包含哪些证据。

用多个技能协调更大的工作流

如果一条数据管线的正确性判断分散在四个不同的人脑子里,那么这四个人就是路线图:管线的每次变更都取决于他们是否有空、是否了解这批数据。Data Forge 是一个把这类判断的一部分沉淀为可协作技能的示例。

在 support-desk 管线示例中,需求是统计已创建和已解决的事故数量。在构建管线之前,forge-init 技能会先探查源表、命名约定等细节,并把结果写入 resolved manifest(解析后的清单)。其他技能从这份 manifest 中读取它们需要的项目上下文。

随后,forge-builder 技能负责从 issue 到 pull request 的整个协调工作。它在设计和构建管线时,用 forge-dbx 查询数据平台,用 forge-lint 应用团队的标准。过程中会有人工来复核各项决策;最终生成的 pull request 包含管线代码、schema 变更和测试。

每个技能都有明确的职责,并且共享项目上下文,而不是各自重新发现一遍。当某个步骤发生变化时,你只需要修改对应的一个技能,其他技能可以保持不变。

技能适合边界清晰、可重复、能从可复用判断中获益的工作,比如检查清单、发布、迁移或指标管线。如果工作流需要稳定接口、共享状态、审计轨迹、长期运行控制,或需要在模型之外强制执行权限,那用 application(应用)会更合适。

把项目配置从技能里拿出来

我们不想把每个项目的名称、数据库或约定硬编码到技能里。在 Data Forge 的 support-desk 示例中,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 可以为本地 support-desk 演示选择 DuckDB,但它不能安装 DuckDB CLI,也不能授予数据库访问权限。这些仍然是环境和用户需要负责的初始化工作。manifest 选择引擎,宿主机提供访问权。

在工作流中加入检查和审批点

Data Forge 的 support-desk 工作流分为七个阶段,每个阶段都设有人工检查点。工作流总览会展示各个技能如何衔接。在一个阶段继续前,工作流会确认上一阶段已完成;在运行 schema 变更前,会请求审批。

Proof Agent 示例把同样的原则应用在代码评审上。GitHub Actions 工作流把原始需求和代码变更交给 verifier,但不提供 coding agent 自己的评估。verifier 返回 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

不同客户端可用的模型、工具、凭据和权限可能不一样。安装技能后,要检查客户端能否在目标任务中识别它、加载它的引用、使用所需工具,并返回技能要求的证据。

构建 agent skills 的三个实践

- 把业务上下文放进一个文件。 将项目特有的名称、schema 和约定放在 manifest 中,让每个技能都读取它,而不是各自复制这些事实。这给团队一个可见的、集中更新配置的地方。
- 让相关技能用同一种方式使用平台。 让相关技能通过同一条路径运行查询、任务和 schema 变更,而不是各自定义自己的命令和连接逻辑。这样工作流的访问方式更容易理解,行为也更容易在每个客户端中检查。
- 用指令引导工作,用检查验证工作。 技能可以告诉 agent 要遵循哪些标准、何时请求审批。在需要上下文或判断的决策点加入人工评审,并用测试和 CI 检查在变更推进前发现问题。如果某项检查必须阻止合并或部署,就在仓库规则中配置这个要求。

从一个你已经解释腻了的任务开始。写下它需要什么、它的边界在哪里、评审者会看到什么。然后换一个 agent 试试,在实践中学到什么有效,再不断改进。

阅读原文
📚 相关主题 AI Agent工程实操指南

订阅 AI Pulse

每天 08:00 · 12:30 · 18:30 · 23:50 更新