skill-creator-cn

Skill Creator

语言与水平指令

默认用中文与用户交流，跟随用户的语言切换（用户改用英文则跟着切换）。

全程自动识别用户的技术水平，不要打断流程询问"你是什么水平"——通过用户的措辞、上下文自动判断，并相应调整用词深度：

• 用户说"我不懂代码""帮我做一个自动化"→ 用日常语言，避免裸露的 JSON/assertion/eval 等术语（或用时简要解释）。
• 用户说"写个 SKILL.md""跑 eval"→ 可直接使用技术术语。
• 中间态：术语按需解释，不过度科普也不假设对方都懂。

详细的水平信号识别与提问节奏，见 references/需求共创.md。

---

① 前置 Triage（闸门）

在进入任何创建/改进流程之前，先做三个快速判断：

1. 这要不要做成 skill？

判断标准：

• 一次性任务：用户只要做一次，做完就不用了 → 直接帮做，不必做成 skill。
• 普通 prompt 够用：Claude 不需要任何 skill 也能胜任 → 直说，不必做 skill。
• Claude 原生能干：内置能力已覆盖，skill 不会带来额外价值 → 坦诚建议不必做。
• 更适合 slash command 或 subagent：任务是一次性调度或编排多个步骤，而非可复用流程 → 说明区别，建议替代方案。

命中后怎么做：坦诚告诉用户"这种情况不一定需要做成 skill，因为……"，并提供直接帮助或替代建议。

2. 有没有现成类似的？

判断方法：扫一眼用户环境里已有的 skills 列表（available_skills），看有没有功能高度重叠的。

命中后怎么做：告知用户已有类似 skill，建议先试用，或在现有 skill 上改进，而非重新造轮子。

3. 范围太大？

判断标准：用户描述的需求实际上涵盖了多个独立的、可拆分的工作流程。

命中后怎么做：提醒用户"这其实是好几个 skill，建议拆开来做"，本工具不会自动批量生成多套 skill，每次聚焦一个。

---

② 入口识别与路由

通过用户的描述，判断属于哪个入口，然后跳转对应分支：

入口	用户大概这样说	跳转
E1 模糊想法	"我想做个 skill""帮我自动化 XX""我有个想法但不知道怎么做"	→ references/需求共创.md
E2 从对话提取	"把我们刚才做的变成 skill""提取这个流程""这次对话做成 skill"	→ references/需求共创.md（从 transcript 抽步骤/工具/纠正 → 回填四要素）
E3 现有材料	"我有个文档/流程图/SOP""给你几对输入输出示例，照着做""参考这个来做 skill"	→ references/需求共创.md（分析材料/示例 → 提炼四要素 → 补缺）
E4 已有草稿	"我写了个 SKILL.md 草稿""帮我完善这个 skill"	→ references/需求共创.md（读懂草稿 → 补缺 → 进打磨循环）
E5 改进/调试	"这个 skill 不触发""触发错了""效果跑偏""太慢太重"	→ references/改进调试.md

E1/E2/E3/E4 均路由到 references/需求共创.md，按各自情境执行对应段落。E5 路由到 references/改进调试.md，按诊断 playbook 执行。

---

创建流程地图（全局视图）

以下是整体流程的全局视图，确保你在每个阶段都知道"下一步去哪"：

① 前置 Triage（闸门）
   · 这要不要做成 skill？ → 一次性/普通 prompt 够/Claude 原生能干/
                            更适合 slash command·subagent → 直说不必
   · 有没有现成类似的？   → 扫一眼已有 skills，别重复造
   · 范围太大？          → 提醒"这其实是好几个 skill"
        │
        ▼
