Agent Skills 工程化深度解析：用 skill-creator 测试、度量并持续改进技能

一、引言：Agent Skill 不能只“写出来试试看”

原文链接：Improving skill-creator: Test, measure, and refine Agent Skills
来源：Claude Blog / Anthropic
发布时间：2026 年 3 月

过去我们谈 Agent Skills，重点常常放在“怎么写”：如何把一套工作流整理进 SKILL.md，如何描述触发场景，如何给 Claude 提供工具、示例和约束。这个阶段很像早期提示词工程：把经验沉淀下来，让模型在特定任务上表现更稳定。

但真正进入团队协作之后，问题会从“能不能写一个 Skill”变成更工程化的三个问题：

1. 它真的比不用 Skill 更好吗？
2. 模型更新后，它还像上个月一样可靠吗？
3. 它会不会在错误场景触发，或者在该触发时没触发？

Anthropic 这篇文章的核心价值，就是把 Agent Skills 从“提示词资产”推进到“软件化能力资产”：Skill 不只是写出来给 Claude 读的说明书，而是需要被测试、被度量、被回归验证、被持续迭代的工程对象。

下面这张图概括了本文的主线：

图注：这张示意图建议放在引言之后，用来建立全局直觉：SKILL.md 只是起点，后面还需要 eval suite、benchmark、多智能体评估、A/B 盲评和触发描述优化，最终形成持续迭代闭环。本文配图均为作者基于原文机制整理的概念示意，并非 Anthropic 官方架构图。

二、核心概念：什么是 Agent Skills，为什么需要 skill-creator

Agent Skills 可以理解为一种面向 Claude 的能力扩展包。它通常包含任务说明、执行步骤、判断标准、工具使用方法、示例和注意事项。与一次性的 prompt 不同，Skill 的目标是让某类任务形成可复用的工作流。

例如：

• 一个文档生成 Skill，可以告诉 Claude 如何根据组织模板写技术方案；
• 一个 PDF 处理 Skill，可以告诉 Claude 如何提取、填写和校验 PDF；
• 一个 NDA 审查 Skill，可以编码法务团队对风险条款的检查标准；
• 一个周报生成 Skill，可以规定从哪些 MCP 数据源读取信息、按什么格式汇总。

skill-creator 则是帮助作者创建和改进 Skills 的工具。原文介绍的更新重点，不再只是“辅助生成 Skill”，而是增加了测试、benchmark、评估和描述优化能力。

换句话说，skill-creator 的角色正在从“脚手架生成器”变成“Skill 质量工程平台”。

2.1 为什么普通 prompt 不够

普通 prompt 很适合一次性任务，但不适合长期沉淀团队流程。原因很简单：

如果一个团队只是偶尔用 Claude 辅助写文档，prompt 足够了；但如果希望把某个流程稳定地交给 Agent 执行，就必须回答“怎么证明它一直有效”。这就是 evals 进入 Skill 创作流程的原因。

三、两类 Skills：能力增强型与偏好编码型

原文把 Agent Skills 分成两类：capability uplift skills 和 encoded preference skills。这一区分非常重要，因为两类 Skill 的生命周期、评估重点和淘汰方式都不同。

图注：建议在本节开头插入这张左右对照图。左侧展示 capability uplift skill 如何补足模型短板，右侧展示 encoded preference skill 如何固化团队流程；中间用“验证重点”和“生命周期”两条轴强调它们的评估差异。

3.1 Capability uplift skills：补足模型当前短板

Capability uplift skills 的目标是让 Claude 完成基础模型本身还不能稳定完成的任务。它更像一组外置的“解题策略”或“任务诀窍”。

典型例子包括：

• 让 Claude 更稳定地生成复杂格式文档；
• 让 Claude 学会某种领域特定的代码审查模式；
• 让 Claude 在处理 PDF、表格、演示文稿等复杂文件时使用更可靠的步骤。

这类 Skill 的一个特殊点是：它可能会随着基础模型变强而逐渐失去必要性。

如果新版模型在不加载 Skill 的情况下也能通过同一组 evals，那么说明这个 Skill 解决的问题可能已经被模型内化了。这不是失败，而是一种正常的生命周期变化：Skill 从“必要辅助”变成“历史训练轮”。

3.2 Encoded preference skills：固化团队真实偏好

Encoded preference skills 的目标不是补足模型能力，而是把组织内部的流程、标准和偏好编码进去。

典型例子包括：

