custom-skill-creator

Skill Creator

用于创建新技能并逐步改进技能的技能。

⚠️ 完整性约定：此工作流包含 6 个阶段：意图 → 草拟 → 测试与评估 → 迭代 → 优化描述 → 打包。在向用户提供描述优化之前，工作流尚未完成。如果还没到这一步，就还有工作要做。

开始之前，先确定用户目前处于此流程的哪个阶段，以及还剩哪些阶段——包括本文件末尾的阶段。只有在能够说出所有剩余阶段之后，才能开始执行。

从宏观来看，创建技能的流程如下：

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

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

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

当然，也要灵活应对。如果用户说“我不需要跑一堆评估，随便跟我聊聊就好”，那就按他们的意思来。

用户对技能的表现感到满意后，还有一个关键步骤：优化描述。描述字段是决定 Claude 是否调用某项技能的主要机制，而且我们专门为它设计了一套优化流程。不要跳过这一步——即使技能设计得很好，描述写得不好也永远不会触发。

明白了吗？很好。

与用户沟通

使用技能创建器的人对编程术语的熟悉程度可能差异很大。如果你还没注意到（这种趋势也才刚刚兴起），Claude 的强大能力正促使水管工打开终端，父母和祖父母在 Google 上搜索“如何安装 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
Use this template:
# [Title]
## Executive summary
## Key findings
## Recommendations

示例模式——加入示例会很有帮助。可以按这种方式编排（但如果示例中出现“Input”和“Output”，你可能需要稍作调整）：

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

写作风格

与其生硬地反复强调 MUST，不如试着向模型解释事情为什么重要。运用心智理论，尽量让技能具有普适性，而不是局限于特定示例。先写一份草稿，再以全新的视角审视并改进它。

面向 Agent 认知的设计

有件事非常重要，但大多数人都没意识到：Agent 读取 SKILL.md 时，不会平等地看待文件中的所有内容。有三种力量会对你不利：

• 首因偏差：最前面的约 1,000 个 token 会被视为“核心任务”。之后的内容会逐渐沦为“实现细节”。这不是提示词的问题，而是 Transformer 注意力机制的工作方式。
• 贪婪执行：一旦 Agent 发现一个可执行步骤，“执行”循环就会覆盖“阅读”循环。它会停止阅读并开始行动，往往还没读到文件末尾。
• 中间遗失：无论内容多么重要，长文档中间约 40% 的内容对 Agent 行为的影响最弱。这在文献中已有充分记录，并且会影响每个模型。

结果就是：在包含 6 个阶段的流水线中，Agent 会忠实执行阶段 1–3，却跳过阶段 4–6。不是因为缺少指令，而是因为这些指令在第 300 行。

SKILL.md 文件不是文档，而是行为契约。 设计时应采用以下应对措施：

1. 流水线承诺关卡——在 Agent 采取任何行动之前，要求它确认所有阶段，包括最后一个阶段。如果它说不出阶段 5 是什么，就说明它还没读过阶段 5。

   > This workflow has 4 phases: Research → Draft → Review → Publish.
   > It is incomplete until Publish is done. Confirm all phases before starting.
   

2. 开头提及结尾——在前 10 行中，说明“完成”是什么样子，并明确说出最后一个阶段。这会迫使注意力机制向后关注。

   > This skill is not finished until the cleanup report is generated (Phase 4).
   

3. 在易于脱身处设置内联检查点——在 Agent 自然觉得“完成了”的确切时刻（主要工作已完成，但清理或集成仍待处理），插入一个明确的停止点，指出还有哪些工作待完成：

   ⚠️ Checkpoint: If you haven't generated the report yet, you're not done.
   Check remaining phases before proceeding.
   

   应将这些检查点放在 Agent 产生“我做完了”念头的那个具体心理时刻——通常是在交付主要成果之后、执行集成、审核或打包步骤之前。

4. 模块化阶段文件——对于接近 500 行的技能，将各阶段拆分为 references/ 下的独立文件。每次读取文件都会重置首因窗口，因此阶段 4 能获得 Agent 的全部注意力，而不必与阶段 1 争夺注意力。

这些并非可有可无的最佳实践，而是针对已知失效模式的结构性应对措施。从第一天起，就应将它们纳入每项技能。

测试用例

写完技能草稿后，想出 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。

运行和评估测试用例

本节是一个连续流程——不要中途停止、不要跳过后续步骤去改进技能，也不要宣布任务已完成。必须完成以下全部 5 个步骤后才能继续。不要使用 /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. 启动查看器，同时提供定性输出和定量数据：

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

持续迭代，直到：

• 用户表示满意
• 所有反馈都为空（即一切看起来都很好）
• 改进已无实质进展

⚠️ 检查点：迭代循环可能已经结束，但工作流还没有结束。你仍需提供描述优化和打包（见下文相应章节）。在这两个阶段完成之前，不要结束对话。

高级：盲测比较

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

此步骤可选，需要子 Agent，大多数用户都用不上。通常通过人工审核即可。

---

优化描述

SKILL.md 前置元数据中的 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 条），最有价值的是那些容易混淆的案例——查询中含有与技能相关的关键词或概念，但实际需要的是其他功能。考虑相邻领域、措辞含糊而简单的关键词匹配可能导致错误触发的情况，以及查询涉及本技能能处理的内容、但更适合使用其他工具的情况。

关键是避免让不应该触发的查询显得明显无关。把“编写一个斐波那契函数”作为 PDF 技能的负向测试太容易了，完全起不到测试作用。负向案例应该足够棘手，确实具有迷惑性。

第 2 步：与用户审核

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

1. 从 assets/eval_review.html 读取模板
2. 替换占位符：
   • __EVAL_DATA_PLACEHOLDER__ → 评估条目组成的 JSON 数组（变量赋值时不要给它加引号）
   • __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。检查 Downloads 文件夹，找到最新版本，以防有多个文件（例如 eval_set (1).json）

此步骤很重要——评估查询质量差，会导致 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 前置元数据。向用户展示修改前后的内容，并报告得分。

---

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

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

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

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

---

环境特定的调整

如果你运行在 Claude.ai 或 Cowork 中（而非 Claude Code），请阅读 references/environment-adaptations.md，了解工作流需要如何调整——主要涉及子 Agent 的可用性、浏览器访问和描述优化。

---

参考文件

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

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

references/ 目录包含更多文档：

• references/schemas.md — evals.json、grading.json 等文件的 JSON 结构
• references/environment-adaptations.md — Claude.ai 和 Cowork 的工作流调整

---

完成清单

在宣布此工作流完成之前，请确认每个阶段都已处理：

• 意图 — 已理解此技能应执行的操作及其触发时机
• 草稿 — 已编写或编辑 SKILL.md，并应用 Agent 认知原则
• 测试与评估 — 已运行测试用例、生成评估查看器（generate_review.py），并获得人工反馈
• 迭代 — 已根据反馈改进技能，并重新运行测试，直到用户满意
• 描述优化 — 已提出描述优化循环，并在接受后运行
• 打包 — 如果 present_files 可用，已提出打包

如果有任何一项未勾选，就表示尚未完成。请将这些步骤添加到 TodoList，确保不会遗漏。如果你使用的是 Cowork，请务必在 TodoList 中加入“创建 evals JSON 并运行 eval-viewer/generate_review.py，以便人工审核测试用例”。

祝你顺利！