Skill Usage Doc（为 skill 生成最详细的小白使用说明）

Overview

本技能是一个生成级（Generation-level）元技能：拿到任意一个 WorkBuddy skill，
自动产出一份"面向完全不懂技术的小白"的最详细使用说明文档，并以文件形式交付。
它把 skill 本身的 SKILL.md 与附带资源，翻译成新手照着做就能上手的保姆级教程。

工作模式为"直接产出交付物"，不是只给建议或只做规划。

When To Use

出现以下任一情况时触发：

• 用户要求"给某个 skill 写/生成/做 使用说明、教程、文档、说明书、小白指南"。
• 用户点名某一 skill（内置、市场安装、或本地 ~/.workbuddy/skills/ 下的），想把它讲给新手。
• 用户拿到一个新 skill，不知道怎么用，需要一份从零讲起的详细指南。
• 用户说"把这个 skill 的用法讲清楚 / 出一份能让小白看懂的说明"。

不会触发（负向场景，避免误用）：
- 用户只想"用"某个 skill 干活（如"帮我合并 PDF"），而非给该 skill 写说明。
- 用户随口问"XX skill 是做什么的"但未要求产出一份文档。
- 用户要的是代码 / 文件本身，而非"使用说明文档"。
- 用户要的是该 skill 的内容产物（如 pdf 技能产出的 PDF），不是说明文档。

输入形态支持：skill 名称（如 pdf）、SKILL.md 文件绝对路径、或 skill 所在目录。

How To Use（工作流）

第 1 步：定位目标 skill

按以下顺序解析用户输入，得到目标 SKILL.md 绝对路径：

1. 若用户给的是目录或 SKILL.md 文件，直接使用。
2. 若给的是 skill 名称，依次查找：
   - ~/.workbuddy/skills/<name>/SKILL.md（用户级）
   - <workspace>/.workbuddy/skills/<name>/SKILL.md（项目级）
   - 已安装市场 skill 目录（若已知路径）；找不到就向用户确认路径。
3. 找不到时，只问一次精确路径，不要反复追问。

第 2 步：解析事实依据

运行分析脚本，提取目标 skill 的名称、描述、标题结构、触发提示、附带资源，
作为生成文档的事实依据（避免凭空编造）：

python "<skill-usage-doc 技能目录>/scripts/analyze_skill.py" "<目标 SKILL.md 或目录>" --json

> 注意：脚本用标准库，可直连 WorkBuddy 托管 Python（下文及全文档以 <托管Python> 指代该解释器全路径；具体路径因机器而异，请勿写死你的本机绝对路径）。
> 同时通读目标 SKILL.md 全文——脚本只给骨架，细节（命令、参数、坑点）靠全文。

第 3 步：加载写作规范与模板

读取本技能自带的两份参考，严格遵循其结构与时：

• references/usage-doc-template.md —— 生成文档必须逐章覆盖的 12 章骨架。
• references/beginner-style-guide.md —— 面向小白的中文写作硬规则（口语化、命令可复制、每步给"你会看到什么"、多用表格、安全提示）。

第 4 步：生成最详细使用说明

> 4.0 先填事实表（硬要求，P1-⑤ 降漏项）：动笔写散文前，必须先把第 2 步 analyze_skill.py 的输出整理成一张「事实表」，逐格填空；散文只是把事实表翻译成人话。没填事实表就写，容易漏章节、漏参数、漏坑点。
>
> 事实表骨架（直接复制到草稿，逐格填）：
> > 技能名 : <name> > 类型 : <analyze_skill.py --type 给出的 6 类之一 + 简/详推荐> # 见下方"篇幅决策" > 一句话 : <description 的人话版> > 触发词 : <triggers 里抽出的 3~5 个原话> > 前置依赖 : <环境/包/Key/Connector/权限，逐条；缺了报什么错> > 真实命令 : <从 SKILL.md 与 resources 文件名中可印证的命令，逐条标解释器> > 参数 : <参数名/默认/示例，逐条> > 坑点 : <路径空格/代理/编码/权限/类型不匹配 等真实易错项> > 产出 : <落盘路径(占位)/格式/怎么预览> > 求助入口 : <官方文档/社区/反馈方式> >
> 填表时同步跑 python scripts/analyze_skill.py <目标> --type 拿「类型 + 简/详推荐」，据此决定篇幅（见下）。

篇幅决策（P2-⑥ · A/B 双版）：
- 详版（CLI/code、Connector、编排路由、Agent-subagent）：命令/参数/坑点/endpoint 必须具体可复制，§4/§5/§7 加厚。
- 简版（纯生成、纯 NL）：对话即用，无需装依赖；§2 写"本 skill 无需本地依赖，直接在 WorkBuddy 内对话即可"，把篇幅省在 §4 的「失败自查」与示例上，避免冗余安装步骤吓退小白。
- 类型探测仅供默认推荐；最终篇幅由用户明确要求或目标 skill 实际复杂度覆盖。

基于事实表 + 第 3 步的模板/规范，逐章撰写。要求：

