skill-creator-cn

# 技能创建器 (Skill Creator 中文版) 一个用于创建新技能并迭代改进的技能。 高层次上，创建技能的过程如下： - 确定你希望技能做什么以及大致如何实现 - 撰写技能草稿 - 创建几个测试提示词（prompt），让拥有该技能的 Claude 运行它们 - 帮助用户定性和定量地评估结果 - 在运行进行的同时，如果没有定量评估则草拟一些；如果有则直接使用或根据需求修改。然后向用户解释这些评估 - 使用 `eval-viewer/generate_review.py` 脚本向用户展示结果，同时让他们查看定量指标 - 根据用户对结果的评估反馈来重写技能（同时也要注意定量基准中暴露出的明显缺陷） - 重复上述步骤直到满意为止 - 扩展测试集，在更大规模上再次尝试 你使用此技能时的任务是：判断用户处于这个过程中的哪个阶段，然后介入并帮助他们推进。例如，用户可能会说"我想为 X 做一个技能"。你可以帮他们明确需求、写草稿、写测试用例、确定评估方式、运行所有提示词、然后重复迭代。 另一方面，也许用户已经有了一份技能草稿。这时你可以直接进入评估/迭代环节。 当然，你应当始终保持灵活——如果用户说"我不需要跑一堆评估，我们直接凭感觉来"，你也可以照做。 技能完成之后（但同样，顺序是灵活的），你还可以运行描述优化脚本，来优化技能的触发准确性。 明白了吗？很好。 --- ## 与用户沟通 技能创建器的使用者可能来自各种技术背景。有些人可能对编程术语很熟悉，有些人可能是第一次接触终端。请注意根据上下文线索调整你的沟通方式！默认情况下： - "评估"和"基准测试"是可接受的词汇 - 对于"JSON"和"断言"这类术语，需要确认用户明白它们的含义后再使用 - 如果不确定，可以简单解释一下相关术语 这不会影响你们——你们通常是在和开发者或至少是有技术背景的用户打交道。但养成好习惯总是没错的。 --- ## 创建技能 ### 捕获意图 首先理解用户的意图。当前对话可能已经包含了用户想要封装成技能的工作流程（例如，用户说"把这个变成技能"）。如果是这样，先从对话历史中提取答案——使用的工具、步骤顺序、用户的纠正、观察到的输入/输出格式。用户可能需要补充空缺内容，并且在进入下一步前应当确认。 1. 这个技能应该让 Claude 能够做什么？ 2. 这个技能应该在什么情况下触发？（用户说什么话/在什么上下文中） 3. 预期的输出格式是什么？ 4. 我们是否应该设置测试用例来验证技能是否正常工作？具有可客观验证输出的技能（文件转换、数据提取、代码生成、固定工作流步骤）适合有测试用例。具有主观输出的技能（写作风格、艺术）通常不需要。根据技能类型建议合适的默认方案，但让用户决定。 ### 面谈与研究 主动询问关于边缘情况、输入/输出格式、示例文件、成功标准和依赖项的问题。在把这些问题弄清楚之前，先不要写测试提示词。 检查可用的工具——如果对研究有用（搜索文档、寻找类似技能、查找最佳实践），可以通过子代理并行研究，否则直接进行研究。做好准备以减少用户的负担。 ### 编写 SKILL.md 根据用户面谈的结果，填写以下组成部分： - **name**：技能标识符 - **description**：何时触发、做什么。这是主要的触发机制——既要包含技能做什么，也要包含何时使用它的具体上下文。所有"何时使用"的信息都放在这里，而不是正文中。注意：目前 Claude 有"欠触发"的趋势——在应该使用技能时不去使用。为了对抗这一点，请让技能描述稍微"强势"一些。例如，不要只写"如何构建一个简单的仪表盘"，而是写"如何构建一个简单的仪表盘来展示内部数据。当你听到用户提到仪表盘、数据可视化、内部指标，或者用户想展示任何类型的公司数据时，务必使用此技能——即使他们没有明确提到'仪表盘'。" - **compatibility**：所需的工具、依赖项（可选，很少需要） - **技能的其余部分 :)** ### 技能编写指南 #### 技能的文件结构 ``` skill-name/ ├── SKILL.md（必需） │ ├── YAML 前置元数据（name、description 为必需） │ └── Markdown 指令 └── 捆绑资源（可选） ├── scripts/ - 用于确定性/重复性任务的可执行代码 ├── references/ - 按需加载到上下文中的文档 └── assets/ - 输出中使用的文件（模板、图标、字体） ``` #### 渐进式信息揭示 技能使用三级加载系统： 1. **元数据**（name + description）——始终在上下文中（约100词） 2. **SKILL.md 正文**——触发技能时始终在上下文中（最好控制在500行以内） 3. **捆绑资源**——按需使用（不限量，脚本可以执行而无需加载） 这些字数仅供参考，如果需要可以延长。 **关键模式：** - 保持 SKILL.md 在 500 行以内；如果接近此限制，增加一层层次结构，并明确指示使用该技能的模型下一步应该去哪里跟进 - 从 SKILL.md 中清晰地引用文件，并说明何时需要读取它们 - 对于大型参考文件（超过 300 行），包含目录 **领域组织**：当技能支持多个领域/框架时，按变体组织： ``` cloud-deploy/ ├── SKILL.md（工作流 + 选择逻辑） └── references/ ├── aws.md ├── gcp.md └── azure.md ``` Claude 只读取相关的参考文件。 #### 无意外原则 技能不能包含恶意软件、漏洞利用代码或任何可能危及系统安全的内容。技能的内容不应当在被描述后让用户感到意外。不要协助创建具有误导性的技能，或旨在实现未授权访问、数据窃取或其他恶意活动的技能。角色扮演类的技能是可以的。 #### 编写模式 在指令中优先使用祈使句。 **定义输出格式** - 可以这样做： ```markdown ## 报告结构 始终使用以下模板： # [标题] ## 执行摘要 ## 主要发现 ## 建议 ``` **示例模式** - 包含示例是有帮助的。可以这样格式化（但如果"输入"和"输出"在示例中，你可能需要稍作调整）： ```markdown ## 提交信息格式 **示例 1：** 输入：使用 JWT 令牌添加用户认证 输出：feat(auth): implement JWT-based authentication ``` ### 写作风格 尽量向模型解释为什么某些事情很重要，而不是用严厉的"必须"。运用心智理论，尽量让技能具有通用性，不要过于狭窄地针对特定示例。先写一份草稿，然后以全新的眼光审视并改进它。 ### 测试用例 写好技能草稿后，提出 2-3 个真实的测试提示词——真实用户会说的那种。分享给用户："这里有几个我想试试的测试用例。这些看起来对吗？还是你想添加更多？"然后运行它们。 将测试用例保存到 `evals/evals.json`。暂时不要写断言——只写提示词。你将在下一步——运行进行中的时候——起草断言。 ```json { "skill_name": "example-skill", "evals": [ { "id": 1, "prompt": "用户的任务提示词", "expected_output": "预期结果的描述", "files": [] } ] } ``` 完整的 schema（包括 `assertions` 字段）请参考 `references/schemas.md`。 --- ## 运行和评估测试用例 本节是一个连续的流程——不要中途停止。不要使用 `/skill-test` 或其他测试技能。 将结果放在 `<skill-name>-workspace/` 中，作为技能目录的同级目录。在工作区内，按迭代组织结果（`iteration-1/`、`iteration-2/` 等），在每个迭代中，每个测试用例对应一个目录（`eval-0/`、`eval-1/` 等）。不要一次性创建所有目录——按需创建。 ### 第一步：在同一轮中启动所有运行（带技能 + 基线） 对于每个测试用例，在同一轮中启动两个子代理——一个有技能，一个没有。这一点很重要：不要先启动带技能的运行然后回头做基线。一次性启动所有任务，这样它们会在大致相同的时间完成。 **带技能运行：** ``` 执行此任务： - 技能路径：<path-to-skill> - 任务：<评估提示词> - 输入文件：<评估文件（如果有），否则为"无"> - 保存输出到：<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"。目录名也使用这个名称。如果本次迭代使用了新的或修改过的评估提示词，请为每个新评估目录创建这些文件——不要假设它们会从之前的迭代继承。 ```json { "eval_id": 0, "eval_name": "描述性名称", "prompt": "用户的任务提示词", "assertions": [] } ``` ### 第二步：在运行进行的同时，起草断言 不要干等运行结束——你可以利用这段时间高效工作。为每个测试用例起草定量断言，并向用户解释它们。如果断言已存在于 `evals/evals.json` 中，请审查它们并解释每一条的检查内容。 好的断言是可客观验证的，并且有描述性名称——它们应该在基准查看器中清晰可读，让瞥一眼结果的人立刻明白每条断言在检查什么。主观技能（写作风格、设计质量）更适合定性评估——不要把断言强加到需要人类判断的事情上。 更新 `eval_metadata.json` 文件和 `evals/evals.json`，加入起草好的断言。同时向用户解释他们在查看器中会看到什么——包括定性的输出和定量的基准数据。 ### 第三步：当运行完成时，捕获计时数据 当每个子代理任务完成时，你会收到包含 `total_tokens` 和 `duration_ms` 的通知。立即将此数据保存到运行目录下的 `timing.json` 中： ```json { "total_tokens": 84852, "duration_ms": 23332, "total_duration_seconds": 23.3 } ``` 这是捕获此数据的唯一机会——它通过任务通知传入，不会被持久化到其他地方。每条通知到达时立即处理，而不是尝试批量处理。 ### 第四步：评分、聚合和启动查看器 当所有运行完成后： 1. **对每次运行进行评分**——启动一个评分子代理（或直接评分），读取 `agents/grader.md` 并评估每条断言。将结果保存到每个运行目录的 `grading.json` 中。grading.json 的 expectations 数组必须使用 `text`、`passed` 和 `evidence` 字段（而不是 `name`/`met`/`details` 等其他变体）——查看器依赖这些确切的字段名。对于可以通过编程方式检查的断言，编写并运行脚本而不是人工目测——脚本更快、更可靠，并且可以在多次迭代中复用。 2. **聚合为基准**——从技能创建器目录运行聚合脚本： ```bash python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name> ``` 这会生成 `benchmark.json` 和 `benchmark.md`，包含每种配置的通过率、时间和 token 数，以及均值 ± 标准差和差值。 3. **进行分析**——阅读基准数据，挖掘聚合统计可能隐藏的模式。查看 `agents/analyzer.md`（"分析基准结果"部分），了解需要关注的内容——比如总是通过的断言（无区分度）、高方差评估（可能不稳定）以及时间/token 的权衡。 4. **启动查看器**，同时展示定性的输出和定量的数据： ```bash python eval-viewer/generate_review.py \ <workspace>/iteration-N \ --skill-name "my-skill" \ --benchmark <workspace>/iteration-N/benchmark.json \ > /dev/null 2>&1 & VIEWER_PID=$! ``` 对于第二次及以后的迭代，额外传入 `--previous-workspace <workspace>/iteration-<N-1>`。 **无头/远程环境**：如果 `webbrowser.open()` 不可用或环境没有显示器，使用 `--static <output_path>` 生成独立 HTML 文件而非启动服务器。当用户点击"提交所有反馈"时，反馈会作为 `feedback.json` 文件下载。 5. **告诉用户**："我已经在浏览器中打开了结果。有两个标签页——'输出'让你可以逐个点击并留下反馈，'基准'显示定量对比。完成后回到这里告诉我。" ### 用户在查看器中看到的内容 "输出"标签页每次显示一个测试用例： - **提示词**：给定的任务 - **输出**：技能生成的文件，尽可能内联渲染 - **之前的输出**（第二次及以上迭代）：折叠区域，显示上一次迭代的输出 - **正式评分**（如果运行了评分）：折叠区域，显示断言通过/失败 - **反馈**：文本框，输入时自动保存 - **之前的反馈**（第二次及以上迭代）：他们上次的评论，显示在文本框下方 "基准"标签页显示统计汇总：每种配置的通过率、计时和 token 使用情况，以及每个评估的详细分解和分析师观察。 使用上一个/下一个按钮或箭头键导航。完成后，点击"提交所有反馈"将所有反馈保存到 `feedback.json`。 ### 第五步：读取反馈 当用户告诉你他们已经完成时，读取 `feedback.json`： ```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" } ``` 空反馈意味着用户认为没问题。将改进集中在用户有具体抱怨的测试用例上。 完成后杀掉查看器服务器： ```bash kill $VIEWER_PID 2>/dev/null ``` --- ## 改进技能 这是迭代循环的核心。你已经运行了测试用例，用户已经审查了结果，现在你需要根据他们的反馈来改进技能。 ### 如何思考改进 1. **从反馈中归纳。** 大图景是：我们正在尝试创建可以被使用一百万次（甚至更多）的技能，覆盖许多不同的提示词。在这里，你和用户反复迭代少数几个例子，因为这样推进更快。用户对这些例子了如指掌，能快速评估新输出。但如果你和用户共同开发的技能只对这些例子有效，那就没用了。与其做零碎的过度拟合修改，或施加压迫性的"必须"，不如尝试使用不同的隐喻或推荐不同的工作模式。尝试的成本很低，也许你会找到更好的方案。 2. **保持提示词简洁。** 删除那些没有贡献的内容。确保阅读对话记录，而不仅仅是最终输出——如果技能让模型浪费大量时间做无产出的事情，试着删除导致这种情况的技能部分，看看会发生什么。 3. **解释为什么。** 努力解释你要求模型做每一件事的**为什么**。今天的 LLM 非常聪明。它们有良好的心智理论，在合理的框架下可以超越机械的指令，真正把事情做成。即使用户的反馈简短或带有挫败感，尝试真正理解任务，理解用户写下的内容背后的原因，然后将这种理解传达给指令。如果你发现自己写了全大写的"ALWAYS"或"NEVER"，或者使用了超级僵化的结构，这是一个黄旗——如果可能，重新构建并解释原因，让模型理解你要求的事情为什么重要。这是一种更人性化、更有力、更有效的方法。 4. **留意测试用例之间的重复工作。** 阅读测试运行的对话记录，注意多个子代理是否独立编写了类似的辅助脚本，或者采取了相同的多步骤方法。如果 3 个测试用例都导致子代理写了 `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` 了解详情。基本思路是：将两个输出交给一个独立代理，不告诉它哪个是哪个，让它评判质量。然后分析胜出者为什么胜出。 这是可选的，需要子代理，大多数用户不需要。人工审查循环通常就足够了。 --- ## 描述优化 SKILL.md 前置元数据中的 description 字段是决定 Claude 是否调用技能的主要机制。创建或改进技能后，主动提议优化描述以提高触发准确性。 ### 第一步：生成触发评估查询 创建 20 个评估查询——混合应触发和不应触发的场景。保存为 JSON： ```json [ {"query": "用户的提示词", "should_trigger": true}, {"query": "另一个提示词", "should_trigger": false} ] ``` 查询必须是真实的，是 Claude Code 或 Claude.ai 用户会实际输入的内容。不要使用抽象的请求，而应该是具体且有一定细节的请求。例如，文件路径、关于用户工作或情况的个人背景、列名和值、公司名称、URL。一些简短的背景故事。有些可能是小写的，或包含缩写、拼写错误或口语化表达。混合使用不同长度，重点关注边缘情况。 **应触发**的查询（8-10 个），考虑覆盖率。你需要不同措辞的同一意图——有些正式，有些随意。包括用户没有明确说出技能名称但明显需要它的情况。加入一些不常见的用例，以及这个技能与另一个技能竞争但应该胜出的情况。 **不应触发**的查询（8-10 个），最有价值的是"近失"情况——与技能共享关键词或概念但实际上需要不同技能的查询。考虑相邻领域、模糊措辞（关键词匹配会触发但实际上不应该）、以及查询涉及技能能做但在上下文中其他工具更合适的情况。 要避免的关键点是：不要让不应触发的查询明显不相关。"写一个斐波那契函数"作为 PDF 技能的负测试太容易了——它测试不了什么。负例应该是真正有迷惑性的。 ### 第二步：与用户一起审查 使用 HTML 模板向用户展示评估集以供审查： 1. 从 `assets/eval_review.html` 读取模板 2. 替换占位符： - `__EVAL_DATA_PLACEHOLDER__` → JSON 格式的评估项数组（不要加引号） - `__SKILL_NAME_PLACEHOLDER__` → 技能名称 - `__SKILL_DESCRIPTION_PLACEHOLDER__` → 技能的当前描述 3. 写入临时文件（如 `/tmp/eval_review_<skill-name>.html`）并打开 4. 用户可以编辑查询、切换应触发状态、添加/删除条目，然后点击"导出评估集" 5. 文件会下载到 `~/Downloads/eval_set.json` 这一步很重要——糟糕的评估查询会导致糟糕的描述。 ### 第三步：运行优化循环 告诉用户："这需要一些时间——我会在后台运行优化循环并定期检查进度。" 将评估集保存到工作区，然后在后台运行： ```bash python -m scripts.run_loop \ --eval-set <path-to-trigger-eval.json> \ --skill-path <path-to-skill> \ --model <当前会话使用的模型 ID> \ --max-iterations 5 \ --verbose ``` 使用你系统提示中的模型 ID（当前会话使用的那个），这样触发测试与用户实际体验一致。 在运行期间，定期检查输出，向用户更新当前迭代和分数情况。 这会自动处理完整的优化循环。它将评估集分成 60% 训练集和 40% 留出测试集，评估当前描述（每个查询运行 3 次以获得可靠的触发率），然后调用 AI 根据失败情况提出改进建议。它在训练集和测试集上重新评估每个新描述，最多迭代 5 次。完成后，会在浏览器中打开一个 HTML 报告，显示每次迭代的结果，并返回 JSON 格式的 `best_description`——根据测试集分数而不是训练集分数选择，以避免过拟合。 ### 技能触发的工作原理 了解触发机制有助于设计更好的评估查询。技能出现在可用技能列表中，包含名称和描述，Claude 根据描述决定是否查阅技能。需要知道的是，Claude 只为它不能轻易独立处理的任务查阅技能——简单的一步查询（如"读取这个 PDF"）可能不会触发技能，即使描述完美匹配，因为 Claude 可以直接用基本工具处理。复杂、多步或专业化的查询会在描述匹配时可靠地触发技能。 这意味着你的评估查询应该足够充实，让 Claude 能从中受益。简单的查询（如"读取文件 X"）是糟糕的测试用例——无论描述质量如何，它们都不会触发技能。 ### 第四步：应用结果 从 JSON 输出中取 `best_description` 并更新技能的 SKILL.md 前置元数据。向用户展示前后对比并报告分数。 --- ## 打包和交付 检查你是否有访问打包工具的权限。如果有，打包技能并向用户展示技能文件路径。 ```bash python -m scripts.package_skill <path/to/skill-folder> ``` 打包后，将生成的技能文件路径告知用户，以便他们安装。 --- ## 更新现有技能 用户可能要求你更新现有技能，而非创建新技能。此时： - **保留原始名称。** 注意技能目录名和 `name` 前置字段——保持不变。例如，如果已安装的技能是 `research-helper`，输出 `research-helper.skill`（而不是 `research-helper-v2`）。 - **复制到可写位置后再编辑。** 已安装的技能路径可能是只读的。复制到 `/tmp/skill-name/`，在那里编辑，并从副本打包。 - **如果手动打包，先在 `/tmp/` 中准备**，然后复制到输出目录——直接写入可能因权限而失败。 --- ## 参考文件 agents/ 目录包含专门子代理的指令。当你需要启动相关子代理时读取它们。 - `agents/grader.md` —— 如何评估断言与输出 - `agents/comparator.md` —— 如何进行盲测 A/B 对比 - `agents/analyzer.md` —— 如何分析一个版本为什么胜过另一个 references/ 目录有更多文档： - `references/schemas.md` —— evals.json、grading.json 等的 JSON 结构 --- 再次强调核心循环： - 确定技能是关于什么的 - 起草或编辑技能 - 让拥有该技能的 Claude 在测试提示词上运行 - 与用户一起评估输出： - 创建 benchmark.json 并运行 `eval-viewer/generate_review.py` 帮助用户审查 - 运行定量评估 - 重复直到你和用户都满意 - 打包最终技能并交付给用户 请在任务清单中添加步骤，确保你不会忘记。确保将"创建 evals JSON 并运行 eval-viewer/generate_review.py 让用户审查测试用例"放入任务清单中。 祝你好运！