• 法务团队的 NDA 审查标准；
• 产品团队的 PRD 写作结构；
• 安全团队的风险分级规则；
• 工程团队的周报汇总格式；
• 公司内部审批、合规或客服流程。

这类 Skill 不会因为模型变强就自然消失。即使模型再强，它也不可能凭空知道某个团队“希望怎样做”。因此它的核心评估问题不是“模型能不能做”，而是：它是否忠实反映了真实工作流？

3.3 两类 Skill 的评估差异

这个分类能帮助我们避免一个常见误区：用同一套标准评估所有 Skills。能力增强型 Skill 需要证明“有它更好”；偏好编码型 Skill 需要证明“它按我们的方式做”。

四、evals：把 Skill 当作软件一样测试

原文最关键的工程化转向，是把 evals 引入 Skill 创作。可以把 eval 理解为 Agent Skill 的测试用例：给定输入、附件和评价标准，观察 Claude 是否在加载 Skill 后产生符合预期的行为。

一个 eval 通常包含三类信息：

1. 测试 prompt：模拟真实用户会怎样提出任务；
2. 相关文件：例如 PDF、合同、表格、模板或历史样例；
3. 通过标准：描述什么样的输出算好，什么样的行为算失败。

图注：这张流程图建议放在 evals 概念解释之后。它从 prompt、附件和 rubric 开始，经过隔离执行、输出采集、自动/人工评判，最终进入 Skill 修改和回归验证，强调 eval 不是一次性检查，而是持续闭环。

4.1 eval 不是“看起来不错”的主观判断

没有 eval 时，Skill 质量往往靠作者试几个样例，然后凭感觉判断“好像有用”。这种方式有三个问题：

• 不可重复：今天试得好，不代表下次还好；
• 不可比较：Skill v1 和 v2 谁更好，很容易被单个样例误导；
• 不可回归：模型、工具或基础设施变化后，很难知道哪里坏了。

有了 eval 之后，Skill 的质量就能被拆成更清楚的指标：

4.2 一个概念性的 eval 配置长什么样

不同平台和工具的具体格式可能不同，下面只是一个便于理解的概念模板，不代表官方固定语法：

name: nda-risk-review
skill: nda-reviewer
prompt: >
  Review this NDA for enterprise procurement approval.
  Return risks using our internal severity labels.  
attachments:
  - samples/vendor-nda.pdf
expected:
  must_include:
    - confidentiality term
    - liability cap
    - governing law
    - unilateral termination clause
  must_not_include:
    - generic legal disclaimer only
judge:
  mode: rubric
  pass_if: "all required clauses are checked and risk labels follow team policy"
metrics:
  - pass_rate
  - elapsed_time
  - token_usage

图注：如果文章发布平台支持配图，这里建议插入一张“代码截图式”SVG，而不是普通代码块截图。图中展示一个 NDA 审查 eval 的概念配置：输入 prompt、附件、必查条款、评判方式和采集指标，帮助读者快速理解 eval 的组成。

4.3 eval 的两个核心用途

用途一：捕捉质量回归

Agent 系统不是静止的。基础模型会升级，工具实现会变化，MCP Server 可能调整返回字段，组织模板也会改版。一个上个月表现稳定的 Skill，这个月可能因为依赖环境变化而出现回归。

如果没有 eval，团队往往只能等用户发现问题；如果有 eval，就可以在发布前、模型升级后或 CI 定时任务中提前发现退化。

用途二：判断 Skill 是否仍然必要

对于 capability uplift skills，eval 还有一个很有意思的作用：判断基础模型是否已经“学会了”原本 Skill 提供的技巧。

实践上可以做三组对比：

1. 加载 Skill 的 Claude；
2. 不加载 Skill 的 Claude；
3. 修改后的 Skill 或新版 Skill。

如果第 2 组也能稳定通过 eval，说明这个 Skill 可能不再提供明显增益。此时团队可以选择简化、合并或下线它，把维护成本留给更有价值的工作流。

五、benchmark 与多智能体评估：让测试更快、更干净、更可比较

单个 eval 很容易理解，但真正有用的是 eval suite：一组覆盖常见场景、边界场景和反例场景的测试集合。

当 eval 数量变多后，顺序运行会遇到两个问题：

1. 慢：几十个甚至上百个 eval 顺序跑，反馈周期太长；
2. 上下文污染：如果多个测试共享上下文，前一个测试的信息可能影响后一个测试。

