Claude Code skill-creator 深度解析：从安装到落地，打造你的专属 AI 工作流

击歌吟

661人浏览 · 2026-04-15 18:03:43

击歌吟 · 2026-04-15 18:03:43 发布

在这里插入图片描述

当 AI 编程助手从"聊天工具"进化为"可扩展平台"，懂得如何封装自己的工作流，将成为开发者的核心竞争力。

读完本文，你将收获：

理解 skill-creator 的完整架构，能独立开发和调试一个 Claude Skill
掌握量化评估 Skill 触发率的工程方法，告别"凭感觉改 prompt"
获得三类真实落地场景的参考实现，可直接套用到你的工作流

一、前言：Skill 让 Claude Code 从"通用"走向"专属"

Claude Code 的火爆，不只是因为 Anthropic 的模型够强，更因为它提供了一套可编程的交互范式——Skill。

简单来说，Skill 是一种让 Claude 在特定场景下自动调用预设工作流的机制。你可以在 ~/.claude/skills/ 下放一个文件夹，里面包含 SKILL.md 和若干辅助脚本，Claude 就能在恰当的时机"记起"这套技能，并按照你的规范执行任务。

但问题也随之而来：

怎么写才能让 Claude 准确触发这套技能？
怎么验证 Skill 的效果确实比不用它更好？
怎么持续优化，而不是凭感觉改 prompt？

这就是 skill-creator 存在的意义。它是 Anthropic 官方维护的 Skill 开发套件，深藏在你本地的 ~/.claude/skills/skill-creator/ 目录中。需要明确的是：它不是一个独立的 SaaS 或桌面应用，而是一套嵌入在 Claude Code 工作流中的自动化脚本和代理指令集。run_eval.py、improve_description.py 等核心脚本都依赖 claude -p 子进程调用 Claude，因此它的使用前提是已经安装并登录了 Claude Code CLI。

本文将基于 skill-creator 的真实源码，带你从安装使用、核心架构、源码实现到落地场景，完整拆解这个项目。

适合读者： 已安装 Claude Code CLI，想进一步定制专属工作流的开发者。

二、skill-creator 是什么？

skill-creator 的 SKILL.md 开篇就点明了它的定位：

“A skill for creating new skills and iteratively improving them.”

它的核心目标非常清晰：帮助用户把重复工作流科学固化为可复用的 Claude Skill，并通过量化评估持续迭代优化。

2.1 项目结构一览

skill-creator/
├── SKILL.md                    # skill-creator 自身的技能定义
├── scripts/
│   ├── quick_validate.py       # 快速验证 SKILL.md 格式
│   ├── package_skill.py        # 打包为 .skill 分发文件
│   ├── run_eval.py             # 触发率评估（核心）
│   ├── run_loop.py             # 描述优化自动化循环
│   ├── improve_description.py  # 调用 Claude 自动改写 description
│   ├── aggregate_benchmark.py  # 聚合基准测试数据
│   ├── generate_report.py      # 生成 HTML 报告
│   └── utils.py                # 工具函数（解析 SKILL.md frontmatter）
├── agents/
│   ├── grader.md               # 评分代理指令
│   ├── comparator.md           # 盲测对比代理指令
│   └── analyzer.md             # 结果分析代理指令
├── eval-viewer/
│   ├── generate_review.py      # 启动可视化评审页面
│   └── viewer.html             # 评审页面模板
├── references/
│   └── schemas.md              # JSON Schema 规范
└── assets/
    └── eval_review.html        # 触发率评估审阅模板

这个结构本身就很值得学习：它把自己的工作流也做了高度模块化，验证、评估、优化、打包、评审，每一步都有独立的脚本和代理指令。

2.2 整体流程鸟瞰

在深入各功能前，先建立一张全局地图——skill-creator 的完整开发生命周期如下：

三、10 分钟快速上手：从零到第一个可运行的 Skill

在深入源码前，先跑通一个最小示例，建立真实的手感。

3.1 环境要求

唯一的前置条件是已经安装并配置好 Claude Code CLI。因为 skill-creator 的很多脚本（如 run_eval.py、improve_description.py）都会通过 claude -p 子进程调用 Claude。

3.2 Hello World：创建你的第一个 Skill

第一步：创建 Skill 目录结构

mkdir -p ~/.claude/skills/my-commit-helper
cd ~/.claude/skills/my-commit-helper

第二步：编写 SKILL.md

