skill-creator

name	skill-creator
description	当用户要求创建、编辑、优化或评估 skill，讨论 skill 格式、触发条件，或验证技能效果时使用。
metadata	{"openclaw":{"emoji":"🛠️"}}

skill-creator — 技能创建与优化技能

执行前置

遵循当前目录 AGENTS.md「技能执行公共契约」；仅按需读取技能正文与 reference。

创建新 skill 并迭代改进：意图捕获 → 草稿 → 测试用例 → 用户评估 → 重写循环 → 触发描述优化。设计原则源自 Anthropic 官方 skill-creator 与 Agent Skills 规范。

核心原则

1. 先捕获意图，不臆断：新 skill 做什么、何时触发、输出格式、是否需测试用例， 四项缺项先提问确认——所有问题在第一次交互一次性全部提出（编号列表），用户一次回答，不逐次追问。
2. 触发描述是核心（SDO，见 obra/superpowers writing-skills）：frontmatter 的 description 是技能触发的唯一机制； 必须只写触发条件（用户常说的词/场景），不总结工作流——总结流程的描述会让 agent 按描述 shortcut 跳过正文（SDO 实测）； 并适度"pushy"（Claude 倾向于少触发，描述要主动提示适用场景）。 Bad/Good 对比（源自 writing-skills SDO）：

   # ❌ BAD: 总结工作流 — agent 可能照描述执行而跳过正文流程图
   description: Use when executing plans - dispatches subagent per task with code review between tasks
   # ✅ GOOD: 仅触发条件，不含流程
   description: Use when executing implementation plans with independent tasks
   

   措辞微测试（micro-test wording，源自 writing-skills）要求：每个指令变体新上下文单样本 + 无指令对照 + 每变体≥5次重复 + 逐条人工阅读命中；方差是信号——5次收敛同一形状说明措辞有效，5种解释说明措辞未约束行为。
3. 分级披露（progressive disclosure）：SKILL.md 保持精简（理想 <500 行）； 过长内容拆到 references/ 并按需读取；脚本放 scripts/（可执行、确定性任务）； 资源放 assets/。
4. 解释 why，而非堆 MUST：用"为什么这样做"的说明替代全大写 MUST/NEVER； 硬性规则是黄旗——优先讲清理由让模型真正理解。 规则形式必须匹配失败类型（吸收 superpowers writing-skills "Match the Form to the Failure"）： 明知故犯型失败（知道规则但压力下跳过）→ 禁止式 + 合理化借口表 + 红旗清单； 输出形状型失败（缺部件/结构错）→ 正配方（规定输出"是什么"——组成部分与顺序）； 禁止式对形状类失败适得其反（agent 会与"不要 X"谈判，产出更差），配方无可谈判； 任何规则不加"除非"从句（豁免从句会被绕开，真实例外写成基于可观察条件的独立规则）。
5. 证据驱动评估：用测试用例 + 有/无技能对照评估技能效果；结论以实测为准。
6. 循环迭代直至满意：评估反馈 → 重写 → 复测，循环直至用户满意或收益微小。
7. 格式一致性：新/改 skill 遵循本目录既有格式规范（frontmatter + 正文结构 + 目录 AGENTS.md），保持与已有 skill 风格统一。
8. 意外最小化（Lack of Surprise）：skill 不得包含恶意/越权/误导性内容； 意图表述与内容一致，不协助创建用于未授权访问、数据外泄等恶意用途的技能。

触发时机

• 用户要求创建技能："创建skill"、"写一个技能"、"做一个小技能"、"技能怎么写"
• 用户要求优化技能："优化skill"、"改进技能"、"skill没触发"、"技能格式规范"
• 用户要求评估技能："评估技能"、"技能测试"、"验证skill效果"
• 与其他技能配合：生成技能后归集/归档用 init 技能；性能问题用 optim 技能； 技能触发/行为异常用 debug 技能

工作流程

Step 1. 捕获意图（先问对问题）

1. 这个技能要让 agent 做什么？（核心能力）
2. 何时触发？（用户会说什么词/出现什么场景——写入 description）
3. 预期输出格式？（文件、报告、代码、行为变化）
4. 是否需要测试用例？（输出可客观验证的（文件转换/数据提取/固定流程）建议测试； 主观输出（写作风格/艺术）通常不需要，由用户决定）

从会话历史提取已有信息（用户可能已展示过想固化的流程），缺项在第一次交互一次性全部列出提问确认。

Step 2. 调研与参考（网络最佳实践）

• 调研相关最佳实践：本目录既有 skill 的格式规范、Anthropic 官方 anthropics/skills 仓库（skill-creator/template）、社区 obra/superpowers 等；
• 参考同类 skill 的写法（描述、结构、粒度），注明借鉴来源；
• 结合用户项目实际（语言、工具链、设备、精度需求）定制，不照搬。

Step 3. 编写 SKILL.md

按既有格式规范编写：

---
name: <skill-name>            # 小写、连字符分隔；与目录名一致
description: |
  <做什么>。<何时使用>：列出用户典型说法的触发词与场景（写"pushy"些）。
metadata:
  openclaw:
    emoji: <图标>
---

# <skill-name> — <中文名>

## 核心原则        # 5-9 条，解释 why
## 执行前置        # 引用 AGENTS.md 公共契约；不重复公共规则
## 触发时机
## 工作流程        # Step 1..N，命令给出确切可执行示例
## 错误处理        # 表格：场景 → 处理
## 注意事项

• 长度：保持精简（<500 行）；超长时拆 references/（如分场景的长指令、大表格）； 从 SKILL.md 明确指引"何时读取哪个 reference"；
• 命令示例必须真实可执行；指令用祈使句；
• 保留本目录既有 skill 的公共约定：文件:行号 引用、证据驱动；过程只在终端输出。