原文提到的多智能体支持，正是为了解决这两个问题。

图注：这张图建议放在 benchmark 章节。左侧展示 eval suite 并行分发到多个独立 agent，每个 agent 拥有干净上下文；右侧展示 comparator agent 对 Skill v1/v2 或 Skill/no Skill 的输出做盲评，从而降低评判偏差。

5.1 每个 eval 都应该有干净上下文

对 Agent 测试来说，干净上下文非常重要。因为模型很容易从前文中获得提示，例如：

• 前一个 eval 已经暴露了答案模式；
• 前一个失败案例让模型“猜到”下一题该注意什么；
• 某些附件或规则残留在上下文中，影响后续判断。

多智能体评估的核心思想是：每个 eval 由独立 agent 执行，拥有独立上下文、独立 token 统计和独立耗时指标。

这样做带来三个好处：

• 结果更接近真实用户单次调用；
• 每个测试的成本和延迟可以独立分析；
• 并行执行显著缩短反馈周期。

5.2 comparator agent：让 A/B 对比更接近盲评

很多 Skill 改动不是简单的 pass/fail，而是质量差异。例如：

• v2 的结构更清晰，但遗漏了一个风险点；
• v1 更保守，v2 更像团队语气；
• 无 Skill 输出更简洁，但不符合内部格式。

这时就需要 comparator agent。它不直接执行任务，而是比较两个输出，判断哪一个更符合 rubric。为了减少偏差，比较器不应该知道哪个输出来自哪个版本。

常见对比方式包括：

5.3 benchmark 不是只看通过率

通过率当然重要，但只看通过率很容易误判。一个 Skill 即使通过率提升，也可能带来不可接受的延迟或成本。

建议至少同时观察三类指标：

1. 质量指标：pass rate、rubric score、人工偏好胜率；
2. 效率指标：elapsed time、工具调用次数、重试次数；
3. 成本指标：input token、output token、工具费用。

对于生产团队来说，最佳 Skill 不是“理论输出最完美”的 Skill，而是在质量、延迟、成本和可维护性之间达到稳定平衡的 Skill。

六、触发治理：Skill 描述比很多人想象得更关键

evals 主要评估 Skill 被使用之后的输出质量。但在真实系统里，还有一个更前置的问题：Skill 是否在正确场景触发？

随着 Skills 数量增加，触发治理会越来越重要。原因很简单：每个 Skill 的 description 都像一个“路由规则”。写得太宽，会在不该触发时触发；写得太窄，会在该触发时缺席。

图注：这张图建议放在触发治理章节。图中左侧展示用户 prompts 流入 description gate，右侧用 false positives、false negatives 和 sweet spot 说明描述优化的目标：既不过宽，也不过窄。

6.1 false positive：不该触发时触发

描述太宽时，Skill 会抢走不属于自己的任务。例如一个“写技术设计文档”的 Skill，如果描述成“用于所有技术写作”，它可能会在用户只是想写一封简短邮件时触发。

误触发的危害包括：

• 输出过度结构化；
• 引入不必要的工作流步骤；
• 消耗更多 token；
• 与其他更合适的 Skill 冲突。

6.2 false negative：该触发时没触发

描述太窄时，Skill 会错过本该处理的任务。例如一个“审查 NDA”的 Skill，如果描述只写“用于审查英文 NDA PDF”，那么用户上传 Word 版 NDA、或者说“帮我看看这份保密协议风险”，它可能不会触发。

漏触发的危害更隐蔽：用户看到的是普通模型输出，可能以为 Skill 本身没价值，实际上是触发描述没有覆盖真实表达方式。

6.3 如何优化 Skill description

原文提到，skill-creator 可以分析当前描述和样本 prompts，并建议修改 description，以减少误触发和漏触发。Anthropic 在文档创建类 Skills 上运行该能力后，6 个公开 Skills 中有 5 个触发效果得到改善。

一个实用做法是同时准备正例和负例：

description 的目标不是覆盖所有词面表达，而是清楚描述任务边界：何时应该使用、何时不应该使用、与相邻 Skill 如何区分。

七、实践案例一：PDF 非可填写表单如何用 eval 定位失败点

原文提到一个很典型的案例：PDF Skill 在处理 non-fillable forms 时表现不佳。可填写表单通常有明确字段，Agent 只要把值写入字段即可；但不可填写表单没有结构化字段，Claude 需要根据页面文本和坐标，把内容放到正确位置。

