Anthropic skill-creator 技术分析文档
本文档面向"完全不了解该仓库、略懂编程的小白开发者"，对 Anthropic 官方 skills 仓库中的 skill-creator 进行系统化、分层次的深度技术分析。读完本文后，你将理解 Skill 的概念、skill-creator 的全部设计，并能仿照它设计自己的 Skill。
一、Skill 全局概览
1.1 什么是 Skill？先理解基础概念
在开始分析 skill-creator 之前，我们需要先弄清一个基础问题：Skill 到底是什么？
简单来说，Skill 就是一个文件夹 ，里面装着一组"指令 + 脚本 + 资源文件"，Claude（Anthropic 公司的 AI 助手）可以在需要的时候动态加载这个文件夹，从而获得某个特定领域的"专业能力"。
打个比方：如果 Claude 是一个万能工人，那么 Skill 就像一本本"操作手册"------当需要做 PDF 处理时，Claude 打开"PDF 操作手册"；当需要做品牌设计时，Claude 打开"品牌设计手册"。每本手册都教会 Claude 如何以标准化、可重复的方式完成某类特定任务。
1.2 skills 仓库的整体定位
anthropics/skills 是 Anthropic 官方开源的 Agent Skills 仓库，截至目前已获得超过 96,000 个 Star。仓库的顶层结构如下：
| 目录/文件 | 作用 |
|---|---|
skills/ |
核心目录，包含所有 Skill 示例（共 17 个） |
spec/ |
Agent Skills 规范文档 |
template/ |
Skill 模板（新手起步模板） |
.claude-plugin/ |
Claude Code 插件配置 |
README.md |
仓库说明文档 |
仓库中的 17 个 Skill 覆盖四大类别：
| 类别 | 包含的 Skill |
|---|---|
| 创意与设计 | algorithmic-art、canvas-design、slack-gif-creator、theme-factory |
| 开发与技术 | claude-api、frontend-design、mcp-builder、web-artifacts-builder、webapp-testing |
| 企业与通信 | brand-guidelines、doc-coauthoring、internal-comms |
| 文档处理 | docx、pdf、pptx、xlsx |
| 元技能（Meta） | skill-creator（本文分析对象） |
1.3 skill-creator 的定位与作用
skill-creator 是一个"用来创建 Skill 的 Skill" ------它是整个仓库中最特殊的一个，属于元技能（Meta-Skill） 。
通俗地说：其他 Skill 教 Claude 怎么做 PDF 处理、怎么写代码、怎么做 PPT......而 skill-creator 教 Claude 怎么制造这些 Skill 本身。就像在工厂里，其他 Skill 是各种"产品"，而 skill-creator 是"制造产品的生产线"。
skill-creator 解决的核心问题：
- 从零创建新 Skill：用户只需要告诉 Claude"我想要一个做 XX 的 Skill"，skill-creator 就会引导整个创建过程
- 迭代改进现有 Skill：通过测试→评估→反馈→修改的循环，持续提升 Skill 的质量
- 量化 评测 Skill 性能：通过自动化基准测试（Benchmark），用数据衡量 Skill 的效果
- 优化 Skill 触发描述 ：自动优化 Skill 的
description字段，让 Claude 更准确地在合适的时候调用该 Skill
1.4 主要功能模块及协作关系
skill-creator 由以下核心模块组成，它们共同构成了一条完整的"Skill 生产流水线"：
scss
用户输入意图
│
▼
┌─────────────────┐
│ 意图捕获与访谈 │ ← 理解用户需求，明确 Skill 要做什么
└────────┬────────┘
│
▼
┌─────────────────┐
│ SKILL.md 撰写 │ ← 编写 Skill 核心定义文件
└────────┬────────┘
│
▼
┌─────────────────┐ ┌─────────────────┐
│ 测试用例运行 │────▶│ 评估与评分 │
│ (scripts/) │ │ (agents/ + │
│ │◀────│ eval-viewer/) │
└────────┬────────┘ └────────┬────────┘
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ 迭代改进 Skill │◀────│ 用户反馈 │
└────────┬────────┘ └─────────────────┘
│
▼
┌─────────────────────┐
│ 描述优化 & 打包发布 │ ← scripts/run_loop.py + package_skill.py
└─────────────────────┘模块间的数据流向：
- 用户意图 → 经过访谈后转化为 → SKILL.md 草稿
- SKILL.md + 测试用例 → 交给子代理运行 → 输出结果
- 输出结果 → 经过评分代理（grader）打分 → grading.json
- 多组评分结果 → 经过聚合脚本 → benchmark.json
- benchmark + 输出文件 → 经过 eval-viewer 渲染 → 可视化评审页面
- 用户反馈 feedback.json → 指导 → Skill 迭代改进
- 最终 Skill → 经过描述优化脚本 → 优化后的触发描述
- 成品 Skill → 经过打包脚本 → .skill 文件
二、目录结构与模块说明
2.1 完整目录树
以下是 skill-creator 的完整文件结构，每个文件都列出：
bash
skills/skill-creator/
│
├── SKILL.md # 🔑 核心：Skill 定义文件（元数据 + 完整指令）
├── LICENSE.txt # 许可证（Apache 2.0）
│
├── agents/ # 🤖 子代理指令集
│ ├── analyzer.md # 分析代理：分析对比结果和基准数据
│ ├── comparator.md # 比较代理：盲测对比两个输出版本
│ └── grader.md # 评分代理：按断言对输出进行评分
│
├── assets/ # 🎨 静态资源
│ └── eval_review.html # 触发评估查询的审核 HTML 模板
│
├── eval-viewer/ # 👁️ 评估结果可视化系统
│ ├── generate_review.py # 生成评审页面的 Python 脚本
│ └── viewer.html # 评审页面的 HTML 模板（~800行）
│
├── references/ # 📖 参考文档
│ └── schemas.md # 所有 JSON 数据结构的 Schema 定义
│
└── scripts/ # ⚙️ 自动化脚本工具集
├── __init__.py # Python 包初始化（空文件）
├── aggregate_benchmark.py # 聚合基准测试数据
├── generate_report.py # 生成 HTML 报告
├── improve_description.py # 通过 Claude 自动优化描述
├── package_skill.py # 打包 Skill 为 .skill 文件
├── quick_validate.py # 快速校验 Skill 格式
├── run_eval.py # 运行触发评估测试
├── run_loop.py # 编排整个优化循环
└── utils.py # 共享工具函数2.2 各目录详细说明
agents/ ------ 子代理指令集
角色： 存放专门用于特定评估任务的 AI 代理指令。这些文件不是可执行代码，而是 Markdown 格式的"指令文档"，当 Claude 需要进行评估、对比、分析时，会读取这些文件来获得专业指导。
| 文件 | 功能 | 使用时机 |
|---|---|---|
grader.md |
教 Claude 如何根据"断言"（assertion）来给输出打分 | 每次测试运行完成后 |
comparator.md |
教 Claude 如何进行"盲测"对比（不知道哪个是新版/旧版） | 需要严格对比两个版本时 |
analyzer.md |
教 Claude 如何分析对比结果、解读基准数据中的规律 | 基准测试完成后 |
与其他目录的协作： agents/ 中的指令被 SKILL.md 主流程引用，在评估阶段由 Claude 动态加载使用。评分结果输出的 JSON 格式定义在 references/schemas.md 中。
assets/ ------ 静态资源
角色： 存放在 Skill 运行过程中会使用到的模板文件、图标、字体等静态资源。
目前只有一个文件 eval_review.html，它是一个 HTML 页面模板，用于让用户审核和编辑"触发评估查询"。页面中有三个占位符：
__EVAL_DATA_PLACEHOLDER__：评估数据 JSON__SKILL_NAME_PLACEHOLDER__：Skill 名称__SKILL_DESCRIPTION_PLACEHOLDER__：Skill 描述
设计意义： 将 HTML 模板与脚本逻辑分离，是一种典型的"关注点分离"设计------模板负责展示样式，脚本负责填充数据。
eval-viewer/ ------ 评估结果可视化系统
角色： 整个评测流程中面向人类用户的可视化窗口。它将枯燥的 JSON 评测数据转化为直观的网页界面，让用户可以方便地查看输出、对比结果、留下反馈。
| 文件 | 功能 | 规模 |
|---|---|---|
generate_review.py |
核心脚本：扫描工作区、嵌入输出数据、启动 HTTP 服务器 | ~320 行 |
viewer.html |
HTML 前端模板：两个标签页（Outputs 定性查看 + Benchmark 定量统计） | ~800 行 |
关键特性：
- 支持内联渲染多种格式：文本、图片、PDF、Excel（使用 SheetJS 库）
- 支持
--static模式生成独立 HTML 文件（无需服务器） - 支持
--previous-workspace展示上一轮迭代的结果用于对比 - 反馈通过
feedback.json文件传递回给 Claude
与其他目录的协作： generate_review.py 读取 scripts/ 中聚合产生的 benchmark.json，也读取各测试运行目录中的 grading.json 和输出文件。
references/ ------ 参考文档
角色： 存放需要在 SKILL.md 主指令之外、按需加载的补充文档。这体现了 Skill 设计中"渐进式披露"（Progressive Disclosure）的原则------不把所有信息都塞进主文件，而是在需要时再加载。
目前仅有一个文件 schemas.md，它定义了 skill-creator 生态系统中所有 JSON 数据结构的 Schema：
| JSON 文件 | 用途 |
|---|---|
evals.json |
测试用例定义（prompt、预期输出、断言） |
grading.json |
评分代理的输出（各断言通过/失败 + 证据） |
timing.json |
运行计时数据（token 数、耗时） |
benchmark.json |
完整基准测试结果（汇总统计 + 每次运行详情） |
comparison.json |
盲测对比输出 |
analysis.json |
事后分析输出 |
history.json |
版本演进记录 |
metrics.json |
执行器输出指标 |
scripts/ ------ 自动化脚本工具集
角色： 整个 skill-creator 的"工程引擎"。所有需要确定性执行（deterministic execution）的自动化任务都由这里的 Python 脚本完成，而不是让 AI 自由发挥。
| 脚本 | 功能 | 核心依赖 |
|---|---|---|
run_loop.py |
主循环 编排 器：编排"评估→改进描述→重新评估"的完整循环 | run_eval.py, improve_description.py |
run_eval.py |
运行触发评估测试：检测 Skill 描述是否能被正确触发 | claude -p CLI |
improve_description.py |
调用 Claude 来自动改进 Skill 描述 | claude -p CLI |
aggregate_benchmark.py |
将多次运行的评分数据聚合为统计汇总 | grading.json 文件 |
generate_report.py |
从 run_loop 的输出生成可视化 HTML 报告 | 优化循环输出 |
package_skill.py |
将 Skill 目录打包为 .skill 文件（zip 格式） |
quick_validate.py |
quick_validate.py |
快速校验 Skill 文件格式合规性 | SKILL.md |
utils.py |
共享工具函数（解析 SKILL.md frontmatter） | --- |
脚本间的调用关系：
markdown
run_loop.py（主编排）
├── run_eval.py（每轮评估）
├── improve_description.py（每轮改进）
└── generate_report.py（最终报告）
package_skill.py
└── quick_validate.py（打包前校验）
utils.py → 被多个脚本共同引用三、关键文档（SKILL.md）详细解读
skill-creator 目录下没有传统的 README.md 文件 。所有文档内容都集中在 SKILL.md 这一个核心文件中。这本身就是一个重要的设计选择------SKILL.md 既是 Claude 的"操作指南"，也是开发者理解该 Skill 的唯一入口文档。
3.1 SKILL.md 的整体结构
SKILL.md 是一个约 500+ 行的大型 Markdown 文件，由YAML 前置 元数据 （frontmatter） 和Markdown 正文指令两部分组成。
文件结构一览：
yaml
---
name: skill-creator
description: (触发描述，约 50 字)
---
# Skill Creator ← 总体介绍
## Communicating with the user ← 沟通风格指南
## Creating a skill ← 创建 Skill 的流程
### Capture Intent ← 第一步：捕获意图
### Interview and Research ← 第二步：访谈调研
### Write the SKILL.md ← 第三步：编写 SKILL.md
### Skill Writing Guide ← Skill 编写指南
### Writing Style ← 写作风格建议
### Test Cases ← 测试用例编写
## Running and evaluating test cases ← 运行与评测流程
### Step 1-5 ← 五步评测法
## Improving the skill ← 改进 Skill 的方法论
### How to think about improvements ← 改进思维
### The iteration loop ← 迭代循环
## Advanced: Blind comparison ← 高级：盲测对比
## Description Optimization ← 描述优化
### Step 1-4 ← 四步优化法
## Claude.ai-specific instructions ← Claude.ai 平台适配
## Cowork-Specific Instructions ← Cowork 环境适配
## Reference files ← 参考文件索引3.2 YAML 前置元数据解析
yaml
---
name: skill-creator
description: Create new skills, modify and improve existing skills, and measure
skill performance. Use when users want to create a skill from scratch, edit,
or optimize an existing skill, run evals to test a skill, benchmark skill
performance with variance analysis, or optimize a skill's description for
better triggering accuracy.
---这两个字段是 Skill 系统中最重要的配置：
- name （
skill-creator）：Skill 的唯一标识符，必须是小写字母加连字符（kebab-case）的格式，最长 64 个字符。这个名称会出现在 Claude 的"可用 Skill 列表"中。 - description ：这是 Skill 的触发机制 ------Claude 根据这段描述来决定是否应该激活这个 Skill。描述中不仅要说明 Skill 做什么，还要说明什么情况下应该使用它。
3.3 核心章节逐一解读
章节一：总体介绍与哲学
SKILL.md 开篇用非常口语化的方式描述了 skill-creator 的核心工作流：
At a high level, the process of creating a skill goes like this:
- Decide what you want the skill to do and roughly how it should do it
- Write a draft of the skill
- Create a few test prompts and run claude-with-access-to-the-skill on them
- Help the user evaluate the results both qualitatively and quantitatively
- Rewrite the skill based on feedback
- Repeat until you're satisfied
- Expand the test set and try again at larger scale
小白解读： 整个过程就像"写作文"------先写草稿，然后请人看看，根据反馈修改，反复打磨直到满意。区别在于这里有自动化工具辅助评测和对比。
章节二：沟通风格指南
这是一段非常人性化的设计理念：
there's a trend now where the power of Claude is inspiring plumbers to open up their terminals, parents and grandparents to google "how to install npm"
核心要点： Skill 的使用者可能技术水平参差不齐，从水管工到资深程序员都有。因此 Claude 在使用 skill-creator 时需要注意：
- "evaluation"和"benchmark"这类词可以直接使用
- "JSON"和"assertion"这类术语，需要先确认用户是否理解，或附上简短解释
设计价值： 这教会我们在设计 Skill 时，要考虑目标用户的多样性，而不是假设所有人都是技术专家。
章节三：创建 Skill 的完整流程
文档将创建过程分为清晰的三个阶段：
阶段 1 --- 捕获意图（Capture Intent）： 通过四个关键问题理解用户需求：
- 这个 Skill 应该让 Claude 能做什么？
- 什么时候应该触发这个 Skill？
- 期望的输出格式是什么？
- 是否需要设置测试用例来验证？
阶段 2 --- 访谈与调研（Interview and Research）： 主动询问边界情况、输入输出格式、示例文件、成功标准和依赖关系。如果可用的 MCP 工具能帮助调研（搜索文档、查找类似 Skill），则并行发起调研。
阶段 3 --- 编写 SKILL.md： 文档详细规定了 SKILL.md 应包含的组件：
| 组件 | 说明 |
|---|---|
name |
Skill 标识符 |
description |
触发描述------什么时候用、做什么。文档特别强调要"稍微激进"，因为 Claude 目前倾向于"触发不足" |
compatibility |
所需工具和依赖（可选字段，很少需要） |
| 指令正文 | Skill 的核心内容 |
章节四：Skill 编写指南（重要参考）
这是 SKILL.md 中对所有 Skill 开发者最有参考价值的一节。
Skill 的标准目录结构：
scss
skill-name/
├── SKILL.md (必须)
│ ├── YAML frontmatter (name, description 必填)
│ └── Markdown 指令正文
└── Bundled Resources (可选)
├── scripts/ 可执行代码（处理确定性/重复性任务）
├── references/ 按需加载的文档
└── assets/ 输出中使用的文件（模板、图标、字体）渐进式披露（Progressive Disclosure）------ 三级加载体系：
这是 Skill 设计中最重要的架构概念之一：
| 层级 | 内容 | 何时加载 | 大小建议 |
|---|---|---|---|
| Level 1： 元数据 | name + description | 始终在上下文中 | ~100 字 |
| Level 2：SKILL.md 正文 | 完整指令 | Skill 被触发时 | <500 行 |
| Level 3：捆绑资源 | scripts/、references/、assets/ | 按需加载 | 无限制 |
为什么要这样设计？ 因为 AI 模型的"上下文窗口"（能同时看到的文本量）是有限的。Level 1 的描述始终占用上下文空间，所以要精简（~100 字）；Level 2 在触发时才加载，但也不宜过长（<500 行）；Level 3 的脚本甚至可以"不加载到上下文就直接执行"，真正做到按需使用。
安全原则（Principle of Lack of Surprise）：
skills must not contain malware, exploit code, or any content that could compromise system security
Skill 的内容不应该让用户感到意外------它做的事情应该与描述一致，不能包含恶意代码。
章节五：运行与评测流程（五步法）
这是整个 Skill 开发流程中技术含量最高的部分，SKILL.md 将其分为五个步骤：
Step 1 --- 并行启动所有测试运行： 对每个测试用例同时启动两个子代理（subagent）：
- with_skill：加载了 Skill 的 Claude 执行任务
- baseline（基线）：没有 Skill 的 Claude 执行同样的任务
两者的对比就像"对照实验"------让我们看到 Skill 到底带来了多大提升。
Step 2 --- 利用等待时间起草 断言 ： 在测试运行的同时，不要干等着，而是起草"量化断言"（assertion）。断言就是可以客观验证的检查项，例如"输出文件是否包含某个关键字段"。
Step 3 --- 捕获计时数据： 每个子代理完成时会报告 total_tokens（使用的 token 数）和 duration_ms（耗时毫秒数）。这些数据需要立即保存，因为之后就无法再获取。
Step 4 --- 评分、聚合、启动可视化：
- 启动评分代理（读取 agents/grader.md）给每个断言打分
- 运行
scripts/aggregate_benchmark.py聚合所有评分 - 进行分析师审查（读取 agents/analyzer.md）
- 启动 eval-viewer 可视化评审页面
Step 5 --- 读取用户反馈： 用户在可视化页面上留下反馈后，点击"Submit All Reviews"，反馈保存为 feedback.json。空反馈表示用户觉得没问题。
章节六：改进 Skill 的方法论
这一节是 SKILL.md 中最富哲理性的部分，展现了 Anthropic 团队对 Prompt Engineering 的深层理解：
四大改进原则：
原则 1 --- 从反馈中泛化，而非 过拟合 ：
we're trying to create skills that can be used a million times across many different prompts
不要为了修好几个测试用例而加入过于具体的限制。如果某个问题很顽固，试试换个比喻、换种表达方式，而不是堆砌"MUST"和"NEVER"。
原则 2 --- 保持精简：
Remove things that aren't pulling their weight
阅读测试的完整执行过程（transcript），如果发现 Skill 让模型浪费时间做无用功，就删掉那些多余的指令。
原则 3 --- 解释"为什么"：
Today's LLMs are smart. They have good theory of mind
这是最重要的原则：与其用 ALWAYS/NEVER 这类强制性指令，不如解释背后的原因。当 AI 理解了"为什么"时，它能更灵活、更有效地完成任务。
原则 4 --- 发现重复工作： 如果所有测试用例都独立编写了相似的辅助脚本，那就把这个脚本提取出来放到 scripts/ 目录中，避免每次都"重新发明轮子"。
章节七：描述优化
描述优化是 skill-creator 中一个独立的高级功能模块。它解决的问题是：如何让 Skill 的 description 字段更精准地触发？
优化流程分四步：
- 生成评估查询：创建 20 条测试查询（约一半应该触发、一半不应该触发），要求查询尽量真实、具体、包含各种边缘情况
- 用户审核：通过 HTML 页面（assets/eval_review.html）让用户审核和修改查询集
- 运行优化循环 ：通过
scripts/run_loop.py自动执行"评估→改进→重新评估"循环，最多 5 轮 - 应用最佳结果：取测试集上得分最高的描述（而非训练集，以避免过拟合）
关于触发机制的重要说明：
Claude only consults skills for tasks it can't easily handle on its own
Claude 只会在遇到自己不容易处理的复杂任务时才会去"查阅" Skill。简单的一步操作（如"读取这个文件"）可能不会触发任何 Skill，因为 Claude 本身就能处理。因此，评估查询需要足够复杂和具体。
章节八：平台适配指南
SKILL.md 还为两个特殊环境提供了适配说明：
Claude.ai 环境的限制：
- 没有子代理（subagent），测试用例只能串行执行
- 可能无法打开浏览器，需要在对话中直接展示结果
- 跳过定量基准测试，以定性反馈为主
- 描述优化功能需要
claudeCLI，因此不可用
Cowork 环境的适配：
- 有子代理，主流程正常运行
- 没有浏览器/显示器，需要使用
--static模式生成独立 HTML - 反馈通过文件下载方式获取
四、核心文件与配置字段解析
4.1 SKILL.md ------ Skill 的"灵魂"
| 属性 | 详情 |
|---|---|
| 位置 | skills/skill-creator/SKILL.md |
| 角色 | Skill 的唯一必需文件，包含元数据和完整指令 |
| 格式 | YAML frontmatter + Markdown 正文 |
| 大小 | 约 500+ 行 |
frontmatter 必填字段：
| 字段 | 类型 | 约束 | 作用 |
|---|---|---|---|
name |
string | kebab-case，最长 64 字符 | Skill 的唯一标识符 |
description |
string | 最长 1024 字符，不能包含尖括号 | 决定 Skill 何时被触发 |
frontmatter 可选字段：
| 字段 | 作用 |
|---|---|
license |
许可证信息 |
allowed-tools |
允许使用的工具列表 |
metadata |
附加元数据 |
compatibility |
兼容性要求（最长 500 字符） |
4.2 agents/grader.md ------ 评分代理指令
| 属性 | 详情 |
|---|---|
| 位置 | skills/skill-creator/agents/grader.md |
| 角色 | 教 Claude 如何客观评估 Skill 输出是否符合预期 |
| 使用时机 | 测试运行完成后，评分阶段 |
核心职责：
- 按照断言（assertion）逐条检查输出，给出 PASS/FAIL 及证据
- 评审断言本身的质量------是否有遗漏或不合理的检查项
- 提取并验证输出中的隐含声明（implicit claims）
- 读取用户备注，整合为结构化评分报告
输出格式： grading.json，包含 expectations（各断言结果，字段为 text/passed/evidence）、summary、execution_metrics、timing、claims、eval_feedback 等字段。
4.3 agents/comparator.md ------ 盲测对比代理指令
| 属性 | 详情 |
|---|---|
| 位置 | skills/skill-creator/agents/comparator.md |
| 角色 | 在不知道"哪个是新版/旧版"的情况下，客观比较两个输出 |
| 使用时机 | 需要严格比较两个 Skill 版本时（高级功能） |
评分维度：
- 内容维度：正确性、完整性、准确性（1-5 分）
- 结构维度：组织性、格式、可用性（1-5 分）
输出格式： comparison.json，包含 winner、reasoning、rubric_scores 等字段。
4.4 agents/analyzer.md ------ 分析代理指令
| 属性 | 详情 |
|---|---|
| 位置 | skills/skill-creator/agents/analyzer.md |
| 角色 | 深度分析为什么某个版本更好，以及基准数据中的规律 |
| 使用时机 | 盲测对比完成后 / 基准测试完成后 |
两大功能：
- 事后分析（Post-hoc Analysis） ：分析盲测结果，输出 winner 的优势、loser 的劣势、改进建议
- 基准数据分析：发现非区分性断言（不管有没有 Skill 都通过）、高方差评测（可能不稳定）、时间/token 交换比
4.5 references/schemas.md ------ 数据结构定义
| 属性 | 详情 |
|---|---|
| 位置 | skills/skill-creator/references/schemas.md |
| 角色 | 定义所有 JSON 文件的结构规范，是整个数据流的"数据字典" |
这个文件是 skill-creator 中各组件能够互相通信的基础。每个组件按照 schemas.md 定义的格式输出 JSON，下游组件再按同样的格式读取。
关键 Schema 概览：
evals.json 结构：
json
{
"skill_name": "example-skill",
"evals": [
{
"id": 1,
"prompt": "用户的任务 prompt",
"expected_output": "预期结果描述",
"files": [],
"assertions": [
{ "text": "输出应包含标题", "type": "semantic" }
]
}
]
}benchmark.json 结构（简化）：
json
{
"metadata": { "skill_name": "...", "iteration": 1 },
"runs": [
{
"eval_id": 0,
"config": "with_skill",
"pass_rate": 0.85,
"total_tokens": 84852,
"total_duration_seconds": 23.3
}
],
"run_summary": {
"with_skill": { "mean_pass_rate": 0.85, "stddev_pass_rate": 0.1 },
"without_skill": { "mean_pass_rate": 0.6 }
}
}4.6 scripts/ ------ 自动化脚本详解
run_loop.py ------ 主循环编排器（~280 行）
职责： 编排整个"描述优化"的自动化循环。
工作流程：
- 将评估查询集按 60:40 分为训练集和测试集（分层采样，保持正负样本比例）
- 对当前描述运行评估（每条查询运行 3 次取可靠触发率）
- 调用
improve_description.py让 Claude 改进描述 - 对新描述重新评估
- 最多迭代 5 轮，选取测试集得分最高的描述（而非训练集，防止过拟合）
- 生成实时 HTML 报告（带自动刷新）
run_eval.py ------ 触发评估运行器（~220 行）
职责： 测试 Skill 描述是否能正确触发。
核心机制：
- 在
.claude/commands/目录创建临时命令文件 - 运行
claude -p（Claude CLI）并使用--stream-json --include-partial-messages参数 - 通过流式事件检测 Claude 是否触发了该 Skill（早期检测）
- 支持通过
ProcessPoolExecutor并行执行多条查询
improve_description.py ------ 描述自动改进（~200 行）
职责： 调用 Claude 来生成改进后的 Skill 描述。
关键策略：
- 向 Claude 提供：当前描述、失败分析（哪些查询触发错误）、历史尝试记录
- 要求 Claude 泛化改进，而非为特定案例过拟合
- 描述字数限制在 1024 字符以内，超出时自动重试
aggregate_benchmark.py ------ 基准聚合脚本（~280 行）
职责： 将分散的评分数据汇总为统计报告。
输出：
benchmark.json：结构化的完整基准数据benchmark.md：人类可读的 Markdown 格式报告- 计算每个配置（with_skill / without_skill）的均值、标准差、最小值、最大值
- 计算两者之间的 delta（差异）
package_skill.py ------ Skill 打包器（~110 行）
职责： 将 Skill 目录打包为可分发的 .skill 文件。
工作流程：
- 调用
quick_validate.py校验 Skill 格式 - 创建 zip 格式的
.skill文件 - 排除无关文件：
__pycache__、node_modules、.pyc、.DS_Store、根级evals/
quick_validate.py ------ Skill 格式校验（~90 行）
职责： 检查 Skill 是否符合规范。
校验项：
SKILL.md是否存在且包含有效的 YAML frontmattername字段是否为 kebab-case 格式，不超过 64 字符description字段是否不超过 1024 字符且不含尖括号compatibility字段（如果有）不超过 500 字符- 只允许规定的 frontmatter 属性
utils.py ------ 共享工具函数（~50 行）
职责： 提供 parse_skill_md(skill_path) 函数，用于解析 SKILL.md 的 frontmatter 和正文内容。支持 YAML 多行指示符（>、|、>-、|-）。
4.7 eval-viewer/ ------ 可视化评审系统详解
generate_review.py（~320 行）
核心功能：
- 扫描工作区目录，发现所有含
outputs/子目录的运行结果 - 将输出文件内容（文本、图片、PDF、Excel）嵌入到 HTML 中（base64 编码）
- 启动一个基于 Python 标准库的 HTTP 服务器（无需额外依赖）
- 支持
--static模式生成独立 HTML 文件 - 支持
--benchmark参数展示量化数据 - 支持
--previous-workspace展示上轮迭代结果
viewer.html（~800 行）
界面设计：
-
Outputs 标签页：逐个展示测试用例的输出
- 配置标记（with_skill / without_skill）
- 内联渲染各种文件格式
- 可折叠的评分详情和上轮输出
- 反馈文本框（自动保存）
- 键盘导航（方向键切换用例）
-
Benchmark 标签页：展示统计汇总
- 通过率、用时、token 使用量对比
- 各评测用例的详细分解
- 断言级别的通过/失败明细
五、运行流程与内部机制
5.1 完整执行流程
下面是从用户触发 skill-creator 到最终输出的完整流程图：
vbnet
┌─────────────────────────────────────────────────────────────────────┐
│ 用户触发 Skill │
│ 例："我想创建一个帮我分析 CSV 数据的 Skill" │
└──────────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 阶段 1：意图捕获（Capture Intent） │
│ │
│ Claude 询问四个关键问题： │
│ 1. Skill 要做什么？ │
│ 2. 什么时候触发？ │
│ 3. 输出格式是什么？ │
│ 4. 需要测试用例吗？ │
│ │
│ 如果当前对话中已有工作流，直接从中提取信息 │
└──────────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 阶段 2：深度访谈与调研（Interview and Research） │
│ │
│ - 询问边界情况、示例文件、成功标准 │
│ - 检查可用的 MCP 工具 │
│ - 如有可能，通过子代理并行调研 │
└──────────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 阶段 3：编写 SKILL.md 草稿 │
│ │
│ 根据访谈结果填写： │
│ - name: skill 标识符 │
│ - description: 触发描述（稍微激进以对抗触发不足） │
│ - 指令正文：步骤、示例、注意事项 │
│ - 如需要：创建 scripts/、references/、assets/ 等辅助文件 │
└──────────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 阶段 4：编写测试用例 │
│ │
│ - 构思 2-3 个真实的用户 prompt │
│ - 与用户确认测试用例是否合适 │
│ - 保存到 evals/evals.json │
└──────────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 阶段 5：运行测试（五步评测法） │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Step 1: 并行启动所有测试运行 │ │
│ │ │ │
│ │ 测试用例 1 ──┬── with_skill 子代理 ──▶ outputs/ │ │
│ │ └── baseline 子代理 ──▶ outputs/ │ │
│ │ 测试用例 2 ──┬── with_skill 子代理 ──▶ outputs/ │ │
│ │ └── baseline 子代理 ──▶ outputs/ │ │
│ │ 测试用例 3 ──┬── with_skill 子代理 ──▶ outputs/ │ │
│ │ └── baseline 子代理 ──▶ outputs/ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │（同时进行） │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Step 2: 在等待期间起草量化断言 │ │
│ │ - 编写可客观验证的检查项 │ │
│ │ - 更新 eval_metadata.json 和 evals.json │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Step 3: 子代理完成时立即捕获 timing 数据 │ │
│ │ - total_tokens, duration_ms → timing.json │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Step 4: 评分 → 聚合 → 分析 → 启动可视化 │ │
│ │ │ │
│ │ 4a. 评分代理(grader.md) → grading.json │ │
│ │ 4b. aggregate_benchmark.py → benchmark.json │ │
│ │ 4c. 分析代理(analyzer.md) → 模式洞察 │ │
│ │ 4d. generate_review.py → 浏览器评审页面 │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Step 5: 用户在浏览器中查看结果、留下反馈 │ │
│ │ - 点击 "Submit All Reviews" → feedback.json │ │
│ └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 阶段 6：迭代改进（核心循环） │
│ │
│ ┌────────────────────────────────────┐ │
│ │ 读取 feedback.json │ │
│ │ 聚焦有具体投诉的测试用例 │ │
│ │ 遵循四大原则改进 SKILL.md │ │
│ └─────────────┬──────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────┐ │
│ │ 重新运行所有测试 → iteration-N+1/ │ │
│ │ 启动评审（--previous-workspace） │ │
│ │ 等待用户反馈 │ │
│ └─────────────┬──────────────────────┘ │
│ │ │
│ ▼ │
│ 用户满意？ ──── 否 ──▶ 回到循环顶部 │
│ │ │
│ 是 │
│ │ │
└────────────┼────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 阶段 7：描述优化（可选） │
│ │
│ 1. 生成 20 条触发评估查询（应触发 + 不应触发） │
│ 2. 用户审核（assets/eval_review.html） │
│ 3. python -m scripts.run_loop（自动化优化循环，最多 5 轮） │
│ 4. 应用最佳描述到 SKILL.md │
└──────────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 阶段 8：打包发布 │
│ │
│ python -m scripts.package_skill <path/to/skill-folder> │
│ → 输出 .skill 文件（zip 格式） │
└─────────────────────────────────────────────────────────────────────┘5.2 数据文件的生命周期
理解数据在各阶段之间如何流转，有助于理解整个系统的协作机制：
scss
evals.json (手动编写)
│
▼
[并行测试运行]
│
├──▶ outputs/（各测试用例的输出文件）
├──▶ eval_metadata.json（每个测试用例的元数据 + 断言）
└──▶ timing.json（每次运行的计时数据）
│
▼
[评分代理]
│
└──▶ grading.json（各断言通过/失败 + 证据）
│
▼
[aggregate_benchmark.py]
│
├──▶ benchmark.json（结构化统计数据）
└──▶ benchmark.md（人类可读报告）
│
▼
[generate_review.py]
│
└──▶ 浏览器评审页面
│
▼
feedback.json（用户反馈）
│
▼
[改进 SKILL.md → 新一轮迭代]5.3 工作区目录组织方式
每次迭代的工作区按以下结构组织：
perl
<skill-name>-workspace/ # 与 skill 目录同级
├── iteration-1/
│ ├── eval-descriptive-name-1/ # 每个评测用例一个目录
│ │ ├── with_skill/
│ │ │ ├── outputs/ # Skill 版本的输出文件
│ │ │ ├── grading.json # 评分结果
│ │ │ └── timing.json # 计时数据
│ │ ├── without_skill/ # 基线版本
│ │ │ ├── outputs/
│ │ │ ├── grading.json
│ │ │ └── timing.json
│ │ └── eval_metadata.json # 评测元数据 + 断言
│ ├── eval-descriptive-name-2/
│ │ └── ...
│ ├── benchmark.json # 本轮聚合统计
│ ├── benchmark.md # 人类可读报告
│ └── feedback.json # 用户反馈
├── iteration-2/
│ └── ...（同上结构）
└── skill-snapshot/ # 改进现有 Skill 时保留的原始快照六、如何仿照 skill-creator 设计自己的 Skill
6.1 一个"标准 Skill"需要哪些基本组成部分？
基于 skill-creator 的设计，一个标准 Skill 通常由以下部分组成：
| 组成部分 | 是否必需 | 在 skill-creator 中的对应 | 作用 |
|---|---|---|---|
SKILL.md |
必需 | 根目录的 SKILL.md（500+ 行） | Skill 的"灵魂"，包含元数据和所有指令 |
scripts/ |
推荐 | 8 个 Python 脚本 | 存放确定性执行的自动化代码 |
references/ |
推荐 | schemas.md | 存放按需加载的参考文档 |
assets/ |
可选 | eval_review.html 模板 | 存放模板、图标等静态资源 |
agents/ |
可选 | 3 个代理指令文件 | 存放子代理的专门指令（如果需要多代理协作） |
LICENSE.txt |
推荐 | Apache 2.0 许可证 | 明确开源许可 |
6.2 模仿 skill-creator 设计新 Skill 的步骤指南
Step 1：创建基础结构
perl
mkdir my-awesome-skill
cd my-awesome-skill创建最小可用的 SKILL.md：
yaml
---
name: my-awesome-skill
description: 在此描述你的 Skill 做什么，以及什么时候应该使用它。
记住要稍微"激进"一些------列出所有可能触发的场景，
包括用户没有明确提到 Skill 名称但显然需要它的情况。
---
# My Awesome Skill
[在这里写你的 Skill 指令]
## 使用场景
- 场景 1
- 场景 2
## 操作步骤
1. 第一步
2. 第二步
## 示例
**示例 1：**
输入：...
输出：...
## 注意事项
- 注意事项 1
- 注意事项 2Step 2：必须修改的内容
| 项目 | 修改内容 | 注意事项 |
|---|---|---|
name |
改为你的 Skill 名称 | 必须是 kebab-case，如 data-analyzer |
description |
改为你的 Skill 描述 | 最重要的字段！决定触发时机。最多 1024 字符 |
| 指令正文 | 改为你的具体操作指令 | 用祈使句，解释"为什么"而不是堆砌"必须" |
Step 3：按需扩展
如果需要自动化脚本：
bash
mkdir scripts
# 添加可执行的 Python/Shell 脚本
# 例如：数据处理脚本、文件生成脚本如果需要参考文档：
bash
mkdir references
# 添加 Markdown 格式的参考文档
# 例如：API 文档、框架指南、最佳实践
# 对于超过 300 行的文件，加上目录如果需要模板或资源文件：
bash
mkdir assets
# 添加模板文件、图标、字体等如果需要多代理协作：
bash
mkdir agents
# 添加各专门代理的指令文件
# 每个 .md 文件对应一个特定角色的代理Step 4：验证 Skill 格式
可以参考 skill-creator 中的 quick_validate.py 脚本来检查你的 Skill 是否合规：
bash
# 检查清单：
# ✅ SKILL.md 存在
# ✅ 包含有效的 YAML frontmatter（--- 开头和结尾）
# ✅ name 是 kebab-case，不超过 64 字符
# ✅ description 不超过 1024 字符，不含尖括号
# ✅ SKILL.md 正文不超过 500 行（建议）Step 5：测试和迭代
- 构思 2-3 个真实的测试场景
- 让 Claude 加载你的 Skill 并执行测试
- 查看输出，收集反馈
- 改进 SKILL.md 和相关文件
- 重复直到满意
6.3 从 skill-creator 中提炼的最佳实践
最佳实践 1：目录结构------让结构自己说话
skill-creator 用目录名直接表达用途：agents/ 放代理指令、scripts/ 放脚本、references/ 放参考文档。遵循这个规范，任何人打开你的 Skill 目录都能立刻理解每个部分在做什么。
建议目录命名规范：
bash
skill-name/
├── SKILL.md # 永远在根目录，永远叫这个名字
├── scripts/ # 可执行代码
├── references/ # 参考文档
├── assets/ # 静态资源
├── agents/ # 子代理指令（多代理场景）
└── evals/ # 测试用例（开发时用，打包时排除）最佳实践 2：渐进式披露------控制上下文负载
这是 skill-creator 中最精妙的设计理念之一。核心思想是：
- Level 1（描述） 始终可见 → 保持精简（~100 字）
- Level 2（SKILL.md 正文） 触发时加载 → 控制在 500 行以内
- Level 3（附属文件） 按需加载 → 可以很大
如果你的 SKILL.md 快要超过 500 行了，就把某些内容提取到 references/ 目录，然后在 SKILL.md 中用一句话指引 Claude 什么时候去读它。
最佳实践 3：description 字段------宁可激进，不可保守
skill-creator 的 SKILL.md 中明确指出，Claude 目前有"触发不足"（undertrigger）的倾向。因此，description 应该列出尽可能多的触发场景，包括用户可能不会直接说出 Skill 名字的间接场景。
反面例子：
"A skill for creating PDF files."
正面例子：
"A skill for creating, editing, and transforming PDF files. Use this whenever the user mentions PDF, document conversion, report generation, form filling, or needs to produce any printable document, even if they don't explicitly ask for a 'PDF'."
最佳实践 4：写作风格------解释"为什么"而不是堆砌"必须"
skill-creator 的改进原则中反复强调：
If you find yourself writing ALWAYS or NEVER in all caps, that's a yellow flag --- reframe and explain the reasoning
与其写"你必须始终使用表格格式"，不如写"使用表格格式能让对比信息一目了然，因为用户通常需要快速扫描多个选项的差异"。AI 理解了原因后，能更灵活地应用指令。
最佳实践 5：多域支持------按变体组织参考文档
当一个 Skill 需要支持多个"域"（如不同云平台、不同编程语言）时，skill-creator 推荐的模式是：
bash
cloud-deploy/
├── SKILL.md # 工作流描述 + 选择逻辑
└── references/
├── aws.md # AWS 专用指南
├── gcp.md # GCP 专用指南
└── azure.md # Azure 专用指南Claude 只加载相关的参考文件，节省上下文空间。
最佳实践 6：脚本抽取------避免重复发明轮子
如果在测试中发现 Claude 每次都独立编写类似的辅助脚本（比如都写了一个 build_chart.py），那就把它提取为 scripts/build_chart.py，让 Skill 指令中引用它。这样：
- 代码质量更可控
- 执行更快（不需要每次重写）
- 可以独立测试和维护
最佳实践 7：面向不同用户水平的沟通
skill-creator 在沟通指南中展示了一个重要原则：不要假设所有用户都是技术专家。在你的 Skill 中，也应该：
- 使用通俗易懂的语言
- 对专业术语附上简短解释
- 根据用户的表达来判断其技术水平并调整沟通方式
七、应用场景与扩展建议
7.1 典型使用场景
场景 1：从零创建新 Skill
用户输入（示例）：
"我想创建一个 Skill，帮助我每周自动生成团队周报。周报需要从 JIRA 拉取已完成任务、从 Slack 拉取关键讨论，最后生成一份 Markdown 文档。"
skill-creator 的处理过程：
- 识别出用户想创建的 Skill 类型（企业通信/报告生成）
- 深入访谈：需要哪些 JIRA 字段？Slack 的哪些频道？报告需要哪些章节？
- 编写 SKILL.md 草稿，包含 MCP 工具使用指令、报告模板、输出格式
- 创建测试用例（如模拟一周的数据），运行并评估
- 根据用户反馈迭代改进
- 打包为
.skill文件
场景 2：改进现有 Skill
用户输入（示例）：
"我有一个数据分析的 Skill，但它生成的图表总是缺少标题和图例，而且处理大数据集时特别慢。"
skill-creator 的处理过程：
- 读取现有 Skill，先做一份快照备份
- 创建针对性测试用例（包含需要标题/图例的场景、大数据集场景）
- 运行基线测试（使用旧版 Skill）和改进版测试
- 通过 eval-viewer 让用户对比两个版本
- 根据反馈继续改进
场景 3：优化 Skill 触发率
用户输入（示例）：
"我的 Skill 功能没问题，但是 Claude 经常不会在该用它的时候用它。"
skill-creator 的处理过程：
- 直接进入描述优化流程
- 生成 20 条评估查询（10 条应触发、10 条不应触发）
- 用户审核查询集
- 运行自动化优化循环（run_loop.py），最多 5 轮
- 选取测试集上得分最高的描述，更新 SKILL.md
7.2 扩展建议
对于想进一步学习的开发者：
- 研究其他 Skill 的 设计模式 ：仓库中的 17 个 Skill 各有特色，特别推荐查看
docx（文档处理）和mcp-builder（MCP 服务器生成）作为参考 - 了解 Agent Skills 规范 ：仓库的
spec/目录包含完整的规范文档 - 使用模板起步 ：仓库的
template/目录提供了最简单的 Skill 模板 - 在 Claude Code 中实践 ：通过
/plugin marketplace add anthropics/skills安装后实际使用，是理解 Skill 运作方式的最佳途径
对于想定制 skill-creator 本身的高级用户：
- 扩展评分维度 ：修改
agents/grader.md，添加特定于你领域的评分标准 - 定制可视化 ：修改
eval-viewer/viewer.html，添加你需要的数据展示方式 - 增加自动化步骤 ：在
scripts/中添加新脚本，集成到工作流中 - 支持更多平台：参考 Claude.ai 和 Cowork 的适配方式，为其他平台添加适配指令
附录：核心概念速查表
| 概念 | 通俗解释 |
|---|---|
| Skill | 一个文件夹，教 Claude 怎么做某类特定任务 |
| SKILL.md | Skill 的核心文件，包含元数据和指令 |
| Frontmatter | SKILL.md 文件头部的配置信息（用 --- 包围的 YAML） |
| 触发（Trigger） | Claude 判断是否需要使用某个 Skill 的过程 |
| 断言 （Assertion） | 可客观验证的检查项，如"输出是否包含某字段" |
| 基线 （Baseline） | 对照组------没有 Skill 时 Claude 的表现 |
| 子代理（Subagent） | Claude 启动的独立子任务，可以并行运行 |
| 基准测试（Benchmark） | 用量化指标对比 Skill 效果的评测 |
| 渐进式披露 | 不把所有信息一次性加载，按需逐步展示 |
| 过拟合 （Overfit） | 为了通过少量测试用例而加入过于具体的限制，导致通用性下降 |
| kebab-case | 小写字母用连字符连接的命名风格，如 my-skill-name |
| MCP | Model Context Protocol，模型上下文协议------Claude 调用外部工具的标准接口 |
.skill 文件 |
打包后的 Skill 分发包（本质是 zip 文件） |