skill-creator

Skill 创建器

一个用于创建新 skill 并迭代改进它们的 skill。

总体来说，创建 skill 的过程如下：

• 确定你希望 skill 做什么，以及它大致应如何实现
• 编写 skill 的初稿
• 设计几个测试提示词，并让可访问该 skill 的 Claude 运行它们
• 帮助用户从定性和定量两方面评估结果
  • 在运行于后台进行时，如果还没有定量评估（eval），就起草一些。如果已经存在，可以直接使用，也可以在你认为需要调整时加以修改。然后向用户解释这些评估（如果评估已存在，则解释现有的评估）
  • 使用 eval-viewer/generate_review.py 脚本向用户展示结果供其查看，同时也让其查看定量指标
• 根据用户对结果的评估反馈重写 skill（如果定量基准中暴露出明显缺陷，也一并修正）
• 重复上述步骤，直到你满意为止
• 扩充测试集，并以更大规模再次尝试

使用此 skill 时，你的任务是判断用户目前处于这一流程的哪个阶段，然后介入并帮助其推进到下一阶段。例如，用户可能会说“我想做一个用于 X 的 skill”。你可以帮助其厘清具体需求，编写初稿，编写测试用例，确定评估方式，运行所有提示词，并不断重复。

另一方面，用户也可能已经有了 skill 的初稿。在这种情况下，你可以直接进入评估和迭代环节。

当然，你应始终保持灵活。如果用户说“不用跑一堆评估，就跟我随便聊聊”，你可以照此执行。

skill 完成之后（但同样，顺序并不固定），你还可以运行 skill 描述优化器。我们为此专门准备了一个脚本，用于优化 skill 的触发效果。

明白了吗？明白了。

与用户沟通

skill 创建器的使用者对编程术语的熟悉程度差异很大。如果你没听说过（这也难怪，这股风潮才刚刚兴起），如今出现了一股潮流：Claude 的强大能力正激励着水管工打开终端，也让父母和祖父母去搜索“如何安装 npm”。另一方面，大多数用户可能都具备一定的计算机素养。

因此，请注意上下文线索，以判断如何措辞！默认情况下，大致参考如下：

• “evaluation（评估）”和“benchmark（基准）”介于两可之间，但可以使用
• 对于“JSON”和“assertion（断言）”，除非用户明显表现出了解这些概念，否则在使用前应加以解释

如果你不确定，可以简要解释术语；如果不确定用户是否理解，也可以用简短的定义加以说明。

---

创建 skill

明确意图

首先理解用户的意图。当前对话中可能已经包含用户希望固化的工作流（例如用户说“把这个做成一个 skill”）。如果是这种情况，应先从对话历史中提取答案，包括所使用的工具、步骤顺序、用户做出的更正，以及观察到的输入/输出格式。用户可能需要补充信息，并且在进入下一步之前应确认无误。

1. 这个 skill 应该让 Claude 能够做什么？
2. 这个 skill 应在什么时候触发？（用户使用哪些措辞或处于哪些情境）
3. 预期的输出格式是什么？
4. 是否需要设置测试用例来验证 skill 是否有效？具有客观可验证输出的 skill（如文件转换、数据提取、代码生成、固定的工作流步骤）适合使用测试用例。具有主观输出的 skill（如写作风格、艺术创作）通常不需要。应根据 skill 类型给出合适的默认建议，但由用户决定。

访谈与调研

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

检查可用的 MCP；如果有助于调研（搜索文档、查找类似技能、了解最佳实践），且支持子 Agent，则通过子 Agent 并行调研；否则直接调研。提前做好准备，了解相关背景，减轻用户的负担。

对于全新或有实质性变更的技能，起草前请阅读 references/quality-playbook.md。参考该文件选择一种主要技能类型，确定技能是否需要注意事项、脚本、设置状态、钩子或验证，并避免把适合放在支持文件中的细节塞进 SKILL.md。

对于 Agent 工作流、交付、自动化、PR 或高影响力技能，还应采用 skill-lifeguard 中的可靠技能契约：包含反面示例、验证检查点、可通过机器检查的完成条件、带日志到补丁循环的回放或冒烟测试钩子，以及漂移信号检测。

