Skill Crafter

创建高质量 Skill 的技能。当用户说"创建技能""新建 Skill""把这个流程变成技能""做一个 XX 的 skill""帮我写个技能"时触发。不适用于使用已有技能执行任务——那是 use_skill 的工作。

创建、修改和优化 Skill。核心方法：四层骨架 + 四阶段流程。

你的工作方式

1. Phase 1：需求理解 — 吃透用户已说的，推断能补全的，只追问真正缺失的
2. Phase 2：编写技能 — 用 init_skill.py 初始化，按 Phase 1→2 映射规则填充四层骨架
3. Phase 3：质量验证 + 注册 — 逐层检查，修复问题，上传注册
4. Phase 4：迭代改进 — 根据使用症状诊断问题，精确修复，沉淀踩坑经验

修改已有技能时：定位 → 读取 → 用 file_edit 精确修改 → 回归检查 → 重新注册。

---

Phase 1：需求理解

用户开口时已经带了大量信息。先吃透已说的，再推断能补全的，只追问真正缺失的。

信息获取优先级

1. 对话历史优先：用户刚完成一个任务说"把刚才的做成技能"，从对话历史提取工作流——用什么工具、执行什么步骤、用户做了什么修正、输入输出是什么。这种情况下通常不需要追问。
2. 用户描述中提取：用户说"帮我创建公众号长文的 skill，我是 AI 行业的"，已经包含技能目标、领域、输出形式。
3. 合理推断：从技能类型可以推断大部分细节，把推断整理好一次性让用户确认。

只问用户需求

聚焦于"这个技能要帮你做什么"。触发短语怎么写、description 怎么组织——这些是你的工作，不要让用户操心。

一轮对齐

最多追问一轮。整理你对技能的理解为简洁摘要，附上少量需要用户决定的选项，一次性发出。用户确认后直接进入 Phase 2。

---

Phase 2：编写技能

初始化

python3 /sandbox/workspace/skills/skill-crafter/scripts/init_skill.py {name}

脚本会生成目录骨架和四层结构的 SKILL.md 模板。根据需要替换或删除示例文件，删除不需要的空目录。

Phase 1→2 映射

需求理解产出的每条信息，对应四层骨架的特定位置。不要猜，按映射表填充：

详细映射规则见 references/phase-mapping.md

核心映射：

Phase 1 产出	落到哪一层
技能目标 + 触发短语 + 不适用边界	头部 description
能力范围 + 一句话定位	概述
典型场景 + 操作步骤 + 输出格式	操作指南
依赖条件 + 已知坑点 + 冲突处理	补充说明

完整案例见 references/example-complete.md——一个从第一行到最后一行用四层骨架写好的真实 Skill。

四层骨架

SKILL.md 由四层组成，Agent 读取时分层递进。每一层写错了，后面的效果就会打折。

第一层：头部（description）——触发器，不是摘要

description 决定 Agent 会不会选用这个 Skill。绝大多数 Skill 在这一步就被跳过了。

写法：

1. 第一句说这个 Skill 做什么
2. 中间写 Use when user asks to + 用户可能说的触发短语（多种表达方式）
3. 最后说不适用的边界

正确示例：

description: 获取并转换微信公众号文章为Markdown的封装Skill。
  Use when user asks to 抓取微信公众号文章、抓微信、
  下载公众号文章、URL转Markdown、微信文章保存.
  不适用于通用网页抓取或非微信内容.

错误示例：

description: WeSpy的封装，支持微信公众号文章抓取和专辑批量下载。

问题：缺少触发词。用户说"帮我抓一下这篇微信文章"，Agent 看着这个 description 不确定该不该用——因为没有"抓取微信文章"这种用户会说的表达。

关键原则： Use when user asks to 不是注释，是给 Agent 的匹配信号。它后面的词就是触发条件。

第二层：概述——画边界，不画地图

概述 = 一句话定位 + 功能范围列表。只列"能做什么"，不写"怎么做"。

正确示例：

## 概述

封装 WeSpy 的完整能力。

### 功能范围

- 单篇文章抓取（微信公众号 / 通用网页 / 掘金）
- 微信专辑文章列表获取
- 微信专辑批量下载
- 多格式输出（Markdown / HTML / JSON）

错误示例：

## 功能范围
- 单篇文章抓取，使用 python3 scripts/wespy_cli.py URL 命令
- 微信专辑文章列表获取，加上 --album-only 参数

问题：把操作细节塞进功能范围。Agent 还没决定要不要用你呢，你就让它看命令行了？"能做什么"归概述，"怎么做"归操作指南。

第三层：操作指南——给场景，不只是给命令

Agent 在这一层逗留时间最长——这是它真正执行任务时参照的内容。

按场景给示例，不要按参数给说明。

正确示例：

## 使用

脚本位置：scripts/wespy_cli.py

# 单篇文章抓取
python3 scripts/wespy_cli.py "https://mp.weixin.qq.com/s/xxxxx"

# 专辑批量下载（下载前20篇）
python3 scripts/wespy_cli.py "https://mp.weixin.qq.com/mp/appmsgalbum?..." --max-articles 20

# 仅获取专辑文章列表（不下载）
python3 scripts/wespy_cli.py "URL" --album-only

