skill-creator

Skill Creator

用于创建新 skill 并逐步改进它的 skill。

判断用户目前所处的阶段，并据此着手：他们可能需要帮助从头定义 skill，也可能已经有了草稿，需要直接开始评估和迭代。保持灵活——如果用户想跳过正式评估，通过对话来迭代，也完全可以。skill 完成后，主动提出进行描述优化，以提高触发准确度。

---

与用户沟通

用户的技术熟悉程度各不相同。通常可以直接使用“评估”和“基准测试”；使用“JSON”和“断言”时，则需要用户明确表示熟悉这些术语。如果不确定，请添加简短的行内说明。

---

创建 skill

梳理意图

先了解用户的意图。当前对话中可能已经包含了用户想要记录的工作流（例如，他们说“把这个变成一个 skill”）。如果是这样，请先从对话历史中提取答案——所用的工具、步骤顺序、用户做出的修正，以及观察到的输入和输出格式。用户可能需要补充缺失的信息，并应在进入下一步前进行确认。

1. 这个 skill 应帮助 Claude 做什么？
2. 在什么情况下应触发这个 skill？（哪些用户表达或上下文）
3. 预期的输出格式是什么？
4. 是否应该设置测试用例来验证 skill 是否有效？对于输出可客观验证的 skill（文件转换、数据提取、代码生成、固定工作流步骤），测试用例很有帮助。对于输出较主观的 skill（写作风格、艺术创作），通常不需要测试用例。根据 skill 的类型建议合适的默认方案，但由用户决定。

访谈与调研

主动询问边缘情况、输入和输出格式、示例文件、成功标准及依赖项。弄清这些内容后，再编写测试提示词。

检查可用的 MCP；如果有助于调研（搜索文档、查找类似的 skill、了解最佳实践），就通过子 Agent 并行调研（如果可用）；否则就在当前对话中进行。提前准备好相关背景信息，减轻用户的负担。

编写 SKILL.md

根据用户访谈，填写以下组成部分：

• name：skill 标识符（kebab-case）
• description：主要的触发机制——说明 skill 的用途，以及适用的具体情境。所有“何时使用”的信息都放在这里，而非正文中。描述应稍微“积极主动”，以应对 Claude 容易触发不足的倾向：不要写“如何构建仪表板”，而应写“如何构建仪表板。每当用户提到仪表板、数据可视化或想要展示公司数据时，都使用这个 skill，即使他们没有明确要求制作‘仪表板’。”
• license：MIT（始终如此）
• skill 的其余部分 :)

Skill 编写指南

Skill 的结构

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description, license required — nothing else)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/    - Executable code for deterministic/repetitive tasks
    ├── references/ - Docs loaded into context as needed
    └── assets/     - Files used in output (templates, icons, fonts)

渐进式披露

三个加载层级：元数据（始终处于上下文中，约 100 个词）、SKILL.md 正文（触发时加载到上下文中，最好少于 500 行）、捆绑资源（按需加载，不限量）。将 SKILL.md 控制在 500 行以内——如果接近上限，就将内容移到 references/，并添加清晰的指引。对于超过约 300 行的参考文件，请添加目录。

领域组织：当一个 skill 支持多个领域或框架时，按变体组织：

cloud-deploy/
├── SKILL.md (workflow + selection)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

Claude 只会读取相关的参考文件。

写作模式

在指令中使用祈使句。通过明确的模板块定义输出格式（例如，ALWAYS use this exact template: ...）。如果转换过程具体明确，请使用 Input:/Output: 配对示例。

写作风格

解释事情的重要性，而不是强硬地反复强调“必须”。让 skill 保持通用，避免只适用于测试示例。先写出草稿，再以全新的视角通读一遍，然后定稿。

测试用例

编写技能草稿后，构思 2-3 个真实的测试提示词——就像真实用户会说的话。与用户分享：「下面是我想尝试的几个测试用例。你觉得合适吗？还是想再添加一些？」然后运行它们。

将测试用例保存到 evals/evals.json——目前只需保存提示词，还不需要断言。完整架构（包括稍后在第 2 步添加的 assertions 字段）请参阅 references/schemas.md。

---

运行和评估测试用例

