Skill: tuobadaidai/skill-crafter (version 1.1.0)

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


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)