Agent 直接对号入座——用户需求匹配哪个场景，就用哪条命令。不需要自己拼。

错误示例：

## 参数说明
- URL：文章或专辑的链接
- --album-only：仅获取专辑列表
- --max-articles N：批量下载时指定数量

命令：python3 scripts/wespy_cli.py [URL] [OPTIONS]

问题：Agent 看到通用模板，得自己拼命令。每多一步判断，就多一次出错。

第四层：补充说明——堵死岔路口

Agent 执行中遇到问题来查这一层。覆盖所有"可能走错"的判断点。

需要覆盖的典型场景：

• 依赖不存在怎么办（自动安装？报错？降级方案？）
• 输入格式不对怎么办
• 输出目录不存在怎么办
• 网络超时怎么办
• 同名文件已存在，覆盖还是跳过

每一个踩过的坑，都写进补充说明。 Skill 会随着使用越来越"聪明"，就是因为踩过的坑都沉淀在这里了。

结构模式

四层骨架是组织原则，结构模式是内容模式。根据技能用途选择：

1. 流程型（有明确步骤的工作流）

• 结构：概述 → Phase 1 → Phase 2 → ... → 多轮修改
• 示例：报告生成、数据分析

2. 任务型（多种独立操作，按意图路由）

• 结构：概述 → 决策表 → 操作 1 → 操作 2 → ...
• 示例：知识库管理、文件操作

3. 规范型（标准/规范/指南）

• 结构：概述 → 规范细则 → 检查清单
• 示例：品牌写作规范、代码规范

4. 能力集型（多个关联功能的集成）

• 结构：概述 → 核心能力 → 功能 1 → 功能 2 → ...
• 示例：客服工作台、开发工具链

模式可以混合。大多数技能以一种为主，按需组合。

编写风格

• 解释为什么重要，不堆砌"必须"
• 写场景示例，不写参数说明
• 通用性优先，不局限于特定示例
• SKILL.md 控制在 400 行以内；超出的内容拆入 references/，在正文中说明何时读取

安全原则

技能不得包含恶意软件、攻击代码，或旨在未授权访问、数据窃取的内容。

避免的做法

1. 重复 LLM 已有能力 — 技能提供结构化流程或领域知识，不是"请用优美的语言写作"
2. 引用不存在的工具 — 编写前检查自身工具列表
3. 只说 MUST 不说 WHY — 解释原因让 Agent 能在边界情况自主判断
4. 超长不拆分 — 超过 400 行拆入 references/
5. 没有工作流示例 — 至少 2 个覆盖典型场景的示例
6. 缺少确认门 — 长流程需要有用户确认点
7. description 当摘要写 — 必须含触发词，必须含不适用边界
8. 操作指南只给参数 — 必须按场景给完整示例

---

Phase 3：质量验证 + 注册

质量检查

生成文件后逐项检查，发现问题直接修复，不需要展示给用户。详细检查项见 references/checklist.md。

核心检查：

检查项	标准
frontmatter	name 为 kebab-case ≤64 字符；description 含触发词和不适用边界
TODO 残留	SKILL.md 中无 [TODO 占位符残留
四层完整	头部 → 概述 → 操作指南 → 补充说明，每层都有实质内容
触发词覆盖	description 的触发短语覆盖了用户可能的多种表达
场景示例	操作指南至少 2 个按场景给出的完整示例
兜底方案	补充说明覆盖了依赖缺失和常见错误场景
行数控制	SKILL.md ≤ 400 行

注册

ima_skill_create -d /sandbox/workspace/skills/{name}/

注册完成后告知用户：

技能已提交！审核通过后即可使用。 如果以后想修改，可以说"修改我的 XX 技能"。

---

Phase 4：迭代改进

Skill 很少一次写对。根据使用中的症状诊断问题，精确修复。

详细诊断和修复方法见 references/iteration.md

常见症状速查

症状	可能原因	修复方向
Skill 不触发	description 缺触发词或边界过宽	补充触发短语，缩小不适用边界
触发后出错	命令不可执行、依赖无兜底	修复操作指南，补充依赖兜底方案
输出不稳定	场景示例不足、格式定义模糊	增加场景示例，明确输出格式
Agent 走岔路	概述含糊、缺确认门、缺分支判断	穷举替代"等"，加确认门，补分支规则

修复流程

1. 读取 SKILL.md，定位问题所在层级
2. 用 file_edit 精确修改——只改有问题的层
3. 用精简 checklist 做回归检查
4. 重新注册

沉淀机制

每次修复一个问题，把经验沉淀到补充说明中。补充说明是 Skill 的"踩坑记录"，随使用逐渐丰富。

---

资源目录

scripts/

• init_skill.py — 技能目录初始化脚本，生成四层结构模板

references/

• four-layers.md — 四层骨架写法详解（含正误对比）
• checklist.md — 质量检查清单（按层级分 P0/P1/P2）
• workflows.md — 流程组织模式（与四层骨架对齐）
• output-patterns.md — 输出格式定义（与四层骨架对齐）
• phase-mapping.md — Phase 1→2 映射规则（需求产出对应四层哪一层）
• example-complete.md — 完整真实 Skill 案例（四层骨架从头到尾的写法）
• iteration.md — 迭代改进指南（症状诊断、修复流程、沉淀机制）