编写 SKILL.md

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

• name：技能标识符
• description：何时触发、技能的作用。这是主要的触发机制——同时说明技能的作用和适用的具体情境。所有“何时使用”的信息都应放在这里，而不是正文中。注意：Claude 目前容易出现技能“触发不足”的倾向，即有用时也不使用。为避免这种情况，请让技能描述更具主动性。例如，与其写“如何构建一个简单、快速的仪表板来展示 Anthropic 内部数据”，不如写“如何构建一个简单、快速的仪表板来展示 Anthropic 内部数据。只要用户提到仪表板、数据可视化、内部指标，或想展示任何类型的公司数据，即使没有明确提出要构建‘仪表板’，也务必使用此技能。”
• compatibility：可选的环境要求说明（1–500 个字符），定义见 Agent Skills 规范。Spellbook 的运行时筛选条件应放在字符串类型的 metadata.spellbook-runtimes 扩展中，使用以空格分隔的 claude_code、codex 或 portable ID：

  compatibility: Requires Codex with native subagent support.
  metadata:
    spellbook-runtimes: "codex"
  

  省略运行时元数据时，注册表会将其标记为 unspecified，且不会限制安装；这并不能证明技能具有可移植性。系统仍可读取旧版 compatibility.runtimes 映射，但新技能应使用标准字符串加元数据的形式。
• 技能的其余部分 :)
• 高价值工作流技能的可靠技能契约：禁止的行为、检查点、完成条件、冒烟测试钩子和漂移信号。

技能编写指南

技能结构

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description required)
│   └── 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)

渐进式披露

技能采用三级加载系统：

1. 元数据（名称 + 描述）——始终处于上下文中（约 100 个词）
2. SKILL.md 正文——技能触发时载入上下文（理想情况下少于 500 行）
3. 打包资源——按需加载（数量不限；脚本无需载入即可执行）

这些字数只是估算值，如有需要，可以写得更长。

关键模式：

• 保持 SKILL.md 少于 500 行；如果接近此上限，请增加一层清晰的层级结构，并明确指引模型接下来应前往何处继续操作。
• 在 SKILL.md 中清楚地引用文件，并说明何时阅读这些文件。
• 对于较长的参考文件（超过 300 行），请加入目录。

领域组织：当技能支持多个领域/框架时，按变体组织：

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

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

无意外原则

这点不言自明，但技能不得包含恶意软件、漏洞利用代码，或任何可能危及系统安全的内容。描述技能内容时，不应让用户对其意图感到意外。不要接受创建误导性技能，或旨在协助未经授权访问、数据外泄或其他恶意活动的请求。不过，像“扮演某个角色”这样的内容是可以的。

写作模式

指令中优先使用祈使句。

定义输出格式——可以这样写：

## Report structure
ALWAYS use this exact template:
# [Title]
## Executive summary
## Key findings
## Recommendations

示例模式——加入示例很有帮助。可以按这种方式排版（但如果示例中使用了“输入”和“输出”，你可能需要稍作调整）：

## Commit message format
**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication

写作风格

尽量向模型解释事情为何重要，而不是一味使用强硬的“必须”。运用心智理论，让技能具有普适性，而不是局限于特定示例。先写出草稿，再以全新的视角审阅并完善。

测试用例

写完技能草稿后，构思 2–3 个真实的测试提示词，也就是实际用户可能会说的话。与用户分享：“这里有几个我想尝试的测试用例。你觉得合适吗？还是想再补充几个？”（不必逐字使用这句话。）然后运行这些测试。

将测试用例保存到 evals/evals.json。暂时不要编写断言——只保存提示词。待运行过程中再起草断言。

{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "User's task prompt",
      "expected_output": "Description of expected result",
      "files": []
    }
  ]
}

完整架构（包括稍后添加的 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 版本放在其对应的 baseline 版本之前。

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

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>。

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

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

5. 告知用户，例如：“我已在浏览器中打开结果。查看器有两个选项卡——‘Outputs’可让你逐个浏览测试用例并留下反馈，‘Benchmark’会显示定量对比。完成后，请回到这里告诉我。”

用户在查看器中看到的内容

“Outputs”选项卡一次显示一个测试用例：