本节是一个连续的流程——不要中途停下。不要使用 /skill-test 或任何其他测试技能。

将结果放在技能目录的同级目录 <skill-name>-workspace/ 中。在工作区内，按迭代整理结果（iteration-1/、iteration-2/ 等），每次迭代中，每个测试用例各自放在一个目录中（eval-0/、eval-1/ 等）。不要一开始就创建所有目录——按需创建即可。

第 1 步：在同一轮中启动所有运行（使用技能和基线）

对于每个测试用例，在同一轮中启动两个子 Agent——一个使用技能，一个不使用技能。这一点很重要：不要先启动使用技能的运行，之后再回来启动基线运行。一次性启动所有任务，让它们大致同时完成。

使用技能运行：

Execute this task:
- Skill path: <path-to-skill>
- Task: <eval prompt>
- Input files: <eval files if any, or "none">
- Save outputs to: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
- Outputs to save: <what the user cares about — e.g., "the .docx file", "the final CSV">

基线运行（使用相同提示词，但基线取决于上下文）：

• 创建新技能：完全不使用技能。使用相同提示词，不提供技能路径，并将结果保存到 without_skill/outputs/。
• 改进现有技能：使用旧版本。编辑前，先创建技能快照（cp -r <skill-path> <workspace>/skill-snapshot/），然后让基线子 Agent 使用该快照。将结果保存到 old_skill/outputs/。

为每个测试用例编写一个 eval_metadata.json（目前可以留空断言）。为每个评估指定一个能描述测试内容的名称——不要只叫「eval-0」。目录也使用这个名称。如果本次迭代使用了新的或修改过的评估提示词，请为每个新的评估目录创建这些文件——不要假定它们会从之前的迭代沿用。

{
  "eval_id": 0,
  "eval_name": "descriptive-name-here",
  "prompt": "The user's task prompt",
  "assertions": []
}

第 2 步：运行进行期间，起草断言

不要只是等待运行完成——利用这段时间做有用的工作。为每个测试用例起草可量化的断言，并向用户说明。如果 evals/evals.json 中已有断言，请检查它们并说明其检查内容。

好的断言应当客观可验证，并有描述性名称——让使用基准查看器的人扫一眼就能明白每项检查的内容。对于主观类技能（如写作风格、设计质量），最好进行定性评估——不要强行为需要人工判断的内容设置断言。

起草完成后，使用这些断言更新 eval_metadata.json 和 evals/evals.json。

第 3 步：运行完成后，记录计时数据

每当子 Agent 任务完成时，你都会收到包含 total_tokens 和 duration_ms 的通知。立即将这些数据保存到运行目录中的 timing.json：

{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}

这是记录这些数据的唯一机会——数据会通过任务通知传来，其他地方不会保存。通知到达时就逐条处理，不要等到最后再批量处理。

步骤 4：评分、汇总并启动查看器

所有运行完成后：

1. 为每次运行评分 — 启动评分子 Agent（或直接评分），读取 agents/grader.md，并根据输出评估每项断言。将结果保存到每个运行目录中的 grading.json。grading.json 中的 expectations 数组必须使用 text、passed 和 evidence 字段（不能使用 name/met/details 或其他变体）——查看器依赖这些确切的字段名。对于可通过程序检查的断言，请编写并运行脚本，而不是凭目测判断——脚本速度更快、更可靠，还可在后续迭代中重复使用。

2. 汇总为基准测试 — 从 skill-creator 目录运行汇总脚本：

   python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>
   

   此脚本会生成 benchmark.json 和 benchmark.md，其中包含每种配置的 pass_rate、time 和 tokens，以及均值 ± 标准差和差值。如果要手动生成 benchmark.json，请参阅 references/schemas.md，了解查看器要求的确切架构。 将每个 with_skill 版本放在对应的基准版本之前。

3. 进行分析 — 阅读基准测试数据，并指出汇总统计数据可能掩盖的模式。请参阅 agents/analyzer.md 中的“分析基准测试结果”部分，了解需要关注的内容，例如无论技能如何都始终通过的断言（无法区分优劣）、方差较大的评估（可能不稳定），以及时间与令牌的权衡。

