agent-skills claude-code ai-agents workflow evaluation

通过技能实现自我提升的智能体：重用、筛选、修复与验证。

一种包含四个环节的设计，用于帮助智能体提升自身能力：保存可用的代码、优化描述内容、提出经过审核的修复方案，并在交接前验证输出结果。

发布者：REACTAPP.TOP加入本站 2026年10月28日阅读约 15 分钟3391 词

来源: Your Agent Keeps Making the Same Mistake. Start With Its Skills.

如果一个编程智能体两次遇到相同的问题，通常是因为它没有合适的地方来存储所学到的知识。whetstone插件背后的理念是：智能体今天的工作应当让明天的工作更加高效。智能体自己编写并测试过的辅助工具应该能在下次使用时依然存在。需要修正的工作流程应当能带来可被他人审查的持久性改变。而在将结果交付给用户之前，所有该任务必需的检查都已经完成。

这些本是普通的工程习惯，却往往只存在于人的脑海中，每次会话结束时都会重复出现。Whetstone将它们归纳为四种能够提升其他技能水平的技巧：重用经过验证的代码、改进技能选择方式、记录流程中的经验教训，以及在结果返回给用户之前对其进行验证。

这里所说的“自我提升型智能体”其实是一个刻意限定的概念。该智能体会帮助改进自身的指令与工具，由人类审核这些变更并决定哪些内容应被保留，模型本身不会被重新训练，也没有任何内容会在后台无人监控的情况下自动学习。

通过对383个技能文件的初步审查，该插件获得了具体的测试环境。不过更具通用价值的是其设计思路：可复用的功能应存储在何处、如何选择合适的干预措施，以及在决定保留某项变更之前需要哪些证据。这些原则无论用于该插件还是基于自身工作流程开发的版本都同样适用。

实际上可以改进的智能体部分

技能相当于一个文件夹，其中包含包含操作说明的SKILL.md文件，可选地还包括脚本和参考文档。开放的Agent Skills规范规定了统一的结构，文件开头会有简短的名称和描述。Anthropic的工程团队将技能视为让通用智能体拥有可复用专业能力的方式，其优势在于无需重新构建运行时即可改进流程。

这涉及两个独立的环节：智能体必须选择合适的技能，而所选技能也必须能够有效指导工作。解决其中一个问题并不会自动解决另一个问题。

Whetstone为其四种技能各自分配了单一职责：

dry-promotion负责保存可复用的代码。
skill-audit用于检查用于技能选择的信息。

skill-repair 提出流程上的修改建议。

verify-before-return 用于检查输出结果。

这种分离方式的有效之处在于每个操作都会修改不同的内容。即便没有出现任何错误，某些辅助功能也可能值得保存；而即使底层流程运行完美，模糊的描述仍需重视。如果让每个请求都经过全部四个操作，就会将无关的工作混为一谈，而独立的入口则允许仅调用任务所需的那一部分功能。

每个操作最终都会产生可查看的结果：磁盘上的文件、审计报告、建议的差异对比或验证证据。这些都有助于调试，也能为审核者提供具体的审批依据。虽然可以借助智能体的帮助，但仅有令人信服的解释并不足以使更改永久生效。

1. DRY原则：保留已成功完成的工作

DRY的意思是“不要重复自己”，也指代理程序应使用其之前生成的可用代码。每当有新的展示请求时，都需要先重新构建渲染器，因此在处理新内容之前必须先解决一个旧的工程问题。

渲染器是可重复使用的工具，而内容则是会变化的部分。Anthropic的文档通过一个运行预写提取脚本的PDF技能说明了类似观点：代码负责处理稳定的机械性工作，而模型则负责做出针对特定任务的决策。

这正是dry-promotion的功能所在。它会将一个有用的辅助脚本复制到技能的scripts/文件夹中，并重新编写指令以使该脚本得以执行。仅仅保存文件是不够的：虽然技能仍然要求代理程序编写脚本，但并没有任何指示让它使用已保存的脚本。

字符计数器是写作工作流中的一个典型示例。字幕有长度限制，小型程序可以负责计算字符数，而模型则专注于内容撰写。相关操作指南可以这样表述：

在返回字幕之前，先运行已存储的字符计数器。如果计数超过限制，就缩短内容后再进行计数。切勿猜测数值，也无需重新构建计数器。

这样做的好处是能够得到可检查、可测试的稳定实现。不过这并不能让整个工作流完全确定化，因为字幕内容本身仍可能变化，而且程序也有可能机械地重复错误的定义。计数器还需要明确是统计Unicode码点还是可见字符，以及如何处理空格和换行符。

