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。

核心检查：

检查项标准frontmattername 为 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 — 迭代改进指南（症状诊断、修复流程、沉淀机制）