05—skill-creator 源码深度拆解：LLM Skill 触发率、防过拟合与三 Agent 评审完整指南

刘棕霆
7 阅读11分钟

skill-creator 源码深度拆解：LLM Skill 触发率、防过拟合与三 Agent 评审完整指南

系列：SkillSentry · AI Skill 测评体系从零到一（五）

难度：深入（源码级）

适合读者：想理解 AI 评估工具底层原理的工程师

📌 一句话摘要：很多人写完 Skill 不知道触发率为什么低——本文从 skill-creator 源码拆解触发率测评、60/40 防过拟合和三 Agent 盲测评审的完整实现，涵盖 5 个核心设计点。

🏷️ 推荐标签：skill-creator源码 LLM Skill触发率 description优化

前言

读这篇的目的：理解 SkillSentry 四层验证体系的技术来源——我们借鉴了 skill-creator 源码的哪些设计思路、为什么这样设计。这不是 skill-creator 的使用教程。

skill-creator 是一个运行在 OpenCode（AI 编程工具）上的 Skill，用于创建和优化 AI Skill 的 description 触发效果，包含触发率测评和自动优化循环。我们的 SkillSentry 借鉴了它的核心评估思路，但两者解决不同问题：

工具解决的问题典型使用时机
skill-creatorSkill 的 description 写得好不好？能否被正确触发？写完 Skill 第一次发布前
SkillSentrySkill 触发后行为质量是否达标？每次迭代发布前

两者是互补关系：先用 skill-creator 确认「Skill 能被触发」，再用 SkillSentry 验证「触发后行为正确」。

说明：skill-creator 是内部工具，源码路径 ~/.config/opencode/skills/skill-creator/ 仅限内部环境可访问。以下分析基于源码阅读，外部读者可将其理解为「SkillSentry 设计依据的参考实现」。

这篇文章从源码层面拆解 skill-creator 的 4 个核心能力，每个函数调用都有对应的源文件行号。

能力一：触发率测评（run_eval.py）

触发率测评解决的问题是： 通过实时 SSE 流检测模型是否调用了目标 Skill，而不是等待完整输出——这让单次检测从分钟级降到秒级，是 LLM Skill 触发率评估的基础能力。

核心函数：run_single_query（run_eval.py:35-181）

def run_single_query(query, skill_name, skill_description, timeout, project_root, model):
    # 1. 创建临时 Skill 命令文件
    command_file = project_commands_dir / f"{clean_name}.md"
    command_file.write_text(f"---\ndescription: |\n  {indented_desc}\n---\n...")

    # 2. 执行 claude -p，使用 SSE 流式输出
    cmd = ["claude", "-p", query,
           "--output-format", "stream-json",
           "--verbose",
           "--include-partial-messages"]  # 关键：提前检测触发

    # 3. 实时监听流事件
    while time.time() - start_time < timeout:
        event = json.loads(line)
        if event["type"] == "stream_event":
            se_type = event["event"]["type"]

            if se_type == "content_block_start":
                tool_name = event["event"]["content_block"]["name"]
                if tool_name in ("Skill", "Read"):
                    pending_tool_name = tool_name  # 可能触发
                else:
                    return False  # 调用了其他工具，说明没用 Skill

            elif se_type == "content_block_delta" and pending_tool_name:
                accumulated_json += delta["partial_json"]
                if clean_name in accumulated_json:
                    return True  # 确认触发！立即返回

    # 4. 清理临时文件
    command_file.unlink()

关键设计点：

  1. --include-partial-messages：不等完整输出，从 SSE 流中实时检测触发。这让单次检测从分钟级降到秒级。

  2. 临时命令文件：每次测试用不同的唯一 ID（uuid4().hex[:8]），测完立即删除，不污染环境。

  3. 10 worker 并行（run_eval.py:198）：ProcessPoolExecutor(max_workers=10)，10 个 query 同时跑。

  4. 触发判断逻辑：看工具调用的 name 字段，Skill 或 Read + 包含 skill 名字 = 触发；调用了其他工具 = 未触发。