• Prompt：给出的任务
• Output：技能生成的文件，并尽可能以内嵌方式呈现
• Previous Output（第 2 轮及之后）：折叠区域，显示上一轮的输出
• Formal Grades（如果运行了评分）：折叠区域，显示断言是否通过
• Feedback：可在输入时自动保存的文本框
• Previous Feedback（第 2 轮及之后）：显示在文本框下方的用户上次评论

“Benchmark”选项卡显示统计摘要：各配置的通过率、耗时和令牌用量，以及各评估项的明细和分析人员的观察结果。

可通过“上一个／下一个”按钮或方向键进行导航。完成后，点击“Submit All Reviews”，将所有反馈保存到 feedback.json。

步骤 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

---

改进技能

这是整个循环的核心。你已经运行了测试用例，用户也审阅了结果，现在需要根据他们的反馈改进技能。

如何思考改进

1. 从反馈中归纳通用规律。 这里的大局是，我们要创建的 Skill 会被使用上百万次（也许真的会，甚至更多，谁知道呢），覆盖许多不同的提示词。你和用户之所以反复迭代少数几个示例，是为了加快进度。用户对这些示例了如指掌，评估新输出也很快。但如果你们共同开发的 Skill 只对这些示例有效，那它就毫无用处。与其做琐碎的过拟合式修改，或是令人压抑的强制性 MUST 规定，不如在遇到顽固问题时，尝试换一种比喻，或推荐不同的工作模式。尝试的成本不高，说不定就能找到很好的方案。

2. 保持提示词精简。 删除那些没有发挥作用的内容。务必阅读转录记录，而不只是看最终输出。如果发现 Skill 让模型浪费大量时间做无效的事情，可以删除导致这些行为的部分，看看结果如何。

3. 解释原因（why）。 请努力解释你让模型做每件事背后的原因。如今的大模型很聪明，具备良好的心智理论，在合适的运行框架下，能够超越机械式的指令，真正把事情做成。即使用户的反馈简短或带有挫败感，也要尝试真正理解任务，理解用户为什么这样写、究竟写了什么，然后把这种理解传达到指令中。如果你发现自己在写全大写的 ALWAYS 或 NEVER，或者使用非常僵化的结构，这就是一个黄色警示信号。如果可能，请换一种方式表述，并解释其中的理由，让模型明白你所要求的事情为什么重要。这是一种更人性化、更有力、更有效的做法。

4. 寻找测试用例之间的重复工作。 阅读测试运行的转录记录，留意子 Agent 是否各自独立编写了相似的辅助脚本，或采用了同样的多步骤方法来完成某件事。如果三个测试用例中，子 Agent 都编写了 create_docx.py 或 build_chart.py，这就强烈表明 Skill 应当打包该脚本。将其编写一次，放入 scripts/ 目录，并告诉 Skill 使用它。这样以后每次调用都不必重复造轮子。

这项任务非常重要（我们要创造每年数十亿的经济价值！），你的思考时间不是瓶颈。请慢慢来，认真斟酌。我建议先写一份修订草稿，然后重新审视并加以改进。请尽力走进用户的内心，真正理解他们想要什么、需要什么。

迭代循环

完成 Skill 改进后：

1. 将改进应用到 Skill 中
2. 将所有测试用例重新运行到新的 iteration-<N+1>/ 目录中，包括基线运行。如果是创建新 Skill，基线始终为 without_skill（不使用 Skill），该基线在各次迭代中保持不变。如果是改进现有 Skill，则由你判断合适的基线：可以是用户最初提供的原始版本，也可以是上一次迭代的版本。
3. 使用 --previous-workspace 指向上一次迭代目录，启动审阅器
4. 等待用户审阅，并告诉你他们已完成
5. 阅读新的反馈，再次改进，然后重复上述步骤

持续进行，直到：

• 用户表示满意
• 反馈全部为空（一切看起来都很好）
• 你已无法取得实质性进展

---

高级：盲测比较

如果你想更严格地比较某项技能的两个版本（例如，用户问“新版本真的更好吗？”），可以使用盲测比较系统。详情请阅读 agents/comparator.md 和 agents/analyzer.md。基本思路是：将两个输出交给一个独立的 Agent，但不告知它哪个输出对应哪个版本，让它判断质量。然后分析胜出者胜出的原因。

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