这类问题非常适合用 eval 定位，因为失败可能发生在多个环节：

1. PDF 文本提取不完整；
2. 坐标定位不准确；
3. Agent 没有识别出标签和填写区域的对应关系；
4. 输出 PDF 的渲染位置偏移；
5. 验证逻辑只检查了文本存在，没有检查位置。

7.1 eval 应该怎样设计

一个好的 PDF 表单 eval 不应该只问“有没有填上内容”，而要定义更具体的通过标准：

原文提到的修复方向是基于提取出的文本坐标进行 anchoring。这个细节很关键：它不是让模型“凭感觉”猜位置，而是把页面已有文本作为锚点，围绕锚点计算填写区域。

7.2 这类案例给 Skill 作者的启发

PDF 案例说明，eval 不只是最终验收工具，也可以帮助定位 Agent 工具链中的失败环节。尤其当任务涉及文件、坐标、格式和外部工具时，单看最终输出很难知道哪里错了。

建议把复杂文件处理 Skill 的 eval 拆成多层：

1. 解析层 eval：文件内容是否正确提取；
2. 推理层 eval：字段和目标位置是否正确匹配；
3. 执行层 eval：工具调用结果是否正确生成；
4. 回归层 eval：历史失败样例是否不再复现。

八、实践案例二：NDA 审查 Skill 如何评估“忠实执行团队标准”

NDA 审查 Skill 是 encoded preference skill 的典型例子。它的价值不在于 Claude 是否懂法律常识，而在于它是否按照某个团队的内部标准审查。

例如，一个采购法务团队可能要求每次审查必须覆盖：

• 保密期限是否过长；
• 责任限制是否对等；
• 适用法律和争议解决是否符合公司政策；
• 是否存在单方解除、过宽定义或不合理赔偿条款；
• 输出是否按“高 / 中 / 低风险 + 修改建议”的格式呈现。

8.1 eval 的关键不是泛泛而谈

如果 eval 的通过标准只是“指出风险”，Claude 很容易给出看似专业但不可验证的回答。更好的标准应该接近团队检查表：

通过条件：
1. 必须逐项检查 8 个指定条款；
2. 每个风险必须映射到内部风险等级；
3. 对高风险项必须给出可发送给供应商的修改建议；
4. 不得只输出泛泛的法律免责声明；
5. 如果条款缺失，必须明确标记“未发现”。

这类 Skill 的 eval 更像流程合规测试，而不是知识问答测试。

8.2 失败案例比成功案例更有价值

NDA 审查 Skill 应该保留一些“容易漏”的样例，例如：

• 条款被拆散在多个段落中；
• 风险点用委婉措辞表达；
• 合同中存在互相矛盾的条款；
• 缺失某个关键条款但没有显式写“缺失”；
• 用户要求“简单总结”，但实际希望做风险审查。

这些样例能帮助 Skill 作者判断：Skill 是真的理解了团队标准，还是只是在输出一份看起来像审查报告的文本。

九、实践案例三：周报生成 Skill 如何测试 MCP 数据整合

周报生成 Skill 也是 encoded preference skill，但它多了一个复杂点：它往往需要从多个外部系统获取数据，例如项目管理、代码仓库、告警平台、文档系统和工单系统。这通常会通过 MCP Server 暴露给 Agent。

这类 Skill 的 eval 不能只看最终周报写得好不好，还要看数据链路是否正确：

9.1 周报 Skill 的 eval suite 可以分层

建议至少准备四类测试：

1. 标准样例：所有数据源可用，验证主流程；
2. 缺失样例：某个数据源为空，验证是否说明缺口；
3. 冲突样例：多个系统对同一事项状态不同，验证是否保守表达；
4. 格式样例：同样数据以不同用户表达触发，验证输出结构稳定。

这样做的好处是，Skill 作者可以知道失败到底来自数据获取、信息整合、格式输出还是触发描述。

十、落地方法：如何为一个 Skill 建立最小可用评估体系

如果团队刚开始做 Agent Skills，不建议一上来建设复杂平台。可以从一个最小闭环开始。

10.1 第一步：定义 Skill 的价值假设

每个 Skill 都应该先回答一句话：如果这个 Skill 成功，它具体改善了什么？

示例：

• PDF Skill：减少复杂 PDF 处理中的格式错误；
• NDA Skill：让审查输出稳定覆盖内部检查表；
• 周报 Skill：把跨系统信息整合时间从 30 分钟降到 5 分钟；
• 文档 Skill：让输出稳定符合团队模板，而不是每次从头解释。