Step 4. 测试与评估

1. 写 2-3 个真实用户口吻的测试提示词（"试试这个……""帮我……"），与用户确认； 测试提示词必须实质化（吸收官方 skill-creator 触发机制理解）：技能只在任务 复杂到模型无法轻易处理时触发——单步简单查询（"读这个文件""算 2+2"）即使描述 完全匹配也可能不触发；测试用例要具体（文件路径/数值/上下文/多步骤）， 简单查询是差的测试用例，会低估触发率；
2. 有/无技能对照运行（新建：无技能基线；优化：旧版本基线）：
   • 用旧版本快照 cp -r <skill-path> <工作区>/skill-snapshot/ 作为基线；
   • 组织结果到工作区：<skill-name>-workspace/iteration-<N>/eval-<ID>/with_skill|without_skill|old_skill/outputs/；
   • 同回合并行启动全部有/无技能运行，不先跑完一边再跑另一边；每次运行完成立即 保存 timing.json（total_tokens/duration_ms——只出现在任务完成通知里，错过不补）；
   • 运行期间起草断言（客观可验证、命名有描述性），断言可脚本化判断的写脚本而非人眼；
3. 收集定性反馈（用户审阅输出）与定量指标（测试项通过率、耗时、token 数）；
4. 措辞微测试（吸收 writing-skills micro-test wording，面向行为塑造类指令）：
   • 每个指令变体用新上下文单样本运行（系统提示=该指令真实所在环境），并必须带 "无指令对照"——对照组不表现出失败则说明无需该指令，停止编写；
   • 每变体 ≥5 次重复，单次结果不可信；方差是指标——多次重复收敛同一形状说明指令 有效，5 种不同解释说明措辞不约束行为，先收紧措辞再考虑加字；
   • 命中结果逐条人工阅读（模板回显/引用反例会伪装成命中，自动计数会高估成败）；
   • 微测试只验证措辞，纪律型技能的最终闸门仍是完整压力场景试跑；
5. 汇总后做 analyst pass（吸收 anthropics/skills skill-creator）：读基准数据找 聚合统计掩盖的模式——无技能也通过的断言（非判别性，删之）、高方差评估项（可能不稳定）、 时间/token 权衡；把结论写进结果说明，不只给数字；
6. 跨测试用例找重复工作：若多个测试的 agent 都独立写了同类辅助脚本/重复多步操作 （如都写了 create_docx.py），把该脚本打包进本技能 scripts/ 并让技能引用它—— 省去每次调用重新发明轮子；
7. 依据反馈重写 → 复测，循环直至用户满意、反馈全为空或不再有实质进展；
8. 盲比较（可选进阶）：用户要求严格对比新旧版本时，把两份输出交给独立的第三方 agent（不告知哪个是哪个）评判质量，再分析胜因；通常人工审阅循环已足够。

Step 5. 触发描述优化

1. 生成 20 条触发评估查询（应触发 8-10 条 + 不应触发 8-10 条）， 应触发覆盖不同措辞（正式/口语）与未显式点名技能的场景；不应触发选 "近似误触发"（共享关键词但实际需要别的技能）；
2. 与用户确认查询集，评估当前 description 触发率；
3. 根据失败样例优化 description（补充触发词/场景），复测对比；
4. 更新 frontmatter，向用户展示前后对比。

结构化评估产物（吸收官方 skill-creator 最新版，有脚本环境时落地；无脚本环境 简化为文件记录）：评估数据按规范落盘，保证可复现与跨轮对比——

• evals/evals.json：测试用例集 {"skill_name": ..., "evals": [{"id", "prompt", "expected_output", "files", "assertions"}]}（断言字段后补）；
• 每轮运行目录 eval-<id>/ 下：eval_metadata.json（eval_id/eval_name/prompt/ assertions——断言客观可验证、命名有描述性）、timing.json（total_tokens/ duration_ms——只在任务完成通知中出现，错过不补）、grading.json（断言评分， 字段必须是 text/passed/evidence，viewer 依赖）；
• 聚合 benchmark.json/benchmark.md（pass_rate + 时间/token 的 mean±stddev 与 delta）；聚合统计掩盖的模式由 analyst pass 揭示。

优化循环（吸收官方 skill-creator Description Optimization，有脚本环境时）：

• 查询集按 60% 训练 / 40% 留出测试 拆分；每条查询重复 3 次取可靠触发率 （单次结果不可信）；
• 候选 description 在训练集与留出集上分别评估，按留出集得分选最优 （防对训练集过拟合）；
• 迭代上限 5 轮，每轮由失败样例驱动改进；最终 best_description 写入 frontmatter 并展示前后对比与得分。

Step 6. 总结（结构化输出）

✓ skill 创建/优化完成
   对象:   <skill 名称与位置>
   参考:   <借鉴的网络来源，如 anthropics/skills skill-creator>
   测试:   <N 个测试用例，有/无技能对比结果>
   optim:  <描述触发率 基线→优化后，无则省略>
   改动:   <新建/修改文件清单>

   遗留:   <未处理项，无则省略>

错误处理

场景	处理
意图不明确	按四项清单一次性全部列出提问，不逐次追问
与已有技能职责重叠	指出重叠，建议合并/引用或明确边界
SKILL.md 过长	拆 references/，SKILL.md 保留指引与核心流程
测试无客观输出	用定性用户评估替代断言
描述触发率低	检查触发词覆盖与"pushy"程度，补常见场景措辞
用户反馈空	视为满意，停止迭代

注意事项

• 不编造参考来源与测试数据；借鉴网络实践需注明出处；
• 新技能必须附目录 AGENTS.md（3-7 行说明），并更新上级 skills/AGENTS.md 技能表；