Skill 工坊 (Skill Atelier)

一句话：你说要一个什么样的 skill，我按验证过的流程把它做出来；或者把你已有的 skill 审查、优化一轮。

核心隐喻：定位 = 先定触发分支与调用方式，它决定 description 怎么写、常驻上下文成本花不花；骨架 = 决定哪些内容进 SKILL.md、哪些披露进 references/；写作 = 按写法原则成文；自审 = 照"准确·高效·稳定"三维方针过审查清单（交付前硬闸门）；交付 = 落盘到正确位置、只留一份实体。

入口（用户怎么说，从哪里进）

调用后先交互再动手：用 AskUserQuestion 出三分支选择卡——「新建 skill / 优化已有 skill / 只问写法」；用户首句已带明确走法时，把判定走法放首位标"（推荐）"，由用户确认或改选，不静默替用户定路。

• 新建——"帮我做个 skill"：从步骤 1 起走全流程。
• 优化已有——"审查/优化/精简这个 skill"：用户给出 skill 路径后直接进步骤 4 自审，出审查报告，按用户确认的项修改；修改后按步骤 5 的单一实体与验证要求收尾。
• 只问不写——"description 怎么写"、"什么时候拆 references"：查 references/writing-guide.md 作答，不启动流程。

流程总览

定位 → 骨架 → 写作 → 自审 → 交付。各步含义见上方核心隐喻，不再复述。

新手提示：第一次做 skill？先读 references/quick-start.md——跟着范例从 0 做一遍，动手前扫避坑清单，有疑问查答疑。

适用范围与不适用范围

适用：用户级 / 项目级 skill 的新建、审查、优化、写法咨询。不适用：

• Expert 包创建与运营——走 expert-manager skill。
• MCP server 配置——改 ~/.workbuddy/mcp.json，不是写 skill。
• 安装他人 skill（GitHub/市场）——走 install-skill-from-github 等安装通道（含安全审计）。

步骤 1 · 定位

收集四件事。除调用方式外用自然语言一次问清，不逐项逼问；用户说得简略时用合理假设补齐并回显声明，请其纠正。

• 干什么：一句话说清这个 skill 解决什么问题、给谁用。
• 什么时候触发：列真实触发分支——用户会说的原话，一条分支对应一种真实使用场景。
• 调用方式（AskUserQuestion，两个选项）：
• 模型自动调用——agent 需要自行发现它、或别的 skill 要调用它时用；description 常驻上下文，须按指针标准打磨。
• 用户手动调用——只在用户敲名字时触发，frontmatter 设 disable-model-invocation: true，零常驻成本。吃不准时选此项。
• 判断依据见 references/writing-guide.md §调用方式。
• 安装位置：默认用户级 ~/.workbuddy/skills/；用户明说只服务当前项目时才放 {workspace}/.workbuddy/skills/。

完成标准：用途、触发分支清单、调用方式、安装位置均已确定；skill 名已起（小写连字符，与目录同名）。

步骤 2 · 骨架

按 references/writing-guide.md §信息层级把每个内容块落位到三处之一：SKILL.md 正文、references/（正文留带触发条件的指针）、scripts/（需确定性执行的代码）。

• 流程型 skill 正文以步骤链为骨架，每步带完成标准。
• 动笔前列「文件地图」：每个文件解决什么问题，一行一个，回显给用户确认。

可复用的结构件（入口区、异常兜底、FAQ、基线行等）见 references/writing-guide.md 第二部分「结构模式库」，按骨架需要选用；复杂设计决策拿不准（要不要拆、非流程型怎么搭、原则打架听谁的）见 references/decision-guide.md。

完成标准：文件地图已列出并经用户确认；每个内容块有明确落位，无"先都写进正文再说"。

步骤 3 · 写作

按骨架成文，写作时逐条对照 references/writing-guide.md 各节——此处不复述其内容（其权威地位见注意区）。

完成标准：文件地图所列全部文件成稿并回显；写法原则逐条对照过。

步骤 4 · 自审（硬闸门，不可跳过）

