Skill manual generate

Skill: SKILL 使用手册生成器

用于把一个已有 SKILL 目录转化为正式、简洁、可直接交付的中文使用手册。执行时必须先完整理解目标 SKILL，再按最合适的模板输出 Markdown 文档；不得在未读懂能力边界的情况下套模板生成。

本 SKILL 的目标不是设计新能力，而是把已有 SKILL 的真实能力整理成“可读、可用、可交付”的使用手册。

核心原则

• 先理解，再写作；所有手册内容必须可追溯到目标 SKILL 的实际文件。
• 手册面向使用者，不面向设计者；重点写“如何使用”，不是写设计背景。
• 不得编造目标 SKILL 未声明的能力、流程、资源、输出或权限。
• 必须以“目录级理解”为前提，不得只读取 SKILL.md 和 _meta.json 就草率成稿。
• 同一输入在同一版本下必须按相同的读取顺序、模板选择顺序和落盘规则处理，不得因执行者习惯改变取舍。
• 输出文件名固定取自目标目录 _meta.json 中的 slug 字段，扩展名固定为 .md。
• 输出位置由用户提供目录决定；未指定时默认写入当前工作区根目录。
• 若用户提供参考手册路径，只借鉴其结构和语气，不借鉴目标能力之外的内容。
• 主文档保留核心流程与门禁；具体输出模板放入 references/，按需加载。
• 若同一内容在主文件与模板中重复，主文件只负责流程和选择规则，模板只负责最终版式。
• 文档中“相关文件”章节的目录路径统一使用相对当前工作区根目录的表示，变量名记为 project_relative_skill_dir。
• project_relative_skill_dir 由 skill_dir 相对当前工作区根目录计算得到；无论输入是否为绝对路径，正文都不得直接引用绝对路径。

权威顺序

• SKILL.md 负责输入、流程、模板选择、落盘规则和失败处理。
• references/doc-template.md 负责标准使用手册模板结构。
• references/doc-template-minimal.md 负责极简使用手册模板结构。
• 若模板文件与主文件存在重复表述，以主文件的流程规则和模板文件的结构规则分别为准，不在模板中扩展新的选择条件。

何时使用

• 用户要求为某个现有 SKILL 生成“使用手册”或“说明文档”。
• 用户给出一个 SKILL 目录，要求自动整理为标准 Markdown 文档。
• 用户希望手册文件名与目标 SKILL 的 slug 保持一致。
• 用户要求参考既有手册风格，但内容必须来自另一套 SKILL 文件。

不应触发的场景：

• 用户要创建新的 SKILL 本体，而不是手册，应优先使用 SKILL 创建能力。
• 用户只要求质量评估、评分或审查，不要求输出手册。
• 用户只给出主题描述，未提供可读取的 SKILL 目录，也没有足够材料支撑手册生成。

输入与输出契约

输入

必需输入：

• skill_dir：目标 SKILL 目录路径。

可选输入：

• output_dir：手册输出目录；未指定时默认当前工作区根目录。
• reference_doc_path：参考手册路径；若提供，则借鉴其结构和语气。
• template_style：模板风格；可选 auto、standard 或 minimal，默认 auto。
• doc_title：手册标题；未指定时默认使用“{技能名称} 使用手册”。

固定生成工作单：

• 记录目标目录、输出目录、slug、标题、模板来源、模板选择依据、已读取文件、已排除文件和最终输出路径。
• 生成正文时，统一把目标目录换算为 project_relative_skill_dir，供“相关文件”章节使用。
• 已读取文件 按实际读取顺序记录，默认使用路径字典序。
• 已排除文件 只记录已经扫描但最终不写入正文的文件，并注明排除原因。
• 只要某项能力、边界、示例或注意事项没有明确证据，就不写入正文。
• 若生成前后同一条目出现口径差异，必须先定位证据变化、规则变化或前次误读，再继续输出。

目标目录最小要求

目标目录内至少应存在：

• SKILL.md
• _meta.json

若存在以下补充内容，也必须纳入理解范围：

• references/
• scripts/
• assets/
• 同目录下其他说明性 Markdown、YAML、JSON 或模板文件
• 任何直接影响触发、流程、输出、边界或示例的补充文件

扫描与读取顺序固定如下：

• 先按路径字典序扫描整个目标目录。
• 再按路径字典序读取后缀属于以下集合的文件：.md、.markdown、.txt、.json、.yml、.yaml、.toml、.ini、.csv、.tsv、.py、.sh、.js、.ts、.jsx、.tsx、.mjs、.cjs、.html、.htm、.xml、.svg。
• references/、scripts/、assets/ 中符合上述后缀集合的文件全部读取。
• 不在上述后缀集合中的文件只记录文件名与用途，不展开内容。

若缺失任一关键文件：

• 停止生成。
• 明确指出缺失项。
• 只提出修复建议，不编造内容。

输出