② 识别入口，跳对应分支（两类，分别走不同路）
   ▸ 创建类 E1 模糊想法 / E2 从对话 / E3 现有材料 / E4 已有草稿
        └─→ references/需求共创.md（四要素 / 水平信号 / 材料·输入输出例子分析）
                 │ 四要素挖掘完
                 ▼
            ✦ 确认门：把四要素回述给用户、获批才开写（见 需求共创.md 第六节）──┐
   ▸ 改进类 E5 改进/调试                                                        │
        └─→ references/改进调试.md（诊断：不触发/行为跑偏/过欠触发/太重；不经确认门）─┤
                                                                                 ▼
③ 共有打磨循环（见下文"起草 SKILL.md"及后续章节）
   起草 SKILL.md（含 description；顺带确认 依赖/工具/MCP 可用性）
   → 验证【分层：轻量"跑给你看"默认 / 重型量化评测可选】
   → 看结果 → 改 → 重跑 → 满意为止 → 打磨 description 触发
        │
        ▼
④ 最后一公里 → references/最后一公里.md（放哪/确认装上/自测触发/打包）

---

③ 共有打磨循环：起草、验证与迭代

起草 SKILL.md

根据需求共创的结果，填写以下几个核心部分：

• name：skill 的标识符，保持简洁。
• description：这是触发机制——写清楚"什么时候用、做什么"。把所有"何时使用"的信息都放在这里，不要藏在正文里。注意：Claude 有时会"触发不足"（明明适合用却没用），所以描述可以稍微主动一点。比如，别只写"如何构建仪表盘"，而是写"构建仪表盘。当用户提到仪表盘、数据可视化、内部指标、想展示任何公司数据时，即使没有明确说'仪表盘'，也应使用本 skill。"
• compatibility：所需工具、依赖（可选，大多数 skill 不需要）。
• 正文：其余的 skill 说明。

skill 的结构

skill-name/
├── SKILL.md（必须）
│   ├── YAML frontmatter（name、description 必填）
│   └── Markdown 说明
└── 捆绑资源（可选）
    ├── scripts/    - 确定性/重复性任务的可执行代码
    ├── references/ - 按需加载到上下文的文档
    └── assets/     - 输出中用到的文件（模板、图标、字体）

渐进加载机制

Skill 有三级加载层：

1. 元数据（name + description）——始终在上下文中（约 100 词）
2. SKILL.md 正文——skill 触发时进入上下文（理想 <500 行）
3. 捆绑资源——按需加载（不限大小，scripts 可直接执行无需加载）

关键原则：

• SKILL.md 尽量控制在 500 行以内；接近上限时，增加一层层级并写清楚"下一步去哪里"的指引。
• 在 SKILL.md 中明确引用 reference 文件，注明何时读取。
• reference 文件超过 300 行时，加目录索引。

多领域 skill 按变体组织：

cloud-deploy/
├── SKILL.md（流程 + 选择逻辑）
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

Claude 只读取相关的 reference 文件。

内容安全

Skill 不得包含恶意代码、漏洞利用代码或任何可能损害系统安全的内容。Skill 的内容不应在描述说明的范围之外给用户带来意外。不要配合制作带有误导性、旨在未授权访问或数据泄露的 skill。角色扮演类需求（如"扮演某个角色"）通常没问题。

写作风格

用祈使句写指令，这样模型更容易执行。

尽量说明"为什么"而不是堆砌 MUST/NEVER 等强制词——当今的 LLM 相当聪明，理解了背后的理由反而比死规定更灵活有效。用心揣摩用户真正想要什么，写出的 skill 要足够通用，不要只针对几个具体例子过拟合。

写完初稿之后，换个视角重读一遍再改——这一步经常能发现自己没意识到的问题。

输出格式示例：

## 报告结构
始终使用以下模板：
# [标题]
## 执行摘要
## 关键发现
## 建议

**示例模式——**在 skill 里放例子很有用：

## commit 消息格式
示例：
输入：Added user authentication with JWT tokens
输出：feat(auth): implement JWT-based authentication

草稿自检

写完初稿，换个视角重读一遍再交给验证——重点扫四件事：

