skill-creator

技能创建器

用于创建新技能并对其进行迭代改进的技能。

从总体上看，创建技能的流程如下：

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

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

另一方面，如果他们已经有技能草稿，你可以直接进入评估和迭代环节。

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

技能完成后（但流程顺序仍可灵活调整），你还可以运行技能描述改进器来优化技能的触发方式。我们另有一个专门的脚本用于此目的。

根据用户调整术语；必要时说明评估标准。

创建技能

梳理意图

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

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

访谈与调研

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

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

编写 SKILL.md

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

• name：技能标识符（1–64 个字符，仅限小写字母 a–z、数字 0–9 和连字符，且必须与目录名称一致）
• description：说明技能的功能和适用时机（1–1024 个字符，使用第三人称）。列出具体使用场景，并与相近技能区分。根据观察到的触发遗漏和误触发调整其范围，而不是假定每个描述都应该更频繁地触发。
• argument-hint（可选，Claude Code 扩展——不属于 agentskills.io 规范；其他客户端的支持情况各异，严格的验证器会将其标记为问题）：在技能列表中显示，用于指导用户（例如，"[file or directory]"）
• compatibility（可选）：平台／环境要求，1–500 个字符
• 技能的其余内容 :)

技能编写指南

编写最佳实践

参考：https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices — 完整清单位于 references/best-practices.md；编写或审查技能内容前请先阅读。起草时最重要的四项原则：

• Claude 本身已经非常聪明。 补充 Agent 缺少的信息：本地决策及其原因、经过测量的发现、非显而易见的约定，以及在技能运行环境中有效的来源路径（并非每个客户端都能访问 URL）。如果能避免实际错误，请保留简短的资源索引或准确的架构；避免重复代码库内容或讲解常规的探索方法。
• 简洁是关键。 在保留任务所需知识和完成标准的同时，删去重复内容和基础知识。若准确的名称或简短片段能澄清非显而易见的 API 约定或必需输出，就优先使用；普通 API 无需逐一举例。
• 让自由度与脆弱性相匹配。 有多种可行方式时使用文字指导；一致性至关重要时使用精确脚本。大多数技能介于两者之间。
• 使用第三人称描述。 使用“处理 Excel 文件”，而不是“我可以帮你处理 Excel 文件”——描述会注入系统提示词，混用视角会影响发现效果。

技能的组成

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. 元数据（名称 + 描述）——客户端发现／选择；列表行为因客户端而异
2. SKILL.md 正文——技能触发时始终处于上下文中（理想情况下少于 500 行）
3. 打包资源——按需加载；读取前不会加载任何内容，且脚本无需加载其源代码即可运行。打包文件也适用于 Agent 无法联网的环境

上述字数仅为大致估算，如有需要，可以适当增加。

关键模式：

• 力求核心内容简洁；500 行是建议值，而非格式限制。删除重复内容后，将不同主题链接起来，并说明何时阅读。
• 在 SKILL.md 中清楚地引用参考文件，并说明何时阅读
• 对于较长且涉及多个主题的参考资料，如果目录有助于定位相关章节，请添加简短目录；仅行数较多并不意味着必须添加目录。

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

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

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

不令人意外原则

这不言而喻，但技能不得包含恶意软件、漏洞利用代码或任何可能危及系统安全的内容。如果技能内容的意图会让用户感到意外，就不应包含其中。不要顺从创建误导性技能，或旨在助长未授权访问、数据外泄或其他恶意活动的请求。不过，“扮演某个角色”之类的内容是可以的。

写作模式

在说明中优先使用祈使句。

定义输出格式——如果下游工作流或解析器需要特定格式，请指定精确模板。对于开放式任务，请说明所需信息，并采用项目的格式。对于固定的报告规范：

## Report structure
Use this structure when producing the report required by this workflow:
# [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

注意事项

当一些不明显的陷阱可能导致合理但错误的操作时，请将其列出：环境特性、隐含假设，或 Agent 无法从代码中推断出的行为。不要仅仅为了重复主要说明而添加“注意事项”章节。

发布前检查清单

在宣布技能完成前，请检查格式和引用的文件：name 与目录名称一致（小写字母加连字符，1–64 个字符），且 description 具体、使用第三人称，并且不超过 1024 个字符。根据任务评估篇幅、引用结构和触发行为。保留必要的版本范围或带日期的本地观察，并提供当前来源；没有来源时，避免提出易变的说法。

写作风格

尽量向模型解释事情为何重要，而不是用过于强硬的 MUST 要求。设身处地思考，并尽量让技能适用于一般情况，而不是局限于特定示例。先写一份草稿，再以全新的视角检查并改进。

测试用例

写完技能草稿后，构思 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 版本放在对应的基线版本之前。

3. 进行分析——阅读基准测试数据，找出汇总统计数据可能掩盖的规律。查看 agents/analyzer.md 的“分析基准测试结果”部分，了解需要关注的内容，例如无论技能如何都总是通过的断言（缺乏区分度）、方差较大的评估（可能不稳定），以及时间与 token 的权衡。

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

   python <skill-creator-path>/eval-viewer/generate_review.py \
     <workspace>/iteration-N \
     --skill-name "my-skill" \
     --benchmark <workspace>/iteration-N/benchmark.json &
   

   在 Windows 上，去掉末尾的 & 并在单独的终端中运行，或者使用 --static <output_path> 生成独立的 HTML 文件，而不是启动服务器。 从第 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”选项卡显示统计摘要：每种配置的通过率、耗时和令牌用量，以及各项评估的细分数据和分析员的观察。

可通过“上一项”/“下一项”按钮或方向键进行导航。完成后，用户点击“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"
}