• 输出文件路径：{output_dir}/{slug}.md
• slug 必须来自 {skill_dir}/_meta.json
• 输出格式必须是标准 Markdown
• 输出文档默认语言为中文

模板资源

若用户未提供参考手册路径，默认按 template_style 或目标 SKILL 复杂度自动选择模板：

• references/doc-template.md

当同时满足下列条件时，优先选择极简模板：

• 用户明确要求极简、简约、轻量、最简输出
• 目标目录没有 scripts/
• 目标目录没有 assets/
• references/ 不存在，或仅有 0-1 个直接支持文件
• SKILL.md 只表达单一主要流程，且没有明显的多阶段、复评、回退、分支或多模板要求

极简模板：

• references/doc-template-minimal.md

以下任一条件成立时，优先选择标准模板：

• 用户明确要求正式、完整、交付型、系统性说明
• 目标目录含有 scripts/、assets/，或 references/ 超过 1 个直接支持文件
• SKILL.md 含有多阶段、复评、回退、分支、失败处理或多模板要求
• 任何一项极简条件不满足

模板使用规则：

• 章节名称只允许做一次性、同义且必要的微调，不能在同一份文档中混用多个近义标题。
• 若目标 SKILL 更强调“交付内容”“执行流程”“输出产物”，可将“输出结果”改为更贴切标题。
• 若用户提供 reference_doc_path，优先参考其结构与语气，但不得照搬内容。
• 若用户指定 template_style=minimal，直接使用极简模板；若指定 standard，直接使用标准模板；若指定 auto 或未说明，则先判断是否满足全部极简条件，只有全部满足才使用极简模板，否则使用标准模板。
• 若未提供参考文档，也未能读取模板资源，才允许退回最小结构手册，但必须明确说明降级原因。

标准流程

阶段 0：确认任务

动作：

• 确认 skill_dir 是否存在且可读。
• 确认是否给出 output_dir 和 reference_doc_path。
• 若未给出 output_dir，默认使用当前工作区根目录。
• 若未给出 reference_doc_path，根据 template_style 与目录特征选择模板：
  • standard：读取 references/doc-template.md
  • minimal：读取 references/doc-template-minimal.md
  • auto：仅当全部极简条件同时满足时才使用极简模板，否则使用标准模板
• 扫描目标目录下的全部文件与子目录，建立阅读清单。

输出：

• 目标 SKILL 路径。
• 输出目录。
• 最终输出文件名。
• 是否使用参考文档。

通过标准：

• 能明确回答“读哪个 SKILL、输出到哪里、文件名是什么”。

阶段 1：读取与理解目标 SKILL

动作：

• 通读 {skill_dir} 下的全部有效内容，而不是只读两个核心文件。
• 完整读取 {skill_dir}/SKILL.md。
• 读取 {skill_dir}/_meta.json。
• 若存在 references/，按路径字典序读取其中全部可读文本文件。
• 若存在 scripts/，按路径字典序读取其中全部符合后缀集合的文件，并提取其用途、触发关系和对技能执行的支撑作用。
• 若存在 assets/，按路径字典序读取其中全部符合后缀集合的文件；其余文件只记录用途，不展开内容。
• 读取同目录下其他说明性文件时，按路径字典序读取全部符合后缀集合的文件。
• 生成“相关文件”章节时，所有目录路径统一使用 project_relative_skill_dir，不保留绝对路径或系统根路径。
• 提取以下信息：
  • 技能名称、slug、版本、状态、分类、标签、描述。
  • 核心用途。
  • 典型触发场景。
  • 输入要求。
  • 主执行流程。
  • 输出或交付结果。
  • 不适用场景、风险边界和用户确认点。
  • 参考资料、脚本、模板、素材等辅助资源在实际使用中的角色。
  • 每个核心结论对应的文件来源或章节来源。

输出：

• 手册写作所需的结构化信息清单。
• 目标目录内容清单与已采纳的关键证据。

通过标准：

• 已能用简洁语言说明目标 SKILL“做什么、何时用、如何用、产出什么”。
• 已确认目录内哪些补充文件会影响手册内容，哪些只是辅助材料。

阶段 2：学习参考结构

动作：

• 若提供 reference_doc_path，读取其标题结构、章节顺序、表格形式、示例写法和语气风格。
• 仅借鉴结构和表达方式，不复制其领域内容。
• 若未提供参考文档，则根据 template_style 或自动判断读取默认模板：
  • standard：references/doc-template.md
  • minimal：references/doc-template-minimal.md
  • auto：仅当全部极简条件同时满足时才使用极简模板，否则使用标准模板

输出：

• 写作结构方案。

通过标准：

• 已确定最终手册的章节顺序和表达风格。
• 参考文档只提供结构与语气，不提供事实依据。

阶段 3：起草手册

动作：

• 按结构化信息填写模板。
• 至少提供 3 组与目标 SKILL 强相关的使用示例；按以下固定顺序取值，最多取 3 组：
  1. SKILL.md 或补充文件中明确写出的主流程示例。
  2. SKILL.md 或补充文件中明确写出的边界、限制、失败或回退示例。
  3. SKILL.md 或补充文件中明确写出的输出、交付物或结果示例。
