创建新技能、修改和改进现有技能，并衡量技能性能。当用户想要从头开始创建技能、编辑或优化现有技能、运行评估以测试技能、通过方差分析衡量技能性能基准，或优化技能描述以获得更好的触发准确度时使用。
创建新技能、修改和改进现有技能，并衡量技能性能。当用户想要从头开始创建技能、编辑或优化现有技能、运行评估以测试技能、通过方差分析衡量技能性能基准，或优化技能描述以获得更好的触发准确度时使用。
npx skills add https://github.com/HelloEveryboby/Butler --skill skill-creatorこのコマンドをClaude Codeにコピー＆ペーストしてスキルをインストール
Adobe Photoshop 图像处理专家。精通图层与蒙版、选区与抠图、调色与校色、修图与美化、文字特效、滤镜应用及基础设计。当用户需要编辑图像、合成照片、设计图形或优化图片时，应启用此技能。
Adobe Creative Suite 全能助手。精通 Photoshop 图像处理、Illustrator 矢量设计、Premiere Pro 视频剪辑、After Effects 动效制作、InDesign 排版设计、Lightroom 摄影后期与 XD 原型设计。当用户需要处理图像、设计图形、剪辑视频、制作动效、排版或编辑照片时，应启用此技能。
微软 Office 官方套件全能助手。精通 Word 文档排版、Excel 数据分析与公式、PowerPoint 演示设计、Outlook 邮件管理及 OneNote 笔记整理。当用户需要创建文档、处理表格、制作幻灯片、管理邮件或整理笔记时，应启用此技能。
WPS Office 官方套件全能助手。精通 WPS 文字排版与审校、WPS 表格数据处理与函数、WPS 演示设计、WPS PDF 编辑与转换，以及 WPS AI 智能办公辅助。当用户需要处理 WPS 相关文档、表格、演示或 PDF 时，应启用此技能。
管理压缩包内容，支持文件改动自动探测、原子更新与原子替换，保障压缩包数据的一致性。
一个用于测试 CLI 动态加载的示例技能。
| name | skill-creator |
| description | 创建新技能、修改和改进现有技能，并衡量技能性能。当用户想要从头开始创建技能、编辑或优化现有技能、运行评估以测试技能、通过方差分析衡量技能性能基准，或优化技能描述以获得更好的触发准确度时使用。 |
这是一个用于创建新技能并进行迭代改进的工具。
从高层级来看，创建技能的过程如下：
eval-viewer/generate_review.py 脚本向用户展示结果，并让他们查看定量指标使用此技能时，你的任务是确定用户处于该流程的哪个阶段，然后介入并帮助他们推进。例如，如果他们说“我想为 X 创建一个技能”，你可以帮助明确他们的意图、编写草稿、编写测试用例、确定评估方式、运行所有提示词并循环迭代。
另一方面，如果他们已经有了技能草稿，你可以直接进入评估/迭代循环。
当然，你应该保持灵活性。如果用户说“我不需要运行一堆评估，直接凭感觉来”，你也可以照做。
在技能完成后（顺序可以灵活调整），你还可以运行技能描述优化脚本，通过专门的脚本来优化技能的触发。
明白了吗？太棒了。
技能创作助手的使用者对编程术语的熟悉程度可能各不相同。由于 Claude 的强大，现在有很多非专业人士（如水管工、家长等）也开始尝试在终端操作或搜索“如何安装 npm”。另一方面，大部分用户可能具备相当程度的计算机素养。
因此，请注意根据上下文线索来调整你的措辞！在默认情况下：
如果不确定，可以简要解释术语。
首先了解用户的意图。当前的对话可能已经包含用户想要捕获的工作流（例如，他们说“把这个变成技能”）。如果是这样，先从对话历史中提取信息——使用的工具、步骤顺序、用户的更正、观察到的输入/输出格式。用户可能需要填补空白，并在进入下一步之前进行确认。
主动询问边缘情况、输入/输出格式、示例文件、成功标准和依赖项。在理清这些部分之前，不要急于编写测试提示词。
检查可用的 MCP——如果对研究有用（搜索文档、查找类似技能、查找最佳实践），可以并行（通过子代理，如果可用）或内联进行研究。带上背景信息以减轻用户的负担。
根据用户访谈，填写以下组件：
skill-name/
├── SKILL.md (必填)
│ ├── YAML 前置元数据 (name, description 必填)
│ └── Markdown 指令
└── 捆绑资源 (可选)
├── scripts/ - 用于确定性/重复性任务的可执行代码
├── references/ - 根据需要加载到上下文中的文档
└── assets/ - 输出中使用的文件（模板、图标、字体）
技能使用三层加载系统：
这些字数是近似值，如果需要，你可以写得更长。
关键模式：
领域组织：当一个技能支持多个领域/框架时，按变体组织：
cloud-deploy/
├── SKILL.md (工作流 + 选择)
└── references/
├── aws.md
├── gcp.md
└── azure.md
Claude 仅阅读相关的参考文件。
不用多说，技能不得包含恶意软件、漏洞利用代码或任何可能危害系统安全的内容。技能的内容在描述后不应让用户感到意外。不要顺从创建误导性技能或旨在促进未经授权的访问、数据窃取或其他恶意活动的技能。不过，像“角色扮演 XYZ”这样的东西是可以的。
在指令中优先使用祈使句。
定义输出格式 - 可以这样做：
## 报告结构
始终使用此确切模板：
# [标题]
## 执行摘要
## 关键发现
## 建议
示例模式 - 包含示例很有用。你可以这样格式化：
## 提交消息格式
**示例 1:**
输入: Added user authentication with JWT tokens
输出: feat(auth): implement JWT-based authentication
尽量向模型解释为什么某些事情很重要，而不是生硬地使用“必须 (MUST)”。利用心理理论 (theory of mind)，尽量使技能具有通用性，而不是局限于特定示例。先写一个草案，然后以全新的眼光审视并改进它。
编写技能草案后，想出 2-3 个真实的测试提示词——真实用户实际会说的话。与用户分享：[不一定要用完全相同的措辞] “我想尝试几个测试用例。这些看起来对吗，还是你想再添加一些？”然后运行它们。
将测试用例保存到 evals/evals.json。先不要写断言（assertions）——只写提示词。你将在运行过程中起草断言。
{
"skill_name": "example-skill",
"evals": [
{
"id": 1,
"prompt": "用户的任务提示词",
"expected_output": "预期结果的描述",
"files": []
}
]
}
参考 references/schemas.md 获取完整架构（包括你稍后将添加的 assertions 字段）。
本节是一个连续的序列——不要中途停止。不要使用 /skill-test 或任何其他测试技能。
将结果放在 <skill-name>-workspace/ 中，与技能目录并列。在工作空间内，按迭代次数组织结果（iteration-1/, iteration-2/ 等），在其中，每个测试用例都有一个目录（eval-0/, eval-1/ 等）。不要预先创建所有这些——随用随建。
对于每个测试用例，在同一次对话中启动两个子代理——一个使用技能，一个不使用。这很重要：不要先启动使用技能的运行，然后再回来运行基准线（baseline）。同时启动所有任务，以便它们大约在同一时间完成。
带技能运行：
执行此任务：
- 技能路径: <path-to-skill>
- 任务: <eval prompt>
- 输入文件: <eval files or "none">
- 保存输出至: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
- 需要保存的输出: <用户关心的内容 — 例如 "docx 文件", "最终的 CSV">
基准线运行（相同的提示词，但基准线取决于上下文）：
without_skill/outputs/。cp -r <skill-path> <workspace>/skill-snapshot/)，然后让基准线子代理指向该快照。保存到 old_skill/outputs/。为每个测试用例编写 eval_metadata.json（断言暂时可以为空）。为每个评估起一个基于其测试内容的描述性名称——而不仅仅是 "eval-0"。该名称也用于目录名。如果此迭代使用了新的或修改过的评估提示词，请为每个新的评估目录创建这些文件——不要假设它们会从上一次迭代中继承。
{
"eval_id": 0,
"eval_name": "描述性名称",
"prompt": "用户的任务提示词",
"assertions": []
}
不要干等着运行结束——你可以高效利用这段时间。为每个测试用例起草定量断言，并向用户解释。如果 evals/evals.json 中已经存在断言，请审阅并向用户解释它们检查的内容。
好的断言应该是客观可验证的，并具有描述性的名称——它们应该能在基准测试查看器中清晰呈现，让看结果的人一眼就能明白每项检查的是什么。主观技能（写作风格、设计质量）最好进行定性评估——不要强行在需要人类判断的事情上添加断言。
起草完成后，更新 eval_metadata.json 文件和 evals/evals.json。同时向用户解释他们将在查看器中看到什么——包括定性输出和定量基准测试。
当每个子代理任务完成时，你会收到一条包含 total_tokens 和 duration_ms 的通知。立即将此数据保存到运行目录下的 timing.json 中：
{
"total_tokens": 84852,
"duration_ms": 23332,
"total_duration_seconds": 23.3
}
这是捕获此数据的唯一机会——它通过任务通知传来，不会持久化到其他地方。收到通知时立即处理，而不是尝试批量处理。
所有运行完成后：
为每次运行评分 — 启动一个评分员子代理（或内联评分），阅读 agents/grader.md 并根据输出评估每个断言。将结果保存到每个运行目录下的 grading.json。grading.json 的 expectations 数组必须使用 text, passed, 和 evidence 字段（而不是 name/met/details 或其他变体）——查看器依赖这些确切的字段名。对于可以程序化检查的断言，编写并运行脚本而不是目测——脚本更快、更可靠，且可以跨迭代重用。
汇总到基准测试 — 在技能创作助手目录下运行汇总脚本：
python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>
这将生成 benchmark.json 和 benchmark.md，包含每个配置的通过率、时间和 Token 消耗，以及均值 ± 标准差和变化量（delta）。如果手动生成 benchmark.json，请参阅 references/schemas.md 了解查看器所需的具体架构。
将 with_skill 版本放在对应的基准线版本之前。
进行分析评估 — 阅读基准测试数据并发现汇总统计数据可能隐藏的模式。参阅 agents/analyzer.md（“分析基准测试结果”部分）了解要寻找的内容——例如无论是否有技能都始终通过的断言（无区分度）、高方差的评估（可能不稳定）以及时间/Token 的权衡。
启动查看器，展示定性输出和定量数据：
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。
“输出 (Outputs)”标签页一次显示一个测试用例：
“基准测试 (Benchmark)”标签页显示统计摘要：每个配置的通过率、耗时和 Token 使用情况，以及每个评估的详细细分和分析观察。
通过上一个/下一个按钮或方向键导航。完成后，他们点击“提交所有评价”，将所有反馈保存到 feedback.json。
当用户告诉你他们完成时，读取 feedback.json：
{
"reviews": [
{"run_id": "eval-0-with_skill", "feedback": "图表缺少轴标签", "timestamp": "..."},
{"run_id": "eval-1-with_skill", "feedback": "", "timestamp": "..."},
{"run_id": "eval-2-with_skill", "feedback": "完美，非常喜欢", "timestamp": "..."}
],
"status": "complete"
}
空的反馈意味着用户认为它没问题。将改进重点放在用户有具体投诉的测试用例上。
使用完后杀掉查看器服务器进程：
kill $VIEWER_PID 2>/dev/null
这是循环的核心。你运行了测试用例，用户审阅了结果，现在你需要根据他们的反馈让技能变得更好。
从反馈中归纳总结。 这里的核心是我们要创建可以被使用数百万次（甚至更多）的技能，而不仅仅是针对这些特定的提示词。你和用户在这里反复迭代几个例子，是因为这有助于提高速度。用户非常了解这些例子，可以快速评估新输出。但如果你们共同开发的技能仅适用于这些例子，那它就是无用的。与其进行繁琐的过度拟合修改或生硬的强制性要求，如果存在顽固问题，你可以尝试换一种隐喻，或推荐不同的工作模式。尝试的成本相对较低，也许你会发现很棒的方案。
保持提示词精简。 删除那些不起作用的内容。务必阅读执行过程的记录（transcript），而不仅仅是最终输出——如果看起来技能让模型浪费了大量时间做无用功，你可以尝试去掉导致这种情况的部分，看看会发生什么。
解释原因 (Explain the why)。 努力解释你要求模型做的每件事背后的原因。今天的 LLM 非常聪明。它们具有良好的心理理论，在获得良好的引导时，可以超越机械的指令并真正实现目标。即使用户的反馈很简短或带有负面情绪，也要尝试真正理解任务以及用户为什么要写那些内容，然后将这种理解转化为指令。如果你发现自己使用了全大写的 ALWAYS 或 NEVER，或者使用了极其死板的结构，这是一个警示信号——如果可能，重新表述并解释理由，让模型理解为什么你要求的事情很重要。这是一种更人性化、更强大且更有效的方法。
寻找跨测试用例的重复工作。 阅读测试运行的记录，注意子代理是否都独立编写了类似的辅助脚本，或者对某事采取了相同的多步骤方法。如果所有 3 个测试用例都导致子代理编写了 create_docx.py 或 build_chart.py，这是一个强烈的信号，表明该技能应该捆绑该脚本。编写一次，放入 scripts/，并告知技能去使用它。这可以避免未来的每次调用都重复造轮子。
这项任务非常重要，你的思考时间不是瓶颈；请花时间仔细斟酌。我建议先写一个修订草案，然后重新审视并改进它。尽力进入用户的角色，理解他们的需求。
改进技能后：
iteration-<N+1>/ 目录中，包括基准线运行。如果你正在创建一个新技能，基准线始终是 without_skill（无技能）——这在多次迭代中保持不变。如果你正在改进现有技能，根据判断确定什么作为基准线：用户最初提供的原始版本，或者是上一个迭代。--previous-workspace 指向上一个迭代持续进行直到：
在需要对技能的两个版本进行更严格对比的情况下（例如，用户询问“新版本真的更好吗？”），可以使用盲测对比系统。参阅 agents/comparator.md 和 agents/analyzer.md 了解详细信息。基本思路是：将两个输出交给一个独立的代理，不告诉它哪个是哪个，让它评判质量。然后分析胜出者获胜的原因。
这是可选的，需要子代理，大多数用户不需要。人工评审循环通常已经足够。
SKILL.md 前置元数据中的 description 字段是决定 Claude 是否调用技能的主要机制。在创建或改进技能后，建议优化描述以提高触发准确率。
创建 20 个评估查询——包含应该触发和不应该触发的情况。保存为 JSON：
[
{"query": "用户提示词", "should_trigger": true},
{"query": "另一个提示词", "should_trigger": false}
]
查询必须是真实的，是 Claude Code 或 Claude.ai 用户实际会输入的内容。不是抽象的要求，而是具体、详细的请求。例如，包含文件路径、关于用户工作或处境的个人背景、列名和数值、公司名称、URL。一些背景故事。可能包含小写、缩写、拼写错误或日常用语。混合使用不同的长度，并专注于边缘情况，而不是非黑即白（用户将有机会进行审核）。
不好: "格式化这些数据", "从 PDF 提取文本", "创建一个图表"
好: "好的，我老板刚给我发了这个 xlsx 文件（在我的下载文件夹里，名字叫 'Q4 sales final FINAL v2.xlsx' 之类的），她想让我增加一列显示利润率。收入在 C 列，成本我觉得在 D 列。"
对于应该触发 (should-trigger) 的查询 (8-10 个)，考虑覆盖范围。你需要对同一意图使用不同的表述——有正式的，也有非正式的。包含用户没有明确提及技能或文件类型但显然需要它的情况。加入一些不常见的用例，以及该技能与其他技能竞争但应该胜出的情况。
对于不应触发 (should-not-trigger) 的查询 (8-10 个)，最有价值的是那些“差一点就触发”的查询——那些与技能共享关键字或概念但实际上需要其他处理的查询。考虑相邻领域、不成熟的关键字匹配会触发但实际上不该触发的模糊表述，以及查询涉及技能所做的事情但在另一个工具更合适的情况下。
关键要避免：不要让“不应触发”的查询变得显而易见地无关。对于 PDF 技能，“编写斐波那契函数”作为一个负面测试太简单了——它测不出任何东西。负面案例应该是真正棘手的。
使用 HTML 模板将评估集展示给用户审阅：
assets/eval_review.html 中的模板__EVAL_DATA_PLACEHOLDER__ → 评估项的 JSON 数组（不用加引号 — 它是 JS 变量赋值）__SKILL_NAME_PLACEHOLDER__ → 技能名称__SKILL_DESCRIPTION_PLACEHOLDER__ → 技能当前的描述/tmp/eval_review_<skill-name>.html）并打开：open /tmp/eval_review_<skill-name>.html~/Downloads/eval_set.json — 检查下载文件夹以获取最新版本，防止存在多个同名文件。这一步非常重要——差的评估查询会导致差的描述。
告知用户：“这需要一些时间 — 我将在后台运行优化循环并定期查看。”
将评估集保存到工作空间，然后在后台运行：
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”这样的简单查询是糟糕的测试用例——无论描述质量如何，它们都不会触发技能。
从 JSON 输出中获取 best_description 并更新技能 SKILL.md 的前置元数据。向用户展示修改前后的对比并报告得分。
present_files 工具可用时）检查你是否有权访问 present_files 工具。如果没有，请跳过此步骤。如果有，打包技能并将 .skill 文件呈现给用户：
python -m scripts.package_skill <path/to/skill-folder>
打包后，指引用户到生成的 .skill 文件路径，以便他们安装。
在 Claude.ai 中，核心流程是相同的（起草 → 测试 → 审阅 → 改进 → 重复），但由于 Claude.ai 没有子代理 (subagents)，一些机制会有所调整：
运行测试用例：没有子代理意味着没有并行执行。对于每个测试用例，阅读技能的 SKILL.md，然后按照其指令亲自完成测试提示词任务。一次做一个。这不如独立子代理那么严谨（因为是你编写了技能且你在运行它，所以你拥有完整的背景信息），但这是一个有用的健全性检查——人类评审步骤会弥补这一点。跳过基准线运行——直接使用技能完成请求的任务。
审阅结果：如果你无法打开浏览器（例如，Claude.ai 的虚拟机没有显示器，或者你在远程服务器上），请跳过浏览器查看器。直接在对话中呈现结果。对于每个测试用例，显示提示词和输出。如果输出是用户需要查看的文件（如 .docx 或 .xlsx），将其保存到文件系统并告知其位置，以便他们下载检查。在线询问反馈：“这个看起来怎么样？有什么想修改的吗？”
基准测试：跳过定量基准测试——它依赖于基准线对比，而没有子代理的情况下基准线对比没有意义。专注于来自用户的定性反馈。
迭代循环：与之前相同——改进技能，重新运行测试用例，征求反馈——只是中间没有浏览器查看器。如果文件系统允许，你仍然可以在文件系统上将结果组织到迭代目录中。
描述优化：此部分需要 claude CLI 工具（特别是 claude -p），该工具仅在 Claude Code 中可用。如果你在 Claude.ai 上，请跳过。
盲测对比：需要子代理。跳过。
打包：package_skill.py 脚本在任何有 Python 和文件系统的地方都可以运行。在 Claude.ai 上，你可以运行它，用户可以下载生成的 .skill 文件。
更新现有技能：用户可能要求你更新现有技能，而不是创建新技能。在这种情况下：
name 字段 —— 保持不变地使用它们。例如，如果安装的技能是 research-helper，输出 research-helper.skill（而不是 research-helper-v2）。/tmp/skill-name/，在那里编辑，并从副本中打包。/tmp/，然后复制到输出目录 —— 由于权限问题，直接写入可能会失败。如果你在 Cowork 中，需要了解的主要事项是：
--static <output_path> 写入一个独立的 HTML 文件，而不是启动服务器。然后提供一个链接，用户可以点击该链接在他们的浏览器中打开该 HTML。generate_review.py（而不是编写自己的 HTML 代码）生成评估查看器，供人类在你自己修订技能和尝试更正之前查看示例。在此提前致歉，但我必须在这里使用全大写：在你自己评估输入之前生成评估查看器。你要尽快将它们展示在人类面前！feedback.json 作为文件下载。然后你可以从那里读取它（你可能需要先请求访问权限）。package_skill.py 只需要 Python 和文件系统。run_loop.py / run_eval.py) 在 Cowork 中应该运行良好，因为它通过子进程使用 claude -p，而不是浏览器，但请等到你完全完成技能制作且用户同意其状况良好后再进行。agents/ 目录包含专用子代理的指令。当你需要启动相关子代理时，请阅读它们。
agents/grader.md — 如何根据输出评估断言agents/comparator.md — 如何对两个输出进行盲测 A/B 对比agents/analyzer.md — 如何分析一个版本优于另一个版本的原因references/ 目录有补充文档：
references/schemas.md — evals.json, grading.json 等的 JSON 结构。再次重复核心循环以示强调：
eval-viewer/generate_review.py 以帮助用户审阅如果你的 TodoList（或者类似的东西）中有相关步骤，请添加它们以确保你不会忘记。如果你在 Cowork 中，请专门将“创建 evals JSON 并运行 eval-viewer/generate_review.py 以便人类审阅测试用例”放入你的 TodoList 以确保它发生。
祝你好运！