---
name: my-commit-helper
description: >
  Helps generate Conventional Commits style commit messages from git diff output.
  Use when the user asks to generate a commit message, write git commit, or
  summarize code changes for version control.
---

# Commit Message Helper

When asked to generate a commit message:

1. Run `git diff --staged` to see what's changed
2. Analyze the diff and identify the primary change type (feat/fix/docs/refactor/chore)
3. Generate a commit message following Conventional Commits spec:
   `<type>(<scope>): <short description>`
4. Offer the user 2-3 variants if the change is complex

第三步：校验格式

cd ~/.claude/skills/skill-creator
python -m scripts.quick_validate ~/.claude/skills/my-commit-helper

预期输出：

✓ SKILL.md exists
✓ Valid YAML frontmatter
✓ Required field: name = my-commit-helper
✓ Required field: description (245 chars)
✓ name is valid kebab-case
✓ No disallowed fields
All checks passed!

第四步：实测效果

在任意 git 仓库中对 Claude Code 说：

“帮我生成一个 commit message”

如果 Claude 能自动调用你的 Skill 并按规范输出，恭喜——你的第一个 Skill 已经跑通了。

3.3 打包分发

验证通过后，一键打包：

python -m scripts.package_skill ~/.claude/skills/my-commit-helper ./dist

这会生成一个 my-commit-helper.skill 文件。本质上它是一个 zip 包，你可以直接解压查看内容。打包时会自动排除：

__pycache__、node_modules
*.pyc、.DS_Store
根目录下的 evals/ 文件夹（评估数据不需要分发）

四、核心功能拆解：一个完整的 Skill 工程闭环

skill-creator 真正强大之处，在于它把 Skill 开发从"玄学 prompt 调参"变成了一套可量化、可迭代、可评审的工程流程。

4.1 SKILL.md 的渐进式披露架构

skill-creator 在 SKILL.md 中明确提出了 Progressive Disclosure（渐进式披露） 的三层架构：

关键设计原则：

Metadata 层决定触发时机，description 是核心战场——它直接影响 Claude 是否"记起"这个技能
Body 层承载主要指令，要精简有力，避免信息过载
Bundled Resources 负责重逻辑：脚本实现确定性任务，reference 文档按需加载

这种分层设计精妙地平衡了上下文窗口限制与功能丰富性之间的矛盾。一个设计良好的 Skill，Metadata 层只有几百字，但 Resource 层可以包含无限量的辅助工具。

4.2 测试评估体系：从用例定义到可视化评审

skill-creator 定义了一整套评估流水线：

4.2.1 用例定义：evals.json

在 evals/evals.json 中定义测试用例：

{
  "skill_name": "my-commit-helper",
  "evals": [
    {
      "id": 1,
      "prompt": "帮我生成一个 commit message",
      "expected_output": "符合 Conventional Commits 规范的提交信息",
      "files": ["evals/files/sample.diff"],
      "expectations": [
        "输出包含 type(scope): description 格式",
        "使用了 git diff 工具获取变更",
        "提供了多个候选版本"
      ]
    }
  ]
}

4.2.2 执行对比：with_skill vs without_skill

skill-creator 的核心评估逻辑是 A/B 对比。对于每个测试用例，它会同时启动两个子代理：

with_skill：带着你的 Skill 执行任务
without_skill：裸跑，作为 baseline

如果改进已有 Skill，则对比 new_skill vs old_skill。这种设计确保了评估的客观性——不是看输出"好不好"，而是看"用了 Skill 是不是真的更好"。

两个容易被忽略但至关重要的数据文件：

eval_metadata.json：每个测试用例目录下都会生成，包含 eval_id、eval_name、prompt 和 assertions。它是 aggregate_benchmark.py 和 generate_review.py 的输入依赖，没有它，viewer 就无法正确关联输出与用例。
timing.json：SKILL.md 中明确强调这是"唯一的机会"（only opportunity）——当子代理任务完成时，系统会立即从通知中提取 total_tokens 和 duration_ms 保存为 timing.json。没有这份数据，benchmark 中的时间/Token 对比就不完整。

4.2.3 Grader 评分哲学

agents/grader.md 定义了一个极其专业的评分代理。它不仅检查断言是否通过，还会：

提取并验证隐含声明（factual / process / quality claims）
批判 eval 本身的质量：如果某个断言即使输出错了也能通过，它会明确指出这个断言"没有区分度"
读取 metrics.json 和 timing.json，综合评估执行效率

