skill-creator

anthropics/skills skills/skill-creator 的分支版本，修复了 Windows 相关问题（管道读取器、UTF-8 文件 I/O、--project-root、真实技能触发检测）和评估有效性问题（同名已安装技能导致结果受污染、测试框架错误被掩盖为 0% 分数）。上游提交、补丁和审计结果见 CtrlCarlitos/skills 中的 vendor/skill-creator/。可直接替换：名称和描述均相同。 上游问题：anthropics/skills#1827。

Skill Creator

用于创建新技能并持续改进它们的技能。

总体来说，创建技能的流程如下：

• 确定你希望技能实现什么功能，以及大致的实现方式
• 编写技能草稿
• 创建几个测试提示词，并使用可访问该技能的 claude 运行它们
• 帮助用户从定性和定量两个方面评估结果
  • 运行在后台进行时，如果尚无定量评估，就起草一些；如果已有，则可以直接使用，也可以根据需要修改。然后向用户说明这些评估（如果已有评估，则说明现有评估）
  • 使用 eval-viewer/generate_review.py 脚本展示结果供用户查看，同时让用户查看定量指标
• 根据用户对结果的评估反馈重写技能（也要考虑定量基准中显现出的明显缺陷）
• 重复以上流程，直到满意为止
• 扩充测试集，并尝试更大规模的测试

使用此技能时，你的任务是判断用户处于流程的哪个阶段，然后介入并帮助他们推进。例如，用户可能会说：“我想为 X 创建一个技能。”你可以帮助他们明确具体需求、编写草稿和测试用例、确定评估方式、运行所有提示词，并反复迭代。

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

当然，你应该始终保持灵活。如果用户说“我不需要跑一堆评估，随便聊聊就行”，那就按他们的意思来。

技能完成后（不过，顺序可以灵活调整），你还可以运行技能描述优化器来优化技能的触发方式。我们有一个专门的脚本可以完成这件事。

明白？好。

与用户沟通

技能创建器可能会被各种编程术语熟悉程度的人使用。如果你还没听说过（这项趋势确实才刚刚兴起），Claude 的强大能力正促使水管工打开终端，也让父母和祖父母开始搜索“如何安装 npm”。另一方面，大多数用户可能都具备一定的计算机知识。

因此，请留意上下文线索，判断应该如何措辞！通常可以参考以下原则：

• “评估”和“基准测试”有些专业，但可以使用
• 对于“JSON”和“断言”，除非用户有明显迹象表明他们了解这些概念，否则应先解释再使用

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

---

创建技能

捕获意图

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

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

访谈与研究

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

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

编写 SKILL.md

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

• name：技能标识符
• description：何时触发、技能的作用。这是主要的触发机制——既要说明技能的作用，也要具体说明适用情境。所有“何时使用”的信息都应放在这里，而不是正文中。注意：Claude 目前倾向于“触发不足”，也就是在技能有用时不使用它。为应对这一点，请让技能描述更具“推动性”。例如，不要只写“如何构建一个简单快速的仪表盘来展示 Anthropic 的内部数据”，而应写“如何构建一个简单快速的仪表盘来展示 Anthropic 的内部数据。只要用户提到仪表盘、数据可视化、内部指标，或想展示任何类型的公司数据，就务必使用此技能，即使他们没有明确要求制作‘仪表盘’。”
• compatibility：所需工具、依赖项（可选，很少需要）
• 其余技能内容 :)

技能编写指南

技能结构

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. 元数据（name + description）——始终处于上下文中（约 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、时间和 token 数，以及均值 ± 标准差和差值。如果手动生成 benchmark.json，请参阅 references/schemas.md，了解查看器所需的确切架构。 请将每个 with_skill 版本放在对应基线版本之前。

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 复制到工作区目录，以便下一次迭代读取。

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

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

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

“Outputs”标签页一次显示一个测试用例：

• Prompt：给出的任务
• Output：技能生成的文件，可能时以内嵌方式呈现
• Previous Output（第 2 次迭代及之后）：可折叠区域，显示上一次迭代的输出
• Formal Grades（如果运行了评分）：可折叠区域，显示各项断言的通过/失败情况
• Feedback：文本框，输入时会自动保存
• Previous Feedback（第 2 次迭代及之后）：显示在文本框下方的上次反馈

“Benchmark”标签页显示统计摘要：每种配置的通过率、计时数据和 token 用量，并提供各项评估的明细及分析观察。