反馈为空表示用户认为结果没问题。请重点改进用户提出具体意见的测试用例。

完成后关闭查看器服务。在 Unix/macOS 上使用 kill <PID>，在 Windows 上使用 taskkill /PID <PID> /F，或者直接在运行服务的终端中按 Ctrl+C。

---

改进技能

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

如何思考改进

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. 阅读新的反馈，再次改进，然后重复以上步骤

持续进行，直到：

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

---

高级：盲测比较

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

这是可选的，需要使用子 Agent，大多数用户通常用不到。人工审查循环通常就足够了。

---

描述优化

SKILL.md 前置元数据中的描述字段，是决定 Claude 是否调用某项技能的主要机制。创建或改进技能后，请提供优化描述的选项，以提高触发准确度。

第 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 条），最有价值的是似是而非的情况——查询中虽然包含与技能相关的关键词或概念，实际需要的却是其他内容。请考虑相邻领域、措辞模糊但朴素的关键词匹配可能会触发的情况，以及查询涉及该技能能处理的内容、但更适合使用其他工具的情况。

最重要的是避免：不要让不应触发的查询明显无关。将“编写一个斐波那契函数”作为 PDF 技能的负向测试过于简单——这种测试毫无检验价值。负向用例应当是真正棘手的情况。

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

使用经过身份验证的 Claude CLI 支持的模型 ID。当前主机模型可能属于其他提供商；不要盲目地将其 ID 传给 claude -p。

运行期间，定期查看输出，告知用户当前迭代次数和评分情况。

此流程会自动完成整个优化循环。它将评估集拆分为 60% 的训练集和 40% 的留出测试集，评估当前描述（每个查询运行 3 次，以获得可靠的触发率），然后调用 Claude 根据失败的情况提出改进建议。它会在训练集和测试集上重新评估每个新描述，最多迭代 5 次。完成后，会在浏览器中打开 HTML 报告，展示每次迭代的结果，并返回包含 best_description 的 JSON——该描述根据留出集评分而非训练集评分选出。由于它会据此选出胜者，这种拆分相当于验证数据；如需获得无偏估计，请使用新的最终测试集。

技能触发的工作方式

触发评估会检查技能是否是第一个工具调用；如果技能是在其他工具之后使用的，则计为未触发（本地评估器，已于 2026-10-11 检查）。

描述有助于主机选择技能，但是否激活取决于客户端、模型和可用工具。请测试简单和复杂的真实请求，包括容易混淆的请求；不要假设简单请求绝不会触发技能。 请将最终留出集与用于选择描述的查询分开；反复使用同一个测试集进行选择，可能会导致对该测试集过拟合。

步骤 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 文件。

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

• 保留原名称。 记下技能的目录名称和 name frontmatter 字段，并保持不变。例如，如果已安装的技能是 research-helper，则输出 research-helper.skill（而不是 research-helper-v2）。
• 编辑前复制到可写位置。 已安装技能的路径可能是只读的。请将其复制到临时目录，在那里编辑，并使用副本进行打包。

---

Cowork 专属说明

如果你在 Cowork 中，主要需要了解以下几点：

• 你可以使用子 Agent，因此主要工作流（并行生成测试用例、运行基线、评分等）都适用。（不过，如果遇到严重的超时问题，可以按顺序而不是并行运行测试提示词。）
• 你没有浏览器或显示界面，因此生成评估查看器时，请使用 --static <output_path> 写入独立的 HTML 文件，而不是启动服务器。然后提供一个链接，供用户点击并在浏览器中打开 HTML 文件。
• Cowork 设置有时会跳过评估查看器这一步。请注意：无论你使用的是 Cowork 还是 Claude Code，运行测试后，都应始终生成评估查看器，供用户查看，然后再自行修改技能。请使用 generate_review.py（不要使用自定义 HTML）。用户的反馈是最有价值的信号——开始修改之前，先让他们查看评估器。
• 反馈的处理方式有所不同：由于没有运行中的服务器，查看器上的“Submit All Reviews”按钮会将 feedback.json 下载为文件。之后你可以从中读取反馈（可能需要先申请访问权限）。
• 打包功能可用——package_skill.py 只需要 Python 和文件系统。
• 更新现有技能：遵循上文 claude.ai 部分中的更新指南。
• 描述优化（run_loop.py / run_eval.py）在 Cowork 中应该也能正常运行，因为它通过子进程调用 claude -p，而不是使用浏览器；不过，请等到技能完全完成且用户认可其质量后再进行。

---

依赖项

此技能中的脚本需要：

• Python 3.10+ 和 pyyaml（pip install pyyaml）
• claude CLI——run_eval.py、run_loop.py 和 improve_description.py 都会调用它们，并通过 shell 执行 claude -p

不需要 ANTHROPIC_API_KEY：每个脚本都会复用当前会话自身的 Claude Code 身份验证信息。

参考文件

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

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

references/ 目录包含其他文档：

• references/schemas.md — evals.json、grading.json 等文件的 JSON 结构
• references/best-practices.md — 全面的技能编写参考（frontmatter 规则、描述撰写、渐进式披露、脚本设计、反模式）。编写或审查技能内容质量时请阅读。
• references/cross-agent-guide.md — 平台专属的发现路径和跨 Agent 兼容性。技能需要在 Claude Code、Codex 或 Gemini CLI 上运行时请阅读。

---

核心循环提醒： 捕捉意图 → 起草技能 → 运行测试提示词 → 与用户一起评估（generate_review.py + 基准测试）→ 改进 → 重复，直到满意 → 打包。

如果你有 TodoList，请添加“运行 eval-viewer/generate_review.py，以便用户审核测试用例”，确保这一步不会遗漏。祝你顺利！