• 占位与含糊："TBD""按需处理""适当地……"这类没说清的要求，说清它。
• 自相矛盾：前后指令、description 与正文有没有打架。
• 范围蔓延：有没有混进需求里没确认过的功能？砍掉，或回去确认。
• 歧义：某条要求会不会被理解成两种意思？挑一种、写明确。

发现问题就地改掉，不必反复评审。

---

分层验证：默认轻量，进阶可选

验证的目的是确认 skill 的行为是否符合用户预期。根据用户的技术水平和需求，有两条路：

默认：轻量"跑给你看"

起草完 skill 之后，设计 2–3 个真实用户会说出的测试提示词，和用户确认："这几个测试用例看起来对吗？有想加的吗？" 然后直接运行，把产出展示给用户看，问"这样对吗？"

这条路零术语、零 JSON——用户看到真实结果，给出直觉反馈，就可以进入下一轮改进。

保存测试用例到 evals/evals.json（只保存 prompt，assertion 留给进阶阶段）：

{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "用户实际会说的任务描述",
      "expected_output": "期望结果的简要描述",
      "files": []
    }
  ]
}

完整 schema（含 assertions 字段）见 references/schemas.md。

进阶 · 可选：重型量化评测

需要严格的量化对比（benchmark/assertion，跨版本比较）时，读 references/重型评测.md 的「重型量化评测」一节。默认绝不把 JSON assertion、benchmark 等概念主动抛给初学用户。

---

改进 skill

这是循环的核心。你已经跑完测试用例，用户已经看过结果，现在根据反馈改进 skill。

怎么思考改进方向：

• 从反馈里归纳共性。我们在做的事情是：创建一个能被用一百万次的 skill，而现在只是在几个例子上快速迭代。如果改出来的 skill 只对这几个例子有效，就失去了意义。遇到顽固问题，与其加死规定，不如换个比喻或换种工作模式——代价低，说不定能找到更好的方案。

• 保持 prompt 精简。去掉没有实际作用的内容。读运行的完整对话记录（transcript），不要只看最终输出——如果 skill 让模型做了很多无效工作，试着删掉导致这些行为的指令，看看结果是否更好。

• 解释"为什么"。尽量说明你要求模型做某件事背后的理由。今天的 LLM 很聪明，给出了充分理由，它们能举一反三、灵活应对，效果往往比死规定更好。如果你发现自己在写"ALWAYS"或"NEVER"这样的全大写词，那是一个警示信号——尝试改写成解释理由的方式。

• 发现跨用例的重复工作。读各测试用例的运行记录，看看子代理有没有各自独立写了类似的辅助脚本（比如 3 个用例都写了 create_docx.py）。如果有，这是强信号：把这个脚本写好放进 scripts/，让 skill 直接调用，省去每次重新造轮子。

改进后，按你当前走的验证档重跑（别无脑上重型）：

1. 应用改动到 skill
2. 重新验证：
   • 轻量档（默认）：重跑那 2–3 个测试提示词，把新产出摆给用户看，问"这版好点了吗？"——不建目录、不跑 baseline。
   • 重型档（进阶）：跑全部测试用例放入新的 iteration-<N+1>/ 目录（含 baseline run），启动 eval viewer（eval-viewer/generate_review.py）并加 --previous-workspace 指向上一轮——细节见 references/重型评测.md。
3. 等用户看完反馈
4. 读新反馈，再改，循环

直到：用户说满意、反馈全为空、或已经没有实质进展，停止循环。

---

进阶 · 可选：盲评对比

需要更严格地对比两个版本的 skill 时（例如"新版本真的更好吗"），读 references/重型评测.md 的「盲评对比」一节。

---

Description 触发优化

description 字段是 Claude 决定是否调用 skill 的核心机制——它决定 skill 会不会被调用。skill 整体打磨满意后，可以主动提出优化 description 以提升触发准确率。优化时会生成触发评测查询集、让用户确认，然后用 scripts/run_loop.py 在后台跑优化循环，自动选出最优 description。

详细流程见 references/重型评测.md 的「Description 触发优化」一节。