可通过上一个/下一个按钮或方向键进行导航。完成后，点击“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. 从反馈中归纳规律。 这里的大方向是，我们要创建能够使用百万次的技能（也许真的会用这么多次，甚至更多，谁知道呢），以应对许多不同的提示词。你和用户在这里反复迭代的只有少数几个示例，因为这样推进得更快。用户对这些示例了如指掌，因此可以快速评估新输出。但如果你和用户共同开发的技能只能处理这些示例，那它就毫无用处。与其添加繁琐、过度拟合的修改，或设置严苛限制的 MUST，不如在问题顽固时尝试换用不同的比喻，或推荐不同的工作模式。尝试成本相对较低，说不定就能找到很好的方案。

2. 保持提示词精简。 删除那些没有发挥作用的内容。务必阅读完整对话记录，而不只是最终输出——如果技能似乎让模型浪费大量时间做无用功，可以尝试删掉导致这种情况的部分，看看效果如何。

3. 解释原因。 尽量解释清楚要求模型这样做的原因。如今的大模型很聪明，具备良好的心智理论能力；如果提供了合适的引导机制，它们就能超越机械执行指令，真正有效地完成任务。即使用户的反馈简短或带有挫败感，也要努力理解这项任务、用户为什么这样写、他们实际写了什么，然后把这些理解传达给指令。如果发现自己把 ALWAYS 或 NEVER 全大写，或者使用非常僵化的结构，那就是一个警示信号——如果可能，应换种说法解释原因，让模型理解你提出该要求的重要性。这样做更有人情味，也更有力、更有效。

4. 留意测试用例间重复的工作。 阅读测试运行的对话记录，观察各个子 Agent 是否都独立编写了类似的辅助脚本，或采用了相同的多步骤方法。如果 3 个测试用例都让子 Agent 编写了 create_docx.py 或 build_chart.py，这就是一个强烈信号：技能应该包含该脚本。只需编写一次，将它放进 scripts/，并告诉技能使用它。这样每次后续调用都不必从头重复造轮子。

这项任务非常重要（我们正努力每年创造数十亿美元的经济价值！），而思考时间并不是瓶颈；请从容思考，认真权衡。我建议先起草修订稿，再重新审视并继续改进。请尽力设身处地理解用户的想法，弄清他们想要什么、需要什么。

迭代循环

改进技能后：

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

持续进行，直到：

• 用户表示满意
• 反馈全部为空（各项都没有问题）
• 你已无法取得有意义的进展

进阶：盲比较

当你需要对同一 Skill 的两个版本进行更严格的比较时（例如用户问"新版本是否真的更好？"），可以使用盲比较系统。详细内容请阅读 agents/comparator.md 和 agents/analyzer.md。其基本思路是：在不告知来源的情况下，把两份输出交给一个独立的 Agent，由它判断质量，然后分析胜出方胜出的原因。

这一功能是可选的，需要子 Agent 支持，大多数用户并不需要。通常人工审阅循环已经足够。

---

描述优化

SKILL.md frontmatter 中的 description 字段是决定 Claude 是否调用该 Skill 的主要机制。在创建或改进 Skill 之后，应主动提出优化 description，以提高触发的准确性。

第一步：生成触发评估查询

创建 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 条），应考虑覆盖面：同一意图的不同表述，有正式的也有随意的。应包括用户没有明确提及 Skill 或文件类型、但确实需要该 Skill 的情况；也应包括一些不常见的使用场景，以及本 Skill 与其他工具存在竞争、但本 Skill 应当胜出的情况。

对于不应触发的查询（8-10 条），最有价值的是"近似误判"查询，即与 Skill 共享关键词或概念，但实际需要其他工具的查询。可以考虑相邻领域、措辞模糊（朴素的关键词匹配会误触发但实际不应触发）的情况，以及查询涉及 Skill 所做的事情、但在某种场景下其他工具更合适的情况。

需要避免的关键问题是：不要让不应触发的查询显而易见地无关。例如，把"写一个斐波那契函数"作为 PDF Skill 的反例，过于简单，无法起到测试作用。反例应当确实具有迷惑性。

第二步：与用户共同审阅

使用 HTML 模板将评估集提交给用户审阅：

1. 从 assets/eval_review.html 读取模板
2. 替换占位符：
   • __EVAL_DATA_PLACEHOLDER__ → 评估条目的 JSON 数组（不加引号，因为它是 JS 变量赋值）
   • __SKILL_NAME_PLACEHOLDER__ → Skill 的名称
   • __SKILL_DESCRIPTION_PLACEHOLDER__ → Skill 当前的 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。best_description 按测试分数而非训练分数选出，以避免过拟合。

技能触发机制