Grader 的输出 grading.json 是后续所有数据分析的基础。

4.2.4 数据聚合与可视化

aggregate_benchmark.py 会读取所有 grading.json，计算：

每组配置的 pass_rate、time_seconds、tokens 的 mean ± stddev
delta 对比（with_skill 相对 baseline 的提升）

然后 generate_review.py 会启动一个本地 HTTP 服务（无桌面环境时可使用 --static 输出独立 HTML），在浏览器中展示：

Outputs 标签页：逐条查看每个测试用例的输出、评分、反馈文本框
Benchmark 标签页：量化指标对比、analyst notes

feedback.json 是整个闭环的血管。用户点击"Submit All Reviews"后，所有评审意见会保存到 feedback.json。下一轮迭代时，你（或 Claude）会读取这个文件，精准定位问题并优化 SKILL.md。没有这个文件，迭代就失去方向。

4.3 描述优化循环：让触发率从"玄学"变"科学"

这是 skill-creator 最让人惊艳的功能。

Claude 是否调用一个 Skill，99% 取决于 SKILL.md frontmatter 中的 description。但写一个好的 description 非常困难：太泛会误触发，太窄会漏触发。

skill-creator 用 run_eval.py + improve_description.py + run_loop.py 组成了一条自动化流水线。但自动化不等于无人参与——在启动机器优化前，还有一道关键的人工关卡：

assets/eval_review.html 的价值：系统会读取这个模板生成交互式页面，让你审阅并编辑 should-trigger / should-not-trigger 的查询集。这是防止"垃圾进、垃圾出"的关键一步——如果 edge cases 覆盖不全，优化出来的 description 也不会好。

4.3.1 run_eval.py：流式早期触发检测

run_eval.py 的核心逻辑非常巧妙。它不会等待 Claude 完整回复后再判断，而是通过 --output-format stream-json --include-partial-messages 实现 early triggering 检测：

# scripts/run_eval.py:129-154
if event.get("type") == "stream_event":
    se = event.get("event", {})
    se_type = se.get("type", "")

    if se_type == "content_block_start":
        cb = se.get("content_block", {})
        if cb.get("type") == "tool_use":
            tool_name = cb.get("name", "")
            if tool_name in ("Skill", "Read"):
                pending_tool_name = tool_name
                accumulated_json = ""
            else:
                return False

    elif se_type == "content_block_delta" and pending_tool_name:
        delta = se.get("delta", {})
        if delta.get("type") == "input_json_delta":
            accumulated_json += delta.get("partial_json", "")
            if clean_name in accumulated_json:
                return True

这里的工程巧思在于分阶段捕获：首先在 content_block_start 阶段识别到 Skill 或 Read 工具调用意向，然后在 content_block_delta 阶段逐片累积 partial_json，一旦匹配到 clean_name（即临时 command file 的标识名）就立即返回 True。这比等待完整 assistant 消息快得多，也不需要等工具执行结束。

4.3.2 improve_description.py：泛化而非记忆

当某些 query 触发失败时，improve_description.py 会把失败样例喂给 Claude，让它生成更好的 description。

但这里有一个关键约束——不要过拟合。prompt 中明确写道：

“So what I DON’T want you to do is produce an ever-expanding list of specific queries… Instead, try to generalize from the failures to broader categories of user intent.”

这意味着 skill-creator 追求的不是"记住这 20 条 query"，而是"提炼出能覆盖这类意图的通用描述"。这与机器学习中"模型要泛化，不要过拟合"的核心原则一脉相承。

4.3.3 run_loop.py：带训练/测试集分离的迭代优化

run_loop.py 把这个流程彻底自动化了，并引入了分层抽样来防止过拟合：