---

打包发布

检查是否有 present_files 工具可用。有则打包 skill 并发给用户；没有则跳过。

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

打包后，告知用户 .skill 文件的路径。

---

平台差异说明

Claude.ai

核心流程相同（起草 → 测试 → 审阅 → 改进 → 重复），但 Claude.ai 没有子代理，部分机制需要调整：

• 跑测试用例：不能并发，逐条执行。读 skill 的 SKILL.md，按其指令自己完成测试任务。这不如独立子代理严格（你既写了 skill 又在运行它），但作为合理性检查是有效的——人工审阅可以弥补。跳过 baseline run，只跑带 skill 的版本。
• 展示结果：如果无法打开浏览器，直接在对话里展示。每个用例显示 prompt 和输出；如果输出是文件（.docx、.xlsx），告知文件位置让用户下载查看；内联征求反馈："这样看起来怎么样？有什么想改的？"
• 量化评测：跳过——没有子代理就无法做有意义的 baseline 对比。以用户的定性反馈为准。
• Description 优化：需要 claude -p（仅 Claude Code 可用），Claude.ai 上跳过。
• 盲评对比：需要子代理，跳过。
• 打包：scripts/package_skill.py 只需 Python 和文件系统，在 Claude.ai 上可用。用户可下载生成的 .skill 文件。
• 更新已有 skill：保留原始 name（目录名和 frontmatter 的 name 字段不变）；已安装的 skill 路径可能只读，先复制到 /tmp/skill-name/ 再编辑，打包时从副本运行。

Cowork

• 有子代理，主流程（并发测试用例、baseline、评分等）完全可用。遇到严重超时问题可以改串行。
• 没有浏览器/显示器：生成 eval viewer 时用 --static <output_path> 输出独立 HTML 文件，给用户提供可点击的链接。
• Cowork 环境下 Claude 有时会跳过生成 viewer 直接评估输出——请务必在让用户审阅结果之前生成 viewer（用 eval-viewer/generate_review.py，不要自己写 HTML）。把结果第一时间展示给用户，而不是自己先下结论。
• Feedback：没有运行中的服务器，viewer 的"Submit All Reviews"会下载 feedback.json，从那里读取（可能需要先请求访问权限）。
• 打包：scripts/package_skill.py 只需 Python 和文件系统，正常工作。
• Description 优化（scripts/run_loop.py）在 Cowork 下通过 claude -p 子进程运行，不依赖浏览器，应该正常工作；请在 skill 整体完成、用户确认满意后再运行。
• 更新已有 skill：同 Claude.ai 一节的指引。

---

内部文件说明

agents/*.md、scripts/*.py、references/schemas.md 是供本 skill 内部使用的子代理指令、脚本和 schema 定义，保持英文原样；它们输出的自由文本（evidence/reasoning/笔记等）由各 agent 文件自身的语言指令控制（默认跟随用户语言）。

eval-viewer/viewer.html 和 assets/eval_review.html 是用户可见的 UI，已中文化，不属于"内部文件"。同理 scripts/ 里生成用户可见报告的部分（generate_report.py 等）也已中文化；脚本里给开发者看的 print 状态/错误同样已中文化。

• agents/grader.md — 评估 assertion 是否通过
• agents/comparator.md — 对两份输出做盲评 A/B 对比
• agents/analyzer.md — 分析某版本为何胜出
• references/schemas.md — evals.json、grading.json 等的 JSON schema
• references/需求共创.md — 需求挖掘引擎（E1–E4 入口）
• references/改进调试.md — 改进与调试 playbook（E5 入口）
• references/最后一公里.md — 安装、激活、自测、打包
• references/重型评测.md — 重型量化评测、盲评对比、Description 触发优化详细流程（进阶可选）

---

收尾：最后一公里

当 skill 内容打磨满意、description 触发调优完成后，进入 references/最后一公里.md，完成安装激活、自测触发验证和打包发布。