---

描述优化

SKILL.md frontmatter 中的 description 字段是决定 Claude 是否调用某项技能的主要机制。创建或改进技能后，请主动提出优化 description，以提高触发准确率。

步骤 1：生成触发评估查询

创建 20 条评估查询，包含应该触发和不应该触发的查询。将其保存为 JSON：

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

查询必须真实可信，且应当是 Claude Code 或 Claude.ai 用户实际会输入的内容。不要写抽象请求，而要写具体、明确且包含足够细节的请求。例如，文件路径、用户工作的个人背景或具体情况、列名和值、公司名称、URL。可以加入一些背景信息。有些查询可以使用小写字母、缩写、拼写错误或口语表达。查询长度应有长有短，并重点关注边界情况，而不是写得一目了然（用户之后可以审核并确认）。

不佳："Format this data"、"Extract text from PDF"、"Create a chart"

良好："ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage. The revenue is in column C and costs are in column D i think"

对于应该触发的查询（8-10 条），请考虑覆盖范围。针对同一意图，使用不同的表达方式——有些正式，有些口语化。加入用户没有明确提及技能名称或文件类型、但显然需要该技能的情况。加入一些少见的用例，以及该技能与其他技能存在竞争但应当胜出的情况。

对于不应该触发的查询（8-10 条），最有价值的是那些差一点就会触发的查询——它们与该技能共享关键词或概念，但实际需要的是其他内容。请考虑相邻领域、容易产生歧义且简单的关键词匹配可能会误触发的表达，以及查询涉及该技能能做的事、但在此情境下使用其他工具更合适的情况。

关键是避免让不应该触发的查询显得毫不相关。用 "Write a fibonacci function" 作为 PDF 技能的负向测试太简单了——根本测不出任何东西。负向案例应当真正具有迷惑性。

步骤 2：与用户审核

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

1. 从 assets/eval_review.html 读取模板
2. 替换占位符：
   • __EVAL_DATA_PLACEHOLDER__ → 评估条目组成的 JSON 数组（不加引号——它是一个 JS 变量赋值）
   • __SKILL_NAME_PLACEHOLDER__ → 技能名称
   • __SKILL_DESCRIPTION_PLACEHOLDER__ → 技能当前的 description
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 文件夹，找到最新版本

这一步很重要——评估查询质量不佳会导致 description 质量不佳。

第 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 次，以获得可靠的触发率），然后调用 Claude，通过扩展思考，根据失败情况提出改进方案。它会在训练集和测试集上重新评估每个新描述，最多迭代 5 次。完成后，它会在浏览器中打开 HTML 报告，展示每轮迭代的结果，并返回包含 best_description 的 JSON——此描述根据测试分数而非训练分数选出，以避免过拟合。

技能触发机制

了解触发机制有助于设计更好的评估查询。技能会以名称和描述的形式出现在 Claude 的 available_skills 列表中，Claude 会根据描述决定是否查阅某项技能。需要注意的是，Claude 只会在无法轻松自行处理任务时才查阅技能——像“读取这个 PDF”这样简单的单步查询，即使描述完全匹配，也可能不会触发技能，因为 Claude 可以用基本工具直接处理。描述匹配时，复杂、多步骤或专业化的查询则能可靠地触发技能。

这意味着评估查询应当足够实质，让 Claude 确实能从查阅技能中受益。像“读取文件 X”这样的简单查询不是好的测试用例——无论描述质量如何，它们都不会触发技能。

第 4 步：应用结果

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

---

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

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

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

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

---

Claude.ai 专属说明

在 Claude.ai 中，核心工作流相同（起草 → 测试 → 审阅 → 改进 → 重复），但由于 Claude.ai 没有子 Agent，某些机制会有所变化。以下是需要调整的内容：

运行测试用例：没有子 Agent 就无法并行执行。对于每个测试用例，先阅读技能的 SKILL.md，然后按照其中的说明，亲自完成测试提示词。一次只做一个。与由独立子 Agent 执行相比，这种方式不够严谨（你编写了技能，也在运行技能，因此掌握了完整上下文），但可以进行有用的合理性检查，而且人工审阅步骤可以弥补这一点。跳过基线运行——直接使用技能按要求完成任务即可。