没有价值假设，就很难设计 eval。

10.2 第二步：准备 5 到 10 个高质量 eval

早期 eval 不需要多，但要覆盖关键场景：

1. 2 个最常见的成功路径；
2. 2 个历史失败样例；
3. 2 个边界输入；
4. 1 到 2 个不应触发的负例；
5. 1 个成本或耗时敏感样例。

这比堆很多浅层测试更有价值。

10.3 第三步：同时跑 Skill 与 no Skill

对于 capability uplift skills，强烈建议每次 benchmark 都包含 no Skill baseline。否则你只能知道 Skill 是否过了测试，却不知道它是否真的带来增益。

比较维度可以包括：

• 输出是否更完整；
• 格式是否更稳定；
• 是否减少工具调用错误；
• 是否降低人工修改量；
• 成本和延迟是否可接受。

10.4 第四步：把失败样例沉淀成回归集

每次线上或人工评审发现失败，都不要只修 SKILL.md。更重要的是把失败样例加入 eval suite。否则同类问题很容易在下一次模型升级或 Skill 修改后再次出现。

一个成熟的 Skill 仓库应该同时包含：

skill/
  SKILL.md
  examples/
  evals/
    positive/
    negative/
    regressions/
  benchmark-results/
  CHANGELOG.md

这不是要求所有团队都照这个目录实现，而是强调一个原则：Skill 的说明、样例、测试和历史结果应该一起版本化。

10.5 第五步：设置发布门禁

当 Skill 被多人使用后，建议引入最低发布门禁：

这套门禁不一定要一开始接入 CI，但至少应该成为 Skill 发布前的检查清单。

十一、从 Skill 到 specification：未来边界会越来越模糊

原文最后提出一个很有启发性的判断：随着模型能力提升，“skill”和“specification”的边界可能会变得模糊。

当前的 SKILL.md 很像 implementation plan：它不仅描述要做什么，还会告诉 Claude 具体怎么做。比如先读取文件、再提取字段、再按模板输出、最后校验格式。

但 eval 描述的是另一件事：什么结果算正确。

当模型足够强时，也许作者不再需要写很细的执行步骤，只需要写清楚：

• 任务目标是什么；
• 输入输出边界是什么；
• 什么行为算成功；
• 哪些行为必须避免；
• 哪些样例代表真实工作流。

也就是说，未来的 Skill 可能更像一组可执行 specification：通过 eval 定义“what”，让模型自己推导“how”。

图注：建议把这张生命周期图放在展望章节。它展示 Skill 从创建、验证、发布、观测、迭代到简化或退役的过程，尤其强调 capability uplift skill 可能被基础模型吸收，而 encoded preference skill 会随组织流程持续演化。

十二、总结：把 Skill 当成可以演进的软件资产

Anthropic 这篇文章真正重要的地方，不是 skill-creator 增加了几个功能，而是提出了一套新的 Skill 工程观：

Agent Skills 不应该停留在“写一份更好的提示词”，而应该进入测试、度量、回归和迭代的工程闭环。

对开发者和团队来说，可以提炼成五条实践原则：

1. 先分类，再评估：区分 capability uplift skills 和 encoded preference skills，不同类型用不同指标判断价值。
2. 用 evals 替代感觉：用 prompt、附件和 rubric 定义可重复测试，而不是靠几次手工试用判断质量。
3. 把 benchmark 作为发布门禁：关注 pass rate，也关注耗时、token、工具调用和失败类别。
4. 用多智能体隔离测试上下文：每个 eval 使用干净上下文，减少污染，并用 comparator agents 做 A/B 盲评。
5. 治理触发描述：description 不是文案，它决定 Skill 何时被路由；要同时降低 false positives 和 false negatives。

如果说早期 Agent 开发的重点是“让模型会做事”，那么 Agent Skills 工程化的重点就是“证明它持续做对事”。这也是从个人效率工具走向团队生产系统时必须跨过的一步。

当 Skills 开始拥有 eval suite、benchmark history、触发样本、回归集和发布门禁时，它们就不再只是散落在文件夹里的提示词，而是可以被维护、被比较、被淘汰、被演进的软件资产。

× 爱折腾的工程师

真诚赞赏，手留余香

2元 5元 10元 50元 100元 任意金额

2元

使用微信扫描二维码完成支付

• ← Previous Post
• Next Post →