4. 启动查看器，同时提供定性输出和定量数据：

   nohup python <skill-creator-path>/eval-viewer/generate_review.py \
     <workspace>/iteration-N \
     --skill-name "my-skill" \
     --benchmark <workspace>/iteration-N/benchmark.json \
     > /dev/null 2>&1 &
   VIEWER_PID=$!
   

   对于第 2 次及之后的迭代，还需传入 --previous-workspace <workspace>/iteration-<N-1>。

   无头环境： 如果 webbrowser.open() 不可用，或者环境没有显示器，请使用 --static <output_path> 写入独立的 HTML 文件，而不是启动服务器。用户点击“Submit All Reviews”后，反馈将下载为 feedback.json 文件。下载后，将 feedback.json 复制到工作区目录，以便下一次迭代读取。

   注意：请使用 generate_review.py 创建查看器；无需编写自定义 HTML。

5. 告知用户查看器已打开，并请用户在完成审核后回来。

步骤 5：读取反馈

用户告知审核完成后，读取 feedback.json：

{
  "reviews": [
    {"run_id": "eval-0-with_skill", "feedback": "the chart is missing axis labels", "timestamp": "..."},
    {"run_id": "eval-1-with_skill", "feedback": "", "timestamp": "..."},
    {"run_id": "eval-2-with_skill", "feedback": "perfect, love this", "timestamp": "..."}
  ],
  "status": "complete"
}

反馈为空表示用户认为一切正常。改进时重点关注用户明确提出问题的测试用例。

完成后，关闭查看器服务器：

kill $VIEWER_PID 2>/dev/null

---

改进技能

如何思考改进

• 泛化，不要过拟合。 技能必须适用于许多未来的提示词，而不只是测试用例。如果某个问题顽固存在，请尝试不同的比喻或模式，而不是添加僵化的限制。
• 保持提示词精简。 阅读对话记录（而不只是输出），并删除所有会导致无效工作的内容。如果发现自己把 ALWAYS 或 NEVER 全部大写写出来，请改用推理方式表达——相比僵化规则，大模型更能理解背后的原因。
• 解释原因。 为模型提供足够的上下文，使其能够做出良好的判断。说明要求背后的推理，而不只是罗列要求。
• 打包重复工作。 如果多个测试用例的对话记录都独立生成了相同的辅助脚本，就将其放入 scripts/，并告知技能使用该脚本。

迭代循环

改进技能后：

1. 将改进应用到技能中
2. 在新的 iteration-<N+1>/ 目录中重新运行所有测试用例，包括基线运行。如果你正在创建新技能，基线始终为 without_skill（无技能）——在后续迭代中保持不变。如果你正在改进现有技能，请自行判断哪种基线更合适：用户最初提供的版本，或上一轮迭代的版本。
3. 启动评审器，并使用 --previous-workspace 指向上一轮迭代
4. 等待用户审核并告知你他们已完成
5. 阅读新反馈，再次改进并重复

持续进行，直到：

• 用户表示满意
• 所有反馈均为空（看起来一切都很好）
• 你没有取得有意义的进展

---

高级：盲测比较

如果需要更严谨地比较技能的两个版本（例如，用户询问“新版本真的更好吗？”），可以使用盲测比较系统。阅读 agents/comparator.md 和 agents/analyzer.md 了解详情。基本思路是：将两个输出交给独立 Agent，但不告知它们分别属于哪个版本，让它判断质量。然后分析胜出版本的优势所在。

这是可选步骤，需要子 Agent，大多数用户都不需要。通常人工审核循环就足够了。

---

描述优化

创建或改进技能后，主动提出优化描述，以提高触发准确率。

第 1 步：生成触发评测查询

创建 20 条评测查询，包含应触发和不应触发的混合案例。保存为 JSON：

[
  {"query": "the user prompt", "should_trigger": true},
  {"query": "another prompt", "should_trigger": false}
]

查询应贴近实际且具体——包含文件路径、公司名称、日常口语、拼写错误以及不同长度的内容。重点关注边缘案例。避免 "Format this data" 这类抽象请求。

对于应触发（8-10 条）：改变措辞（正式和口语均包含），纳入用户没有提及技能名称、但显然需要该技能的情况，以及该技能应优先于竞争技能的情况。

