Skill Crafter

SKILL.md

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

# Skill Crafter

创建、修改和优化 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：编写技能

### 初始化

```bash
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. 最后说不适用的边界

**正确示例：**

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

**错误示例：**

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

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

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

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

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

**正确示例：**

```markdown
## 概述

封装 WeSpy 的完整能力。

### 功能范围

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

**错误示例：**

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

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

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

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

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

**正确示例：**

```markdown
## 使用

脚本位置：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 直接对号入座——用户需求匹配哪个场景，就用哪条命令。不需要自己拼。

**错误示例：**

```markdown
## 参数说明
- 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 行 |

### 注册

```bash
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` — 迭代改进指南（症状诊断、修复流程、沉淀机制）