审阅结果：如果你无法打开浏览器（例如，Claude.ai 的 VM 没有显示器，或者你使用的是远程服务），则完全跳过浏览器审阅器。改为直接在对话中展示结果。对于每个测试用例，都展示提示词和输出。如果输出是用户需要查看的文件（例如 .docx 或 .xlsx），请将其保存到文件系统，并告知用户文件位置，以便他们下载和检查。直接在对话中征求反馈：“效果如何？有什么想改的吗？”

基准测试：跳过量化基准测试——它依赖基线比较，在没有子 Agent 的情况下没有意义。重点关注用户的定性反馈。

迭代循环：和之前一样——改进技能、重新运行测试用例、征求反馈——只是中间不使用浏览器审阅器。如果有文件系统，你仍然可以将结果整理到迭代目录中。

描述优化：本节需要 claude CLI 工具（具体来说是 claude -p），该工具仅在 Claude Code 中可用。如果你使用的是 Claude.ai，请跳过此步骤。

盲测比较：需要子 Agent。请跳过此步骤。

打包：package_skill.py 脚本只需要 Python 和文件系统，在哪里都能运行。在 Claude.ai 中，你可以运行该脚本，然后让用户下载生成的 .skill 文件。

---

Cowork 专属说明

如果你使用的是 Cowork，主要需要了解以下几点：

• 你可以使用子 Agent，因此主工作流（并行启动测试用例、运行基线、评分等）都可以正常进行。（不过，如果遇到严重的超时问题，可以按顺序而非并行运行测试提示词。）
• 你没有浏览器或显示器，因此生成评测查看器时，请使用 --static <output_path> 写入独立的 HTML 文件，而不是启动服务。然后提供一个链接，供用户点击后在浏览器中打开 HTML 文件。
• 不知为何，Cowork 环境似乎不太倾向于让 Claude 在运行测试后生成评测查看器，所以再次强调：无论你使用 Cowork 还是 Claude Code，运行测试后，都应该先使用 generate_review.py 生成评测查看器，让用户查看示例，然后再自行修改技能并尝试修正问题（不要自己编写定制的 HTML 代码）。提前致歉，但我要大写强调：请务必在自行评估输入之前生成评测查看器。要尽快把结果交给用户查看！
• 反馈流程有所不同：由于没有正在运行的服务，查看器的“提交所有评审”按钮会将 feedback.json 下载为文件。之后你可以从该文件中读取反馈（可能需要先请求访问权限）。
• 打包功能可用——package_skill.py 只需要 Python 和文件系统。
• 描述优化（run_loop.py / run_eval.py）在 Cowork 中应该也能正常运行，因为它通过子进程调用 claude -p，不需要浏览器。但请留到技能完全完成且用户认可其状态良好之后再进行。

参考文件

agents/ 目录包含专用子 Agent 的说明。需要启动相关子 Agent 时，请阅读这些说明。

• agents/grader.md — 如何根据输出评估断言
• agents/comparator.md — 如何对两个输出进行盲测 A/B 比较
• agents/analyzer.md — 如何分析一个版本胜出的原因

references/ 目录包含其他文档：

• references/schemas.md — evals.json、grading.json 等文件的 JSON 结构
• references/quality-playbook.md — 技能类型选择、触发条件描述规则、注意事项、渐进式披露和验证检查

---

为了强调，再重申一遍核心流程：

• 弄清技能的用途
• 起草或编辑技能
• 在测试提示词上运行 claude-with-access-to-the-skill
• 与用户一起评估输出：
  • 创建 benchmark.json 并运行 eval-viewer/generate_review.py，帮助用户审阅
  • 运行定量评估
• 重复以上步骤，直到你和用户都满意
• 打包最终技能并交付给用户。

如果你有 TodoList，请添加步骤，确保不会忘记。如果你在 Cowork 中，请务必在 TodoList 中添加“创建 evals JSON 并运行 eval-viewer/generate_review.py，以便人工审阅测试用例”。

祝你顺利！