def split_eval_set(eval_set, holdout=0.4):
    trigger = [e for e in eval_set if e["should_trigger"]]
    no_trigger = [e for e in eval_set if not e["should_trigger"]]
    random.shuffle(trigger)
    random.shuffle(no_trigger)
    
    n_trigger_test = max(1, int(len(trigger) * holdout))
    n_no_trigger_test = max(1, int(len(no_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

它将 eval set 按 should_trigger 分层抽样，40% 作为测试集，60% 作为训练集。优化过程中模型只能看到训练集的表现，最终选出的最佳 description 则以测试集分数为准——这彻底杜绝了 overfitting。

默认最多迭代 5 轮，每轮每个 query 跑 3 次取平均触发率，还会自动生成 HTML 报告展示迭代过程。

两个防止过拟合的工程细节：

blinded_history（测试集屏蔽）：在调用 improve_description.py 之前，run_loop.py 会刻意从历史记录中剥离所有 test_ 前缀的字段（scripts/run_loop.py:195-198）。这意味着优化模型完全看不到测试集表现，只能基于训练集失败样例进行泛化。最终选出的 best_description 以测试集分数为准——这是标准的机器学习 best practice。
live_report_path（实时 HTML 报告）：循环开始时会自动生成一个带 <meta http-equiv='refresh' content='5'> 的 HTML 页面并调用 webbrowser.open() 打开。用户可以在浏览器中实时观察当前迭代进度和分数变化，不需要盯着终端。循环结束后，报告会切换为无刷新的最终版本。

4.4 盲测对比：A/B Test for Skills

对于高要求的场景，skill-creator 还提供了盲测对比机制：

agents/comparator.md：对两个版本的输出做盲评，不知道哪个是哪个
agents/analyzer.md：盲评结束后"揭盲"，分析胜者为胜的原因，给出具体改进建议

这相当于给 Skill 开发引入了一套双盲实验 + 事后分析的科学方法。

五、源码级解读：五个工程细节的背后逻辑

这五个细节看似零散，但都指向同一个主题：如何在 AI 工具链的边界条件下写出可靠的工程代码。

5.1 package_skill.py：极简打包的分层排除设计

# scripts/package_skill.py:90-101
with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
    for file_path in skill_path.rglob('*'):
        if not file_path.is_file():
            continue
        arcname = file_path.relative_to(skill_path.parent)
        if should_exclude(arcname):
            print(f"  Skipped: {arcname}")
            continue
        zipf.write(file_path, arcname)

没有任何多余的依赖，纯标准库实现。should_exclude（scripts/package_skill.py:27-39）对目录和文件做了分层处理——EXCLUDE_DIRS 是全局排除的，ROOT_EXCLUDE_DIRS 只在 Skill 根目录排除（比如 evals/）。

工程智慧：这种设计避免了"如果用户 Skill 的子目录里恰好也有一个叫 evals 的文件夹"被误排除。全局排除与根目录排除是两个完全不同的语义，混为一谈会出现难以追踪的 Bug。

5.2 aggregate_benchmark.py：小样本下的统计严谨性

计算标准差时使用了 sample standard deviation（除以 n-1），而不是 population stddev：

# scripts/aggregate_benchmark.py:45-64
def calculate_stats(values):
    n = len(values)
    mean = sum(values) / n
    if n > 1:
        variance = sum((x - mean) ** 2 for x in values) / (n - 1)
        stddev = math.sqrt(variance)
    else:
        stddev = 0.0
    return {"mean": round(mean, 4), "stddev": round(stddev, 4), ...}

工程智慧：对于小样本评估（默认每配置 3 轮 run），使用样本标准差是统计学上的正确选择——总体标准差会系统性地低估真实波动，在样本量只有 3 时误差尤其显著。这个细节体现了作者有统计学背景，而不只是会写代码。

5.3 agents/grader.md：评估系统的元认知能力

Grader 的 prompt 中有这样一段话：

“You have two jobs: grade the outputs, and critique the evals themselves. A passing grade on a weak assertion is worse than useless — it creates false confidence.”

工程智慧：这让我想到机器学习中的"评估指标必须能区分模型质量"原则。一个好的评估系统，不仅要能判断对错，还要能指出评估本身的问题。skill-creator 把这个理念直接写进了代理指令——Grader 不只是执行工具，它也是评估体系的质量守门人。

5.4 run_eval.py：对 Claude CLI 底层行为的两处深度洞察

洞察一：临时 command file 机制（scripts/run_eval.py:51-68）

# scripts/run_eval.py:51-68
project_commands_dir = Path(project_root) / ".claude" / "commands"
command_file = project_commands_dir / f"{clean_name}.md"
command_content = (
    f"---\n"
    f"description: |\n"
    f"  {indented_desc}\n"
    f"---\n\n"
    f"# {skill_name}\n\n"
    f"This skill handles: {skill_description}\n"
)
command_file.write_text(command_content)

它把 Skill 临时注册到 .claude/commands/ 目录下，这样 claude -p 就能在 available_skills 列表中看到它，模拟真实用户的触发环境。测试结束后通过 finally 块确保清理（scripts/run_eval.py:179-181），不会污染用户的 commands 目录。

洞察二：移除 CLAUDECODE 环境变量（scripts/run_eval.py:83）

# scripts/run_eval.py:83
env = {k: v for k, v in os.environ.items() if k != "CLAUDECODE"}

这个技巧允许在 Claude Code 会话内部再嵌套调用 claude -p，绕过交互式终端冲突的保护机制。没有深入研究过 Claude Code 内部机制的人，很难想到也很难写出这行代码。

这两处洞察的共同点：它们都要求作者不只是"使用 Claude Code"，而是深入理解其进程模型和文件系统约定。这是 skill-creator 能成为官方套件的底层原因——它是被真正理解这个工具的人写出来的。

5.5 run_loop.py：对抗过拟合的"信息隔离"设计

在把 eval 结果喂给 improve_description.py 之前，run_loop.py 做了一件事：

# scripts/run_loop.py:195-198
blinded_history = [
    {k: v for k, v in h.items() if not k.startswith("test_")}
    for h in history
]
new_description = improve_description(
    ...,
    history=blinded_history,
)

这行列表推导式的威力不容小觑。它把历史记录中所有以 test_ 开头的字段全部过滤掉——包括 test_passed、test_results、test_total 等。这意味着负责改写 description 的 Claude 实例完全看不到测试集表现，只能基于训练集失败样例进行泛化推理。

工程智慧：这相当于在 LLM prompt 工程中实现了一个"信息隔离墙"。如果优化器能看到测试集分数，它很可能会针对测试集里的特定 query 做记忆式调整（memorization），导致 description 在实际使用中泛化能力下降。这个简单的字段过滤，守护了整个优化流程的科学性。

六、落地场景：谁该用 skill-creator？

6.1 个人开发者：把重复工作流"技能化"

这些任务的共同点是：有明确的输入、固定的输出格式、可重复的流程。

Commit Message 规范器：自动根据 diff 生成符合 Conventional Commits 的 message
Release Note 生成器：从 git log 和 PR 描述中提取变更，生成结构化 release note
周报/月报助手：读取本周的 git 提交、文档更新、会议记录，自动生成工作汇报

一旦 Skill 化，每次只需一句话就能触发，Claude 会按你的规范执行，不会每次都"发挥创意"。

6.2 技术团队：统一标准与规范

代码审查清单：把团队的 CR 标准写入 Skill，Claude 在 review PR 时自动对照检查
文档生成规范：统一 API 文档、README、架构图的生成格式
部署流程辅助：把多步骤的部署 checklist 封装成 Skill，降低人为遗漏风险

实际效果：新成员不需要记忆团队规范，Claude 会在恰当的时机自动调用团队的 Skill，用规范的方式完成任务。

6.3 创业公司：快速沉淀 SOP

创业公司的痛点是流程变化快、文档容易过时。用 skill-creator 可以把最新 SOP 直接写成 Skill：

新员工不需要翻找 Confluence/Notion
直接对 Claude 说"帮我按公司规范生成 onboarding 文档"
Skill 本身就是活的、可执行的知识库——改 Skill 就是改 SOP

七、总结：从现在开始，你可以做这些

skill-creator 不只是一个辅助工具，它代表了一种全新的工作方式：AI-Native Workflow Engineering。

它的核心价值在于三点：把 Skill 开发从 prompt 调参变成可量化的工程流程（工程化）；通过 A/B 对比、训练/测试集分离、盲测对比确保优化方向正确（科学化）；渐进式披露、脚本复用、快速验证每个细节都在解决真实问题（务实化）。

现在就可以执行的行动清单：

[ ] 第1步：找到你工作中重复频率最高的一个任务
[ ] 第2步：确认它符合"输入固定 + 输出格式固定"的特征
[ ] 第3步：写出最简版本的 SKILL.md（参考第三节 Hello World）
[ ] 第4步：用 quick_validate.py 校验格式
[ ] 第5步：在真实工作场景中测试触发效果
[ ] 第6步：如果触发率不稳定，运行 run_loop.py 自动优化描述
[ ] 第7步：满意后打包，与团队共享

现在掌握 skill-creator，不只是学会了一个工具——你正在建立一套属于自己的、可持续进化的 AI 工作流工程能力。