在推广某个辅助工具之前，先做好准备工作：移除与特定会话相关的路径，明确输入参数，并在超出最初设计场景的案例上对其进行测试。之后再次运行工作流，确认保存的文件确实是所需的内容。即便最终数值一致，若运行过程中悄悄创建了另一个计数器，那就违背了重用的意义。

模板和共享引用也遵循相同原则。当多个技能共享相同的输出规范时，应保留一个权威版本，让其他技能都引用它。不要仅仅因为两个看似相似的初始示例，就试图通过同一个辅助工具来实现本质上不同的工作流。重用应当保持操作的稳定性，而非掩盖那些重要的差异。

2. 帮助智能体选择合适的技能

通过渐进式披露机制，智能体首先使用轻量级的元数据，只有在选择某项技能时才会加载该技能的完整指令。这样做的实际原因是，提前加载所有步骤会浪费资源在可能永远不会被使用的功能上。

对于自动选择而言，名称和描述便起到了路由信息的作用。文件中间部分精心撰写的说明，在模型决定是否打开该文件时甚至可能都无法获取。

描述并非唯一的筛选方式。Claude Code还支持显式调用，运行时配置也会影响可用内容。不过，描述仍是技能作者能够控制的筛选信号。

扫描某人的技能库后，将同名重复项单独计算、排除冲突情况，得出了以下总结：

383 skills scanned
  missing description           0
  no trigger language         306
  colliding pairs               3
  duplicate names              23
  skills with >=1 defect      306  (79%)

79%这一数值其实是306除以383后的简化结果，实际约为79.9%。那些描述未能通过措辞检查，但这与306次因未使用技能而出现的故障并非同一概念。扫描器仅会检查诸如“在……时使用”或“当用户……时”这类明确的触发语。模型即便没有这些词语的描述也能照做，而带有这些词语的描述也可能过于宽泛而无法提供有效指导。该输出仅作为需要进一步调查的清单，并非衡量智能体故障程度的标准。

为相邻技能分配不同的任务

以同一插件中两个技能的实际描述为例：

其中一人自称是擅长利用向量数据库、嵌入模型及先进检索策略构建检索增强生成系统的专家。另一人则自称是精通选择、配置和调优 Pinecone、Weaviate、Chroma、Qdrant 和 Milvus 等向量数据库以用于语义搜索和 RAG 的专家。

两人的表述都很不错，那么对于需要帮助为 RAG 应用挑选向量存储的用户来说，该选谁呢？能力较强的模型可能会更倾向于第二种更专注的领域，但第一人同样声称自己具备相关能力。由于并未明确说明各自的能力范围，模型不得不自行推断界限。

若能按照这样的方式重新表述，就能更清晰地划分二者的差异。目前尚未对它们进行过基准测试：

name: vector-database-selection
description: >-
  Compare vector databases against workload, filtering,
  deployment, and operating-cost requirements. Use when
  choosing or replacing a vector store. For retrieval-pipeline
  design with an already chosen store, use rag-pipeline-design.

name: rag-pipeline-design
description: >-
  Design ingestion, chunking, retrieval, reranking, and
  evaluation for a RAG application. Use when building or
  diagnosing a retrieval pipeline. For a standalone vector
  database selection, use vector-database-selection.

第一种角色负责选择数据库，第二种角色则负责将文档转化为可用于生成答案的有效上下文。由于两者的工作确实存在重叠，部分词汇需要共享。

在修改任何措辞之前先拟定测试请求。“比较适用于自托管文档搜索应用的向量存储方案”应属于数据库选择范畴；“我们的嵌入向量应该存放在哪里？请帮我决定”不过是换种说法表达相同含义；“我们已经有了向量存储，但检索结果无法找到相关段落”则属于流程诊断范畴。

接着再添加一个两种角色都不应处理的请求，比如调整移动端搜索按钮的间距。如果没有这样的请求，你就只是测试了两种技能中哪一种更优，而非判断智能体是否能够同时拒绝这两项任务。

在全新的会话中使用完全相同的模型、启用的技能及项目上下文进行测试。在任何自动选择测试中都不要提及目标技能的名称，因为命名会改变实验结果。在运行时能够显示相关信息的情况下，记录被加载的技能，并保存生成的答案或结果文件。相比智能体声称使用了正确技能的说法，显示被打开文件的跟踪记录才是更有力的证据。