并行执行：run_eval（run_eval.py:184-256）

def run_eval(eval_set, skill_name, description, runs_per_query=1):
    with ProcessPoolExecutor(max_workers=num_workers) as executor:
        # 每个 query 跑 runs_per_query 次（默认3次）
        for item in eval_set:
            for run_idx in range(runs_per_query):
                future = executor.submit(run_single_query, ...)

    # 计算每个 query 的触发率均值
    trigger_rate = sum(triggers) / len(triggers)
    # 按 should_trigger 判断 pass/fail
    did_pass = trigger_rate >= trigger_threshold  # 默认阈值 0.5

每个 query 跑 3 次，取触发率均值（而不是单次判断），消除随机性。

能力二：自动优化 description 循环（run_loop.py）

自动优化循环解决的问题是： description 优化不知道如何迭代，以及如何防止「在已知 eval 上过拟合、换 query 就失效」——60/40 train/test 分割加上对改进模型盲化 test 成绩是这里最核心的防过拟合设计。

防过拟合设计：60/40 train/test 分割（run_loop.py:24-44）

def split_eval_set(eval_set, holdout=0.4, seed=42):
    # 按 should_trigger 分层采样，保证 train/test 比例一致
    trigger = [e for e in eval_set if e["should_trigger"]]
    no_trigger = [e for e in eval_set if not e["should_trigger"]]

    # 各取 40% 放入 test set
    n_trigger_test = max(1, int(len(trigger) * holdout))
    test_set = trigger[:n_trigger_test] + no_trigger[:n_no_trigger_test]
    train_set = trigger[n_trigger_test:] + no_trigger[n_no_trigger_test:]
    return train_set, test_set

为什么要分 train/test？防止「优化出来的 description 只在这几个 eval 上好，换了 query 就不行」。

迭代循环核心（run_loop.py:79-241）

for iteration in range(1, max_iterations + 1):
    # 1. 跑所有 query（train + test 合批，节省时间）
    all_results = run_eval(eval_set=train_set + test_set, description=current_description)

    # 2. 按 query 归属分回 train/test
    train_result_list = [r for r in all_results if r["query"] in train_queries_set]

    # 3. 如果 train 全通过，停止
    if train_summary["failed"] == 0:
        break

    # 4. 关键：对改进模型「盲化」test 成绩
    blinded_history = [{k: v for k, v in h.items() if not k.startswith("test_")} ...]

    # 5. 调用 improve_description，只看 train 结果来改进
    new_description = improve_description(
        history=blinded_history,  # test 成绩被抹掉
        eval_results=train_results
    )
    current_description = new_description

# 最终按 test 成绩选 best（不是 train）
best = max(history, key=lambda h: h["test_passed"] or 0)

最精妙的设计：blinded_history 把 test 成绩从传给改进模型的历史中抹掉。改进模型只知道「train 上失败了哪些」，不知道 test 上的表现。最后按 test 分数选 best，而不是 train。这是经典的 ML 防过拟合思路在 LLM prompt 优化中的应用。

能力三：统计聚合（aggregate_benchmark.py）

统计聚合解决的问题是： AI 测评的随机性意味着单次结果不可信，需要跑多次并用样本标准差（n-1）而不是总体标准差（n）来估计真实波动——这让汇总出的通过率统计量更保守、更接近真实水平。

统计计算（aggregate_benchmark.py:45-64）

def calculate_stats(values):
    n = len(values)
    mean = sum(values) / n

    # 使用样本标准差（n-1），不是总体标准差（n）
    variance = sum((x - mean) ** 2 for x in values) / (n - 1)
    stddev = math.sqrt(variance)

    return {"mean": round(mean, 4), "stddev": round(stddev, 4), ...}

为什么是 n-1（Bessel 修正）：