了解触发机制有助于设计更好的评测查询。技能会以名称和描述的形式出现在 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 评测一致性（CtrlCarlitos/skills#10）：run_eval.py/run_loop.py 也支持 --harness codex 和 --harness opencode（默认仍为 claude），分别通过各自的非交互式 CLI（codex exec/opencode run）驱动对应的 harness，并根据各自的事件格式检测技能是否触发——两者的事件格式都与 Claude 的 Skill 工具不同。没有 --harness antigravity：Antigravity 无法像 Codex/OpenCode 那样可靠地发现项目本地的一次性技能（已通过实际测试确认），而可用的适配器每次评测查询都需要写入用户实际的全局技能目录；此分支不会默默这样做。如果你要评测的是面向 Antigravity 的技能，请将其视为未经测试的 harness，并明确说明，而不要声称分数可以迁移。opencode 自带的 CLI 在某些环境中存在已确认的严重可靠性问题（它可能完全没有输出并卡住，与受测技能无关）——如果其运行报告的错误率高于 claude/codex，很可能反映的是这个问题，而不是描述本身。请参阅 vendor/skill-creator/DISPOSITION.md。

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

打包：package_skill.py 脚本可在任何具备 Python 和文件系统的环境中运行。在 Claude.ai 中，你可以运行该脚本，然后让用户下载生成的 .skill 文件。

更新现有技能：用户可能是要你更新现有技能，而不是创建新技能。在这种情况下：

• 保留原始名称。 记下技能的目录名称和 name frontmatter 字段，并保持不变。例如，如果已安装的技能是 research-helper，则输出 research-helper.skill（而不是 research-helper-v2）。
• 编辑前先复制到可写位置。 已安装的技能路径可能是只读的。请复制到 /tmp/skill-name/，在该目录中编辑，并从副本进行打包。
• 如果手动打包，请先暂存到 /tmp/，然后再复制到输出目录——直接写入可能会因权限问题失败。

---

Cowork 专用说明

如果你在 Cowork 中，需要了解的主要事项如下：

• 你可以使用子 Agent，因此主要工作流（并行生成测试用例、运行基线、评分等）都可以正常进行。（但如果遇到严重的超时问题，可以改为串行运行测试提示词，而不是并行。）
• 你没有浏览器或显示界面，因此生成评估查看器时，请使用 --static <output_path> 生成独立的 HTML 文件，而不是启动服务器。然后提供一个链接，供用户点击并在浏览器中打开该 HTML。
• 由于某些原因，Cowork 环境似乎让 Claude 不太愿意在运行测试后生成评估查看器，因此在此再次强调：无论你是在 Cowork 还是 Claude Code 中，运行测试后都应始终生成评估查看器，让用户先查看示例，然后再自行修改 Skill 并尝试纠正。请使用 generate_review.py（不要自己编写临时 HTML 代码）。抱歉要重复强调，我要用全大写说明：在你自己评估输入之前，先生成评估查看器！你要尽快让用户看到这些内容！
• 反馈的工作方式不同：由于没有运行中的服务器，查看器中的“Submit All Reviews”按钮会将 feedback.json 下载为文件。之后你可以从该文件读取反馈（可能需要先请求访问权限）。
• 打包可以正常工作，package_skill.py 只需要 Python 和文件系统。
• 描述优化（run_loop.py / run_eval.py）在 Cowork 中应可正常运行，因为它通过子进程调用 claude -p，而不是浏览器。但请先等 Skill 完全制作完成，并且用户认可其质量后再进行此步骤。
• 更新现有 Skill：用户可能要求你更新已有的 Skill，而不是创建新的。请遵循上文 claude.ai 部分中的更新指南。

---

参考文件

agents/ 目录包含专用子 Agent 的说明。需要生成相应子 Agent 时再阅读这些文件。

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

references/ 目录包含其他文档：

• references/schemas.md：evals.json、grading.json 等文件的 JSON 结构

---

再次重复核心循环，以示强调：

• 明确 Skill 的用途
• 起草或编辑 Skill
• 在测试提示词上运行可访问该 Skill 的 Claude
• 与用户一起评估输出：
  • 创建 benchmark.json，并运行 eval-viewer/generate_review.py，帮助用户进行审阅
  • 运行定量评估
• 重复上述步骤，直到你和用户都满意
• 打包最终 Skill 并交付给用户。

如果你有待办列表功能，请将这些步骤加入其中，以免遗漏。如果你在 Cowork 中，请务必在待办列表中加入“创建 evals JSON 并运行 eval-viewer/generate_review.py，以便用户审阅测试用例”这一项。

祝你好运！