返回博客列表

Skill 写好了怎么测？Claude Code 官方 skill-creator 评估全拆解

2026-05-28T07:55:00+08:00
Claude CodeSkillEvalskill-creatorskillgradeAgent

Skill 写好了怎么测？Claude Code 官方 skill-creator 评估全拆解

你花了两小时写了一个 Skill。SKILL.md 结构清晰，描述精准，步骤详细。你试了一下，效果很好。

但问题是——"试了一下"不等于"真的能用了"。

你试的那个 prompt 能触发 Skill，换个说法还能触发吗？输出质量稳定吗？有没有 edge case 会崩？这些都不靠"试一下"能回答的。

Claude Code 官方的 skill-creator 插件内建了一套完整的评估体系。不是"感觉不错就行"，而是三维度量化：触发准确率、输出质量、效率指标。这篇文章把这套体系拆开讲清楚，同时介绍三个第三方评估工具作为补充。

本文提纲

  1. 三个维度：触发、质量、效率
  2. 触发准确率（Trigger Accuracy）
  3. 输出质量（Output Quality）
  4. 效率指标（Efficiency Metrics）
  5. skill-creator 的完整评估流程
  6. 三个第三方评估工具
  7. 写好 eval 的核心原则

三个维度：触发、质量、效率

一个 Skill 好不好，不是"能不能跑"的问题，而是三个维度都要过关：