比较测试前后的结果，并在重写会话中排除一些意译内容，以避免仅针对自身示例进行优化。这套简单的回归测试能够判断某项更改是否对重要请求起到了积极作用。

3. 将经验转化为可复用的指令

发现问题后，更重要的问题是：修正内容应放在何处？

skill-repair会针对处于版本控制下的目标，以差异形式输出修改建议供人审批。其目标是进行最小的编辑来修复已发现的故障，这样审核者就能查看这些修改，若其导致其他问题则可将其撤销。

想象一种撰写报告的技能，它在不查阅源文档的情况下直接返回摘要。即便要求它“更加谨慎”，也几乎无法为其提供具体行动依据。要解决这个问题需先查明为何会跳过相关检查：

流程中从未要求提供源文档：需修改流程。
需要源文档但未给出其位置：需提供相关上下文或补充缺失的输入。
已读取源文档但某图表被错误复制：需采用其他检查方式。

在每种情况下都使用同一条通用警告，反而会完全忽略问题诊断。

请将失败的请求与拟进行的修改放在一起，描述预期的行为，并保留导致失败的相关记录。在新的会话中重新运行该请求，然后尝试执行那些应该仍能正常工作的类似请求。否则，由于修改内容表述得很有说服力，就很容易获得批准，这样便能轻松度过一个下午，却没有任何实质性的改进。

范围也很重要。针对某份报告的偏好设置应保留在该报告中；技能生成的每份报告对应的规则都应存储在技能文件中；那些经常变化的信息则更适合放在技能查询的参考资料中。如果所有的修正都记录在永久性的指令中，那么原本可重复使用的流程就会逐渐变成某个人最后一次会话的记录。

成功案例同样需要妥善处理。当某个流程能够稳定运行时，应保留有用的顺序、输入数据及示例，而不仅仅是关于出错问题的警告。《Agent Skills》的编写指南建议将技能建立在实际工作中，并通过实际执行不断优化。一个技能应当包含下一次运行所缺失的知识，而非记录所有发生过的细节。

当共享指南需要修复时

每个人的技能库都是其个人积累的杂乱内容，由个人使用的工具进行审核，因此大学研究软件团队维护的公共插件仓库也接受了同样的审核。在该快照中，共有12个插件包含76个技能。

这些标记是按插件分类的。有七个插件被全部标记，还有一个科学计算相关的Python插件有五项中的四项被标记。这种分类方式促使人们寻找通用的模板和规范，而贡献指南恰恰就是这样的来源。该指南要求“对代理及其用途进行清晰描述”，并提供了一个占位模板来说明代理的功能，但从未提及何时使用它。共有36项技能正确遵循了该指南，而问题出在指南本身。

据报道，已开启了两个公开问题，一个针对指南，另一个针对那36项描述，且顺序很重要。应先更新规范、给出良好示例，然后再让现有的描述与之保持一致。否则，下一个贡献者即便完全遵循指南，也仍会重现同样的问题。

CI检查能提供帮助，但应先以建议形式使用。如果规则仅识别少数触发短语，将其设置为严格失败条件会促使贡献者不断粘贴这些短语直至构建通过，这样虽然能提升通过率，却无法提升技能水平。真正的验收测试仍需要具有代表性的请求，包括那些该技能应当忽略的请求。

4. 交接前进行验证

verify-before-return为技能提供了验收标准与审核流程。将文件写入磁盘仅是中间步骤，工作流仍需使用适合该任务的依据来检查结果：

对于幻灯片，需先进行渲染，再检查是否有文本被裁剪、标签难以辨认或元素超出画面范围。
对于研究报告，需查看原始资料以确认其能支持论点。
对于代码，则需运行能够测试所需行为的测试。

任何关于任务已完成的声明都应明确指出实际检查了哪些内容。

在生成内容之前先确定相关标准，然后让模型进行初稿撰写，检查问题并修复错误，再对因修复而受影响的检查项重新执行。应限制修改循环的次数，并要求公开所有仍未解决的问题，因为否则“持续改进”可能会变成没有明确结果的无限编辑。

主观性较强的作品需要不同的审查方式。模拟初学者可以指出那些无法解释的术语，持怀疑态度的读者则可以质疑论点。这两种方式都有用，但都属于模型生成的批评意见，并非真实读者的反馈，因此应结合作品的目的来评估每条建议，而非全盘接受所有反对意见。关于风格与策略的判断权仍属于委托创作的人。

进行检测并不等同于执行正确的检测，审计师自身的测试结果便说明了原因。

审计师修改了哪些检测方式