• 严格按 usage-doc-template.md 的 12 章顺序，不跳章、不漏章；不适用的章节写"本 skill 不涉及"并简述原因。
• 全文中文、口语化；首次出现术语括号解释；所有命令放进可复制代码块并标清用哪个解释器。
• 必须包含：① 触发场景速查表；② 保姆级分步流程（含"你输入的话 / AI 做了什么 / 你会看到什么"）；③ 参数表；④ 新手 10 坑；⑤ 一个端到端完整实战案例；⑥ FAQ。
• 内容要"最详细"：宁可多写具体例子，不要抽象带过；但简版类型不要把"无需安装"硬凑成多步。

第 5 步：落盘为文件（生成级交付）

将生成的文档写入 Markdown 文件：

• 默认文件名：使用说明-<skill名>.md
• 默认位置：用户当前工作区根目录；若用户指定了路径/目录，按用户指定的来。
• 若目标 skill 目录可写且用户未指定，也可顺手放在 <目标 skill 目录>/使用说明.md 方便随技能分发。

写入后用 Read 复查一次，确认格式无误、无明显缺章。

• 事实校验（P0 加固 · Trust 闸门）：写入后跑一次本技能的 scripts/verify_doc.py <生成的说明.md> <源 SKILL.md 或目录>：
  它做两件事——① 结构断言（12 章齐全 / 无本机硬编码路径 / 含失败自查）；② 事实校验（代码块里的命令、脚本名是否在源 SKILL.md 文本与其资源文件名 scripts/references/assets 中能印证）。
  结构硬伤必须修掉再交付；"待人工复核"项逐条确认并非编造后再发。

第 6 步：交付与预览

• 用 present_files 呈现生成的 .md 文件，让用户在面板中直接查看。
• 一句话摘要：为哪个 skill 生成了说明、落在哪、包含哪些章节。
• 若用户希望转 HTML / Word / 配图，提示可继续调用对应技能（如 html-to-docx、tencent-docx）。

第 7 步：收集反馈（沉淀到 feedback.md）

交付后主动邀请用户标注问题 / 缺漏 / 想加的章节，写入本技能目录的 feedback.md：

• 格式：每条一行，以 - 开头；版式偏好用 [A/B] 标签（如 - 第7章例子太虚 [A/B:案例多]）。
• 目的：为第 8 步自适应进化提供数据底座（对应 D9 反馈回路 = 5）。
• 用户没反馈则跳过，不勉强。

第 8 步：自适应进化（D10，Agent 辅助自进化）

当 feedback.md 积累 ≥3 条，或用户说"优化说明技能 / 让这个 skill 自我进化"，执行自迭代闭环：

1. 备份：python scripts/self_improve.py backup（改前必备份到 .backups/，可回滚）。
2. 读反馈：通读 feedback.md，归纳高频问题（如"坑点不具体""实战案例缺"）。
3. 自改：直接编辑 references/usage-doc-template.md 或 references/beginner-style-guide.md（必要时改 SKILL.md 自身工作流），落实改进——不经人工复述，自动应用。
4. 记账：python scripts/self_improve.py apply <改进后文件> <target相对路径> 自动写 CHANGELOG.md 并升版本号。
5. A/B 分化：python scripts/self_improve.py ab 按反馈偏好汇总推荐默认版式；对同一目标 skill 可生成"详版 / 简版"两种风格，用历史反馈择优，把胜出版式固化进模板。
6. 回滚：若自改引入回归，从 .backups/ 取最近备份覆盖即可。

> 该闭环让本技能具备"自收集反馈 → 建议迭代 → A/B 分化"的 Agent 辅助进化能力（成熟度 D10 = 4，非代码全自动；"自改模板"由 Agent 在触发后执行，脚本只负责备份/应用/记账/回滚）。仍由用户 / 自动化触发，不后台私自运行。

Resources

scripts/

• analyze_skill.py —— 解析目标 SKILL.md，输出 frontmatter、标题层级、触发提示、附带资源清单（支持 --json）。生成文档前必跑，作为事实依据。
• verify_doc.py —— 生成后事实校验器（P0 加固）：对生成的说明做结构断言 + 事实印证核对，输出"待人工复核"清单，作为 Trust/Reliability 闸门（详见第 5 步）。
• self_improve.py —— 自适应进化引擎（支撑 D10，Agent 辅助）：backup 备份、apply 带备份应用改进并升版、status 反馈统计、ab A/B 偏好汇总。只复制/覆盖，绝不删用户文件。

references/

• usage-doc-template.md —— 生成文档必须遵循的 12 章骨架。
• beginner-style-guide.md —— 面向小白的中文写作规范。

assets/

• 本技能无附带资源文件（不依赖模板二进制）。

Notes

• 本技能为生成级：最终交付物是真实文档文件，而非口头建议。
• 若目标 skill 本身信息不足（如 description 缺失触发词），按全文合理推断并在文档中标注"推测"，不要编造确定结论。
• 涉及密钥/账号的内容，只在文档里教"去哪开、填到哪"，绝不替用户保存或输出真实密钥。
• 自适应进化（D10，Agent 辅助）：反馈闭环写入 feedback.md，自改前必 backup 到 .backups/，所有变更记 CHANGELOG.md；自改受红线约束（不泄露密钥、不产出违规内容、改坏可回滚）。