这是统计学的标准做法，称为「样本标准差」。直觉解释：我们跑 3 次测评，这 3 次是从「所有可能结果」中抽取的样本。用 n（总体标准差）会系统性低估真实波动；用 n-1 修正后，对小样本（n=3）更保守、更接近真实波动的无偏估计。

实际影响：n=3 时，样本标准差比总体标准差大约大 22%——这意味着稳定性判断会更严格，这正是我们想要的。

三次运行的统计产出：

{
  "pass_rate": {
    "mean": 0.917,     ← 三次平均通过率 91.7%
    "stddev": 0.047,   ← 标准差 4.7%，稳定（< 0.05 为稳定）
    "min": 0.875,
    "max": 0.958
  }
}

跨 config 对比（aggregate_benchmark.py:207-222）

def aggregate_results(results):
    # 计算 with_skill / without_skill 各自的统计量
    for config in ["with_skill", "without_skill"]:
        pass_rates = [r["pass_rate"] for r in results[config]]
        run_summary[config] = {"pass_rate": calculate_stats(pass_rates), ...}

    # 计算 delta
    delta_pass_rate = primary["pass_rate"]["mean"] - baseline["pass_rate"]["mean"]
    run_summary["delta"] = {"pass_rate": f"{delta_pass_rate:+.2f}", ...}

输出标准 benchmark.json，格式是 viewer 直接读取的 schema（在 references/schemas.md 中严格定义）。delta 字段用 +/- 格式标注，报告的 Benchmark 数据章节直接读取此文件渲染。

能力四：三 Agent 评审系统

三 Agent 评审系统的核心价值在于： 通过职责分离——Grader 打分、Comparator 盲测对比、Analyzer 归因——让每个 Agent 只做自己最擅长的判断，彼此不互相污染结论。

skill-creator 的评审系统由三个独立 Agent 组成。

Grader Agent（agents/grader.md）

8 步工作流，关键步骤：

Step 1: 读 transcript → 注意工具调用、返回值、报错
Step 2: 读 output 文件 → 注意结构、内容、质量
Step 3: 对每条 expectation：
    - PASS：有明确、具体、真实的证据
    - FAIL：无证据 / 证据矛盾 / 技术上满足但实质错误
Step 4: 提取隐含 claims 并验证（factual/process/quality 三类）
Step 5: 读 user_notes.md（执行者留下的疑问）
Step 6: 批评断言质量（eval_feedback）

PASS 的严格标准（agents/grader.md:87-98）：

「The evidence reflects genuine task completion, not just surface-level compliance (e.g., a file exists AND contains correct content, not just the right filename)」

文件存在 ≠ 内容正确。技术上满足但实质错误 → FAIL。

Comparator Agent（agents/comparator.md）

盲测设计（agents/comparator.md:7-9）：

「You receive two outputs labeled A and B, but you do NOT know which skill produced which. This prevents bias toward a particular skill or approach.」

评分维度（agents/comparator.md:39-57）：

内容维度（Content）：
  正确性（Correctness）  1-5 分
  完整性（Completeness） 1-5 分
  准确性（Accuracy）     1-5 分

结构维度（Structure）：
  组织性（Organization） 1-5 分
  格式规范（Formatting） 1-5 分
  可用性（Usability）    1-5 分

综合得分 = (内容均值 + 结构均值) / 2 × 2（换算 1-10 分）

Analyzer Agent（agents/analyzer.md）

两种模式：

模式一（改进建议）：比较两个版本，找出为什么赢了/输了，生成具体改进建议。

{
  "improvement_suggestions": [
    {
      "priority": "high",
      "category": "instructions",
      "suggestion": "将'process the document appropriately'替换为明确的5步流程",
      "expected_impact": "消除歧义，防止 Agent 自行发挥"
    }
  ]
}

模式二（Benchmark 分析）：跨多次运行发现规律和异常。

关注的 4 类模式（agents/analyzer.md:213-248）：