测试显示，审计师必须将重复安装和内容重叠的情况视为不同的问题。首次检测共发现了81组候选对，其中很多都是相同技能但存在于不同的插件缓存版本中。通过分析这些组合，审计师将同名重复项从冲突分析中分离出来，从而使候选对数量降至3组。

正因如此，在依据汇总结果做出任何更改之前，都需要先仔细检查相关记录。重复文件需要清单核查，而内容冲突的情况则需要路由测试。将它们混为一谈会导致人们采取错误的修复措施。

在剔除重复名称后，还发现有23个名称出现在多个扫描路径中。缓存副本并不能证明旧版本处于活跃状态，为此需要检查运行时启用的插件以及实际解析的路径。同样，383这个数字仅统计了已扫描的文件数量，并未包含非活跃的独特技能，而且即便排除了同名项的比较，也仍无法实现整个清单的去重。

该评分仅是一种基于文本特征的估算方法：用两个描述中共有的词汇数除以它们之间不同的词汇数，默认阈值为0.35。某些排除项可能看起来像重叠内容，而对于同一职位但表述不同的两种描述，也有可能被漏掉。此外，前置信息解析器仅支持部分YAML格式。任何标记在最终用于修复之前都需要人工核查。

当修复通过后，需将出问题的案例与旧版本已成功处理的案例一并保存。通过对比这两者，可以判断后续的改动是否在修复某一行为的同时破坏了另一行为。目前尚未检测到“whetstone”在任务成功率方面有整体提升，而这些检查正是用于评估其表现的方式。

打包文件不会移动，技能才会

让“whetstone”在Claude Code之外也能使用是我们的目标。SKILL.md格式的共享为实现这一目标提供了部分帮助。不过某个技能仍可能依赖其他客户端不提供的工具、权限或文件路径，而且不同客户端对插件的打包方式也各不相同。“Agent Plugins”标准、“Claude Code”参考文档以及“OpenCode”文档都对这些结构进行了说明。

Whetstone通过同一个共享的skills/目录来传输两份清单。相关流程被集中保存在一处，同时会单独测试每个客户端的集成情况。不过，可移植的说明并不能保证模型之间的互操作性，因此需要在另一个兼容的运行环境中执行相同的示例任务，检查其工具调用、依赖项及输出结果，才能确定行为是否一致。

在某个工作流中测试

无需使用大型库。只需选择一种工作流，比如智能体不断重新构建的辅助工具、它混合使用的两种技能，或是你通常需要手动完成的输出结果。保留一个具有代表性的请求及其结果，以便进行对比。

接下来，选择合适的处理方式：重用现有的辅助工具、细化选择范围、录制流程教学视频，或添加缺失的验证检查。然后将本次运行结果与保存的示例进行对比。更全面的清单可以稍后处理，也不应仅仅因为递归扫描发现了旧文件就删除旧的缓存。

该项目采用 MIT 许可证。对于 Claude Code，其 README 中提供了以下安装命令：

claude plugin marketplace add cdcore09/whetstone
claude plugin install whetstone@whetstone

提供了四个入口点：/audit、/promote、/repair和/verify。可根据工作流程选择合适的入口点使用。首次使用时，建议先让其检查相关文件并提出修改建议，再实际应用任何更改。

若想在不安装任何软件的情况下测试该审计工具，可克隆仓库并阅读skills/skill-audit/scripts/audit_skills.py文件。从仓库根目录运行下方命令即可，且仅需要使用Python的标准库：

python3 skills/skill-audit/scripts/audit_skills.py ./skills

将 ./skills 替换为你要检查的目录，可以先从你熟悉的小型技能集开始，然后再扫描机器上的所有插件缓存。--json 可以生成结构化的报告，而 --threshold 0.25 则会显示更多重叠的描述信息。

该脚本仅用于读取文件，不会修改任何技能内容。退出状态为 1 表示发现了标记、候选项冲突或重复名称，但这并不一定意味着 Python 程序崩溃。其默认的目录结构也无法覆盖所有客户端的安装布局，因此指定明确的路径能让检查范围更清晰，也便于复现问题。如果报告包含了私有技能描述或文件系统路径，请将其保存在本地，只需分享统计数据和匿名示例，无需列出内部项目的完整清单。

目标是积累有用的成果：可重复使用的代码、可审查的流程，以及随任务一同存在的检查机制。这是实现自我提升型智能体的实用切入点，且所有内容都处于版本控制之下。任何需要不同实现方式的工作流程，都可以通过四个问题来思考：什么可以复用、什么需要选择、什么需要学习，以及如何检查结果。