对于不应触发（8-10 条）：重点关注相似案例——查询包含相同关键词，但实际需要的是其他技能。避免明显无关的反例；负面案例应当确实具有迷惑性。

第 2 步：与用户审核

使用 HTML 模板向用户展示评测集：

1. 从 assets/eval_review.html 读取模板
2. 替换占位符：
   • __EVAL_DATA_PLACEHOLDER__ → 评测条目的 JSON 数组（不要加引号——这是一个 JS 变量赋值）
   • __SKILL_NAME_PLACEHOLDER__ → 技能名称
   • __SKILL_DESCRIPTION_PLACEHOLDER__ → 技能当前描述
3. 写入临时文件（例如 /tmp/eval_review_<skill-name>.html），并打开：open /tmp/eval_review_<skill-name>.html
4. 用户可以编辑查询、切换是否应触发、添加或删除条目，然后点击“Export Eval Set”
5. 文件会下载到 ~/Downloads/eval_set.json——如果有多个文件（例如 eval_set (1).json），请检查 Downloads 文件夹中最新的版本

这一步很重要——评测查询质量不佳，会导致描述优化效果不佳。

第 3 步：运行优化循环

将评测集保存到工作区，然后在后台运行（提醒用户这需要几分钟）：

python -m scripts.run_loop \
  --eval-set <path-to-trigger-eval.json> \
  --skill-path <path-to-skill> \
  --model <model-id-powering-this-session> \
  --max-iterations 5 \
  --verbose

使用系统提示中提供的模型 ID（即当前会话使用的模型），这样触发测试才能符合用户的实际体验。

运行期间，定期查看输出，让用户了解当前迭代轮次及得分情况。

该脚本会自动运行完整循环：60/40 训练/测试集划分，每条查询运行 3 次以确保可靠性，最多进行 5 轮由 Claude 提出的改进，在浏览器中生成 HTML 报告，并根据测试得分（而非训练得分）选出 best_description，以避免过拟合。

第 4 步：应用结果

从 JSON 输出中获取 best_description，并更新技能的 SKILL.md frontmatter。向用户展示修改前后的内容，并报告分数。

---

打包并呈现（仅当 present_files 工具可用时）

检查你是否可以使用 present_files 工具。如果不能，请跳过此步骤。如果可以，请打包该技能，并向用户呈现 .skill 文件：

python -m scripts.package_skill <path/to/skill-folder>

打包后，告知用户生成的 .skill 文件路径，以便他们安装。

---

Claude Code 专属说明

在 Claude Code 中，核心工作流可完整运行，包括子 Agent、评测查看器浏览器启动，以及通过 claude -p 优化描述的循环。

claude-superskills 的技能输出位置：

创建将添加到 claude-superskills 包中的技能时，请将其放在 skills/<skill-name>/ 中，切勿放在平台目录中（.github/skills/、.claude/skills/、.codex/skills/ 等目录在此仓库中都被 gitignore，必须保持为空）。完整规则请参阅 references/claude-superskills-conventions.md。

为 claude-superskills 创建技能后：

1. 将技能添加到 bundles.json 中相应的 bundle
2. 将技能添加到 README.md 的技能表，并增加技能徽章计数
3. 更新 CLAUDE.md 中的架构树和技能类型部分
4. 运行 node scripts/release.js patch，原子性地更新全部 5 个版本文件

---

Claude.ai 专属说明

Claude.ai 不支持子 Agent，因此请按以下方式调整：自行按顺序运行测试用例（不使用基线，也不并行执行）；直接在对话中呈现结果，而不启动浏览器审阅器；跳过定量基准测试、描述优化（需要 claude -p）和盲测比较。核心的起草 → 测试 → 反馈 → 改进循环仍然适用。使用 Python 时，可在任何环境中通过 package_skill.py 打包。

---

参考文件

• agents/grader.md — 根据输出评估断言
• agents/comparator.md — 对两个输出进行盲测 A/B 比较
• agents/analyzer.md — 分析某个版本胜出的原因
• references/schemas.md — evals.json、grading.json、benchmark.json 的 JSON 架构
• references/claude-superskills-conventions.md — 为 claude-superskills 贡献内容的规则

---

在自行评估输入之前，先生成评测查看器。尽快将输出呈现给用户。