graph TB
    subgraph SkillEval
        TA["Trigger Accuracy
Did the skill fire?"]
        OQ["Output Quality
Was the result correct?"]
        EM["Efficiency Metrics
How much did it cost?"]
    end
    TA -->|skill triggered| OQ
    OQ -->|result correct| EM
    EM -->|cost acceptable| PASS["Skill Ready"]

触发准确率：用户说了 X，Skill 该不该被触发？该触发的时候触发了没有？不该触发的时候有没有误触？这是第一关——Skill 没触发，后面都是空谈。

输出质量：Skill 被正确触发后，输出对不对？符不符合预期？这是第二关——触发了但输出一塌糊涂，还不如不触发。

效率指标：完成这个任务花了多少 token？多少时间？跟没有 Skill 的 baseline 比怎么样？这是第三关——如果 Skill 反而让 Agent 更慢更贵，它就没有存在价值。

三个维度，一关不过就不算过关。

触发准确率（Trigger Accuracy）

触发准确率是 Skill 评估里最微妙的部分。它要回答两个问题：

该触发的时候触发了吗？（Recall）

Skill 的 description 是触发的核心机制。Claude Code 在每次会话开始时，会看到所有可用 Skill 的 name + description（约 100 词），然后根据用户的 prompt 决定是否加载这个 Skill。

问题来了：用户可能用各种方式表达同一个需求。比如你有一个"部署到 AWS"的 Skill：

  • "帮我把这个项目部署到 AWS" ✅ 应该触发
  • "这个项目要上云" ✅ 也应该触发
  • "生产环境怎么搭" ✅ 可能应该触发
  • "我想让这个应用能在互联网上访问" ✅ 也可能应该触发

如果你的 description 只写了"Deploy project to AWS using CloudFormation"，上面后三条大概率不会触发。

不该触发的时候别触发（Precision）

同样危险的是误触。你有两个 Skill：一个是"部署到 AWS"，一个是"部署到 GCP"。

  • "帮我在云上搞个测试环境" → 触发哪个？两个都触发？
  • "我需要一个新的 staging 服务器" → 触发 AWS 的还是 GCP 的？

near-miss（近邻误触）是最难处理的。用户说了一句跟你的 Skill 相关但意图不同的话，系统不应该触发。

skill-creator 怎么测触发

skill-creator 的做法是：生成 20 条测试查询，8-10 条应该触发、8-10 条不应该触发，然后跑 3 次取平均。

关键设计：should-not-trigger 的查询不是随便写的。它们是 near-miss——跟 Skill 共享关键词但实际意图不同。比如"告诉我数据库相关技能"对于一个"创建 Skill"的 Skill 来说就是 near-miss，不应该触发。

测试查询要真实、具体、有细节。官方文档明确说，"格式化数据"这种查询是坏的测试用例，"我老板刚发了一个 xlsx 文件（在 downloads 里，叫 Q4 sales final FINAL v2.xlsx），她要我加一列利润率百分比"这种才是好的测试用例。

还有一个反直觉的发现：简单查询不会触发 Skill。 Claude 只在"自己搞不定"的时候才会去查 Skill。所以"读一下这个文件"这种简单 prompt，即使 Skill description 完美匹配也不会触发——因为 Claude 不需要帮助就能完成。测试查询必须足够复杂。

Description 优化循环

skill-creator 内建了一个自动化优化循环（scripts.run_loop）：

  1. 把 20 条查询分成 60% train / 40% test
  2. 用当前 description 在 train 集上跑触发测试（每条 3 次取平均）
  3. 把失败案例喂给 Claude，让它改进 description
  4. 用新 description 在 train + test 上重测
  5. 重复最多 5 轮
  6. 选 test 分数最高的 description（不是 train，防过拟合）

这个循环的核心洞察：description 太具体会漏触发，太宽泛会误触发，需要找到甜蜜点。

官方还发现了一个关键陷阱：不要在 description 里写具体的执行步骤。 如果你写了"导出资源、生成规格、创建任务"，模型会跟着 description 走，直接跳过 SKILL.md 的正文。测试证实了这一点。

输出质量（Output Quality）

触发正确了，输出对不对？这分为两个层面：

定量检查（Deterministic Grading）

对于输出可以客观验证的 Skill（文件转换、代码生成、数据提取），用 assertion 来检查：

{
  "assertions": [
    {
      "text": "Output file exists and is valid CSV",
      "type": "assertion"
    },
    {
      "text": "CSV contains expected columns: name, email, department",
      "type": "assertion"
    },
    {
      "text": "All rows have non-empty values in required columns",
      "type": "assertion"
    }
  ]
}

能用脚本检查的就不要靠人眼看——脚本更快、更可靠、可以跨迭代复用。

定性评估（LLM Rubric Grading）

对于输出不能客观验证的 Skill（写作风格、设计方案），用 LLM 做 rubric 评分：

- type: llm_rubric
  rubric: |
    Workflow Compliance (0-0.5):
    - Did the agent follow the mandatory 3-step workflow?

    Efficiency (0-0.5):
    - Completed in ≤5 commands?
  weight: 0.3

rubric 的关键：评分标准要具体、可量化。"做得好不好"不是好的 rubric，"是否在 5 步以内完成"才是。

skill-creator 的 A/B 测试

skill-creator 不只是打分，它还有一个 blind comparator（盲评比较器）：

  1. 把 Skill 版本 A 和版本 B 的输出交给一个独立的 grader Agent
  2. grader 不知道哪个是 A 哪个是 B
  3. grader 按预设标准评判哪个更好
  4. 记录胜负比

这解决了"我觉得新版本更好但其实没有"的问题。盲评消除偏见。

Analyzer：根因分析

打完分之后，analyzer Agent 做 root cause analysis（根因分析）：

  • 哪些 assertion 无论有没有 Skill 都通过？（不区分质量的测试，没用）
  • 哪些 eval 方差特别大？（可能 flaky，不够稳定）
  • token 和时间的 tradeoff 值不值得？

这些洞察直接影响下一步的改进方向。

效率指标（Efficiency Metrics）

效率指标回答：这个 Skill 值不值？

Token 消耗

每次运行记录 total_tokens。不只是看绝对值，而是跟 baseline（没有 Skill 的运行）对比：

  • Skill 帮 Agent 省了 token（因为指导更明确，少走弯路）？✅ 好
  • Skill 反而增加了 token（因为加载了很长的 instruction）？⚠️ 要权衡
  • Skill 让 token 翻倍但输出质量显著提升？🤔 看场景

执行时间

每次运行记录 duration_ms。同样要跟 baseline 比：

  • Skill 让 Agent 更快完成？✅
  • Skill 引入了不必要的中间步骤？❌
  • Skill 的 pre-check 花了 10 秒但避免了 3 分钟的错误路径？✅ 值得

Pass Rate

所有 assertion 的通过率。skill-creator 的 benchmark 会算出 mean ± stddev：

with_skill:    pass_rate = 0.87 ± 0.08  (5 runs)
without_skill:  pass_rate = 0.43 ± 0.15  (5 runs)
delta:         +0.44 (improvement)

不是看一次通过就完事，是看多次运行的稳定性。

skillgrade 的效率预设

第三方工具 skillgrade 提供了三个预设级别：

级别 运行次数 用途
--smoke 5 次 快速验证能力
--reliable 15 次 可靠的通过率估计
--regression 30 次 高置信度的回归检测

5 次只能告诉你"大概能跑"，15 次才能给出比较可靠的通过率估计，30 次才能发现偶发的 regression。

skill-creator 的完整评估流程

把上面三个维度串起来，skill-creator 的评估是一个完整的闭环：

flowchart LR
    A["Write Draft"] --> B["Create Test Cases
2-3 realistic prompts"]
    B --> C["Spawn Runs
with_skill + baseline
in parallel"]
    C --> D["Draft Assertions
while runs execute"]
    D --> E["Grade + Aggregate
benchmark.json"]
    E --> F["Launch Viewer
qualitative + quantitative"]
    F --> G["Read Feedback
feedback.json"]
    G --> H["Improve Skill"]
    H --> C

几个关键设计决策：

并行执行：with-skill 和 baseline 同时启动，不要先跑 with-skill 再跑 baseline。时间宝贵。

边跑边写 assertion：不用等运行结束再写 assertion——运行需要时间，利用这段时间把 assertion 写好。

多次迭代：不是跑一次就完事。改进 Skill → 重跑 → 对比前后迭代 → 再改进。每次迭代的结果存在 iteration-1/、iteration-2/ 目录里，viewer 支持跨迭代对比。

数据全记：timing.json（token + 耗时）、grading.json（assertion 通过情况）、feedback.json（人类反馈）。这些数据是下一轮改进的基础。

三个第三方评估工具

除了官方 skill-creator，社区还有三个值得关注的工具：

skillgrade（496 stars）

定位："Agent Skill 的单元测试"。独立于 Claude Code 运行。

npm i -g skillgrade
cd my-skill/
skillgrade init          # 自动生成 eval.yaml
skillgrade --smoke       # 跑 5 次快速验证
skillgrade preview       # CLI 报告
skillgrade preview browser  # Web UI

支持两种 grader：

  • deterministic：跑脚本，返回 JSON score
  • llm_rubric：用 LLM 按预设标准评分

支持 Gemini、Claude、Codex 三种 Agent，支持 Docker 隔离，支持 CI 集成（--ci --threshold=0.8，低于阈值 exit 1）。

skill-conductor（94 stars）

定位：架构优先的 Skill 全生命周期工具。

最大的不同是先选架构模式再写代码。5 种模式：

模式 适用场景
Sequential workflow 清晰的步骤流程
Iterative refinement 输出需要反复迭代
Context-aware selection 同一目标不同工具
Domain intelligence 需要领域知识
Multi-MCP coordination 跨多个服务

评估体系用了 Anthropic 的三 Agent 架构（grader + comparator + analyzer），加上 5 轴评分（Discovery / Clarity / Efficiency / Robustness / Completeness，各 1-10 分）。45 分以上可以上生产，25 分以下应该重写。

cc-plugin-eval（17 stars）

定位：专注测试 Claude Code 插件的触发准确性。

4 阶段流水线：Analysis → Generation → Execution → Evaluation。

最独特的功能是语义测试（semantic testing）——不只是测试精确匹配，还测试同义词和改写：

类型 描述 例子
direct 精确触发短语 "create a skill"
paraphrased 同义改写 "add a new skill to my plugin"
edge_case 不常见但有效 "skill plz"
negative 不应该触发 "tell me about database skills"
semantic 同义词变体 "generate a skill" vs "create a skill"

它用程序化检测（parsing tool captures）达到 100% 置信度的触发判定，不依赖 LLM judge。

写好 eval 的核心原则

不管用哪个工具，写好 eval 有几个通用原则：

1. 测试用例要真实，要复杂。 "格式化这个文件"不是好的测试用例。真实的用户会带着上下文、拼写错误、模糊表述来。测试用例应该模拟这种混乱。

2. near-miss 比正例更重要。 测试 Skill 不该触发的场景，比测试该触发的场景更能发现问题。特别是跟其他 Skill 有重叠的场景。

3. assertion 要客观可验证。 "输出质量好"不是 assertion。"输出文件包含 3 个必需字段"才是。

4. 跟 baseline 比，不要只看绝对值。 Skill 可能花了 2000 token 但帮 Agent 省了 5000 token 的弯路。只看 Skill 本身的开销是误导性的。

5. 跑多次，看方差。 一次通过不代表每次通过。LLM 有随机性，5 次跑 3 次通过的 Skill 跟 5 次全通过的 Skill，质量天差地别。

6. description 是第一优先级。 一个 Skill 写得再好，如果 description 让 Agent 在该触发的时候不触发，等于没有。先优化触发，再优化内容。

作者: itech001
来源: 公众号：AI人工智能时代
网站: https://www.theaiera.cn/
每日分享最前沿的AI新闻资讯和技术研究。

本文首发于 AI人工智能时代，转载请注明出处。

觉得文章不错？分享给更多人！