交付前硬闸门（即"强制函数"：靠流程结构逼你真查，而非靠自觉）：未出具覆盖 references/review-checklist.md 全部五组的审查报告，不得进步骤 5。本步按完成标准理论收紧（见 references/writing-guide.md §完成标准）——结论必须来自实际核查，不是打勾。

按三维方针（准确·高效·稳定）逐项过堂，每项给结论（通过 / 已修 / 不适用）。「通过」不能凭印象：必须基于通读该 skill 全部文件并做跨文件交叉比对（checklist 第 1 项"通读全文交叉比对"），且每条结论能回溯到"查了哪个文件的哪段"。三项纪律：

• 做深挖，不走过场：30 项每条都要实际套用一遍、落到实处方算过完。
• 防提前收工：若报告整篇只标"通过"、零已修，必须先二次复核是否漏查，再放行——没挖出任何问题的初查通常查得不够深。
• 弱指针必改：必需材料躲在弱措辞指针后是「方差 bug」（见 writing-guide §指针），发现即改，不得标"通过"放行（checklist 第 5 项）。

发现问题当场改，出审查报告。报告结构固定，缺段视为没自审：

• 各组结论：五组各列结论 + 该组实际查了什么（可回溯依据）；
• 已修清单：逐条「第 N 项 → 问题 → 改法」；
• 不适用声明：标不适用的组，说明原因。

诚实边界：本 skill 是操作指令，系统不会自动核验质量——你是唯一把关人；跳过或糊弄这步 = 交付未经审查的 skill。新建与优化入口都必须过。

完成标准：五组逐项有结论且每条可回溯依据；审查报告（含三段）已交付；已修项已落盘；用户已确认；整篇零已修时已完成二次复核。

步骤 5 · 交付

• 交付前自检：回一句话确认「审查报告已出，五组全过 / 已修 N 项，无遗漏」，闸门通过才交付；未过不得交付。
• 落盘到步骤 1 确定的位置；frontmatter 带 agent_created: true（便于后续用 SkillManage 维护）。
• 同一 skill 只保留一份实体：被 skillhub 收纳或移动后，旧位置的副本删除或改为指针说明，不留双份真相。
• 验证：告知用户调用方式（模型调用的给一句触发语示例，手动调用的告知 /skill名），请其在新会话试调用。

完成标准：文件落盘到位；无重复副本；用户已知晓调用方式。

异常兜底

共同原则：已确认的要素不因异常或改向重问。异常不只给指引——主动用 AskUserQuestion 出选项，把可行的几条路摆给用户挑，推荐项放首位。

• 文件读不到（优化入口）：报告缺失文件与已尝试路径，出选项：①用户重新给路径（推荐） ②在常见位置（~/.workbuddy/skills/、桌面）搜同名 skill ③放弃优化、转新建。不凭空重建。
• 结构混乱（优化入口）：说明乱在哪，出选项：①先出整理方案（文件地图）供确认后再动手（推荐） ②只做用户逐项点头的修改 ③保持原样、只答写法疑问。不主动批量重构。
• 中途改方向：回显受影响与不受影响的已确认要素，出选项：①只回步骤 1 重定位受影响项（推荐） ②全部推翻重来。
• 写作中断：回显各步骤完成状态，出选项：①从最近达成完成标准的步骤接续（推荐） ②指定某步重做。

注意

• 写作方法论的唯一权威出处是本 skill 的 references/writing-guide.md（完整自洽、无外部依赖）；理论拿不准时停下查它，不凭记忆写。
• 本 skill 管"怎么写 skill"，不管"skill 的领域内容是什么"——领域知识由用户提供或调研补齐，不编造。
• 三道质量闸（每道不过不进下道）：写法原则 → 审查清单 → 交付前自检。
• 文档地图（文件 > 3 个，用表）：
  | 文件 | 解决什么 |
  |---|---|
  | references/writing-guide.md | 怎么写 + 长什么样（写法原则 + 结构模式库） |
  | references/review-checklist.md | 怎么验（三维审查清单） |
  | references/decision-guide.md | 复杂/拿不准的设计决策怎么判 |
  | references/quick-start.md | 新手入门（范例 + 避坑 + 答疑） |