• 若第 1 至第 3 项合计不足 3 组，只写可证实的全部示例，不补造。
• 将能力写成使用者可以直接理解的表达。
• 所有信息都必须源自目标 SKILL 的真实能力，不得自行扩展。

必须覆盖的内容：

• 技能名称。
• 版本。
• 功能简介。
• 适合的触发方式。
• 支持的主要能力。
• 输出结果或交付物。
• 注意事项与使用边界。
• 适用场景。
• 相关文件。

通过标准：

• 手册可以直接给使用者阅读，无需再结合设计文档解释。

阶段 4：写入文件

动作：

• 从 _meta.json 读取 slug。
• 计算输出路径：{output_dir}/{slug}.md
• 将 Markdown 正文写入目标文件。

写入规则：

• 不得擅自改用其他文件名。
• 不得输出为 .txt、.mdx 或其他格式。
• 若目标文件已存在，只用于确认落盘位置和是否需要覆盖，不把旧稿内容当作本次证据来源；默认整体重写为当前版本，若用户明确要求保留历史版本，另存新快照，不在旧稿末尾追加。

通过标准：

• 实际落盘文件路径与 slug 一致。

阶段 5：自检与验收

检查项：

• 文件名是否等于 slug + .md
• 文档是否为标准 Markdown
• 是否包含核心章节
• 是否存在凭空编造的能力
• 示例是否与目标 SKILL 相匹配
• 相关文件路径是否正确
• 相关文件路径是否全部为相对当前工作区根目录的表示
• 是否已记录模板选择依据与证据来源
• 是否已记录内容无法追溯时的省略项
• 是否按固定顺序读取并记录文件
• 文风是否正式、简洁、清晰

验收标准：

• 使用者无需阅读 SKILL.md 全文，也能理解该技能的主要用法。
• 设计者检查后，能确认手册没有超出原始能力边界。
• 输出文档可直接放入仓库使用。

用户交互规则

1. 用户已给出 skill_dir 时，直接读取，不要反复确认流程。
2. 缺少关键路径、关键文件不存在或 slug 缺失时，只问阻塞性问题；一次最多问 3 个。
3. 用户只指定目录、不指定输出目录时，默认输出到当前工作区根目录。
4. 用户提供参考手册时，先学习其结构再写作；未提供时按 template_style 读取默认模板。
5. 用户要求“直接生成”时，直接创建最终 Markdown 文件，不先输出多版方案。
6. 用户要求“只给模板”时，按当前选择的模板风格输出模板内容，不写入目标文件。

质量门禁

• 结构可读：目标目录存在且 SKILL.md、_meta.json 可读取。
• 目录已通读：目标目录下全部有效内容已扫描，且与手册相关的补充文件已按需读取。
• slug 可用：_meta.json 中存在合法 slug。
• 内容可追溯：手册中的核心结论都能追溯到目标 SKILL 文件。
• 模板完整：标准模板成稿至少包含概述、快速开始、功能特性、使用方式、输出结果、示例、注意事项、适用场景、相关文件；极简模板可省略“相关文件”与部分展开章节，但必须保留概述、如何使用、能力、输出、示例、注意事项。
• 模板匹配：模板风格与用户要求一致；auto 模式下，只有在全部极简条件同时满足时才使用极简模板，否则使用标准模板。
• 路径正确：输出路径与文件名满足 {output_dir}/{slug}.md。
• 路径规范：若存在“相关文件”章节，其中所有目录路径均使用相对当前工作区根目录的表示，不得出现绝对路径。
• 记录一致：已读取文件 与 已排除文件 的口径一致，且不把未扫描文件写成排除项。
• 结果可交付：Markdown 可直接保存和渲染，无需二次补写。

失败处理

• 若 skill_dir 不存在：停止并报告目录不可访问。
• 若 SKILL.md 缺失：停止并提示目标目录不是完整 SKILL。
• 若 _meta.json 缺失：停止并提示无法确定 slug。
• 若 slug 为空或非法：停止并要求修正元数据。
• 若目录下存在关键补充材料但未读取：停止交付并补齐阅读，不得带缺口成稿。
• 若参考手册不可读：降级为使用与 template_style 对应的默认模板，并明确说明。
• 若用户要求极简模板但极简模板资源不可读：降级为标准模板并说明。
• 若模板资源不可读：退回最小结构手册，并明确说明模板资源缺失。
• 若目标能力边界不清：优先保守归纳，不得用主观猜测补齐。

最终交付要求

执行完成后，最终至少应给出：

• 生成的目标文件路径。
• 使用的模板来源：参考手册、references/doc-template.md 或 references/doc-template-minimal.md。
• 选择模板的依据：template_style 显式指定或 auto 自动判断。
• 是否成功按照 slug 命名。
• 若未生成文件，必须给出明确阻塞原因和下一步建议。