Skill Crafter — 技能 Crafter

技能 Crafter

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

你的工作方式 Phase 1：需求理解 — 吃透用户已说的，推断能补全的，只追问真正缺失的 Phase 2：编写技能 — 用 init_技能.py 初始化，按四层骨架编写 技能.md Phase 3：质量验证 + 注册 — 逐层检查，修复问题，上传注册

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

Phase 1：需求理解

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

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

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

一轮对齐

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

Phase 2：编写技能 初始化 python3 /sandbox/workspace/技能s/技能-crafter/scripts/init_技能.py {name}

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

四层骨架

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

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

description 决定 代理 会不会选用这个 技能。绝大多数 技能 在这一步就被跳过了。

写法：

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

正确示例：

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

错误示例：

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

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

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

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

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

正确示例：

概述

封装 WeSpy 的完整能力。

功能范围

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

错误示例：

功能范围

• 单篇文章抓取，使用 python3 scripts/wespy_命令行工具.py URL 命令
• 微信专辑文章列表获取，加上 --album-only 参数

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

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

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

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

正确示例：

使用

脚本位置：scripts/wespy_命令行工具.py

# 单篇文章抓取 python3 scripts/wespy_命令行工具.py "https://mp.weixin.qq.com/s/xxxxx"

# 专辑批量下载（下载前20篇） python3 scripts/wespy_命令行工具.py "https://mp.weixin.qq.com/mp/应用msgalbum?..." --max-articles 20

# 仅获取专辑文章列表（不下载） python3 scripts/wespy_命令行工具.py "URL" --album-only

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

错误示例：

参数说明

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

命令：python3 scripts/wespy_命令行工具.py [URL] [OPTIONS]

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

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

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

需要覆盖的典型场景：

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

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

结构模式

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

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

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

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

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

• 规范型（标准/规范/指南）

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

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

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

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

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

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

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

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

核心检查：

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

注册完成后告知用户：

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

资源目录 scripts/ init_技能.py — 技能目录初始化脚本，生成四层结构模板 references/ four-layers.md — 四层骨架写法详解（含正误对比） 检查列出.md — 质量检查清单（按层级分 P0/P1/P2） 工作流s.md — 流程组织模式 输出-patterns.md — 输出格式定义