断言总是双方都通过 → 可能无判别力，不能区分 Skill 价值
断言总是双方都失败 → 可能超出模型能力范围
断言 with_skill 总通过而 without 总失败 → Skill 明确有价值
断言 with_skill 总失败而 without 总通过 → Skill 可能帮了倒忙

我们用了 skill-creator 的哪些，还有哪些没用上

skill-creator 能力SkillSentry说明
Grader/Comparator/Analyzer Agent✅ 借鉴并汉化增加了 evidence 强制非空
统计聚合（样本标准差）✅ 借鉴实现复用了样本标准差计算
触发率测评（run_eval.py）❌ 未集成最大缺口，我们只测行为不测触发
60/40 防过拟合优化循环（run_loop.py）❌ 未集成需要 claude CLI，暂未接入
实时 live report（边跑边看）❌ 未有我们是执行完才生成报告

小结

skill-creator 的核心工程智慧：

  1. 流式检测触发：--include-partial-messages + SSE 流，秒级完成触发判断
  2. 防过拟合的 60/40 分割：对改进模型盲化 test，按 test 选 best
  3. 样本标准差（n-1）：比总体标准差更准确估计真实波动
  4. 盲测消除偏见：Comparator 不知道哪个是「好版本」，纯质量评分
  5. evidence 必须引用原文：Grader 的核心约束，消除感觉判断

这些设计都有明确的工程动机，不是为了复杂而复杂。

下一篇，我们来看怎么读懂测评报告、做出发布决策。

FAQ

Q：skill-creator 和 SkillSentry 分别解决什么问题？

两者是串联关系，不是替代关系。skill-creator 解决的是「Skill 能不能被触发」——description 写得够不够准，模型遇到对应 query 时会不会调用这个 Skill。SkillSentry 解决的是「触发之后行为对不对」——Skill 的执行逻辑、工具调用、输出内容是否符合预期。正确的使用顺序是：先跑 skill-creator 确认触发率达标，再跑 SkillSentry 验证行为质量。

Q：什么是触发率，为什么比通过率更基础？

触发率指「给定一批 query，模型实际调用了目标 Skill 的比例」。它比通过率更基础，因为如果 Skill 根本没被触发，所有行为层的测评（断言通过率、增益 Δ）都是空谈——你测的是通用模型的行为，而不是 Skill 的行为。触发率是整个 Skill 测评链路的第一道门槛，低于 0.5 的 query 直接判定 description 有问题。

Q：60/40 分割是如何防止 description 过拟合的？

核心机制是「对改进模型盲化 test 成绩」。60% 的 train set 用于迭代优化 description，40% 的 test set 对改进模型完全隐藏——改进模型的输入历史（blinded_history）里，所有 test_ 开头的字段都被抹掉。最终选 best description 时，是按 test 分数而不是 train 分数排序。这样即使改进模型把 train set 记住了，它也没法针对 test set 作弊，选出来的 description 泛化能力更强。

Q：样本标准差（n-1）为什么比总体标准差更准确？

我们跑 3 次测评，这 3 次是从「所有可能运行结果」中抽取的样本，而不是全量数据。总体标准差（除以 n）假设你已经观测了所有数据，会系统性低估真实波动。样本标准差（除以 n-1，即 Bessel 修正）承认「手里只有部分数据」，给出更保守的估计。n=3 时，样本标准差比总体标准差约大 22%，稳定性判断因此更严格——这正是我们想要的，宁可误报不稳定，也不要漏报。

Q：盲测 Comparator 是怎么工作的？

Comparator Agent 收到两份输出，分别标记为 A 和 B，但它不知道哪份是「with_skill」哪份是「without_skill」。它按内容（正确性、完整性、准确性）和结构（组织性、格式、可用性）各三个维度打 1-5 分，综合换算成 1-10 分。盲化的目的是防止「知道哪个是好版本就偏向它」的评分偏见——Comparator 只做质量判断，身份揭盲发生在 Analyzer 汇总阶段。

avatar
文章
阅读
粉丝