# Skill Manual Generate > 在需要根据任意 SKILL 目录自动生成中文使用手册时使用。适用于通读目标 SKILL 目录下的全部有效内容，包括 SKILL.md、_meta.json、references/、scripts/、assets/ 与其他说明材料，理解其用途、触发场景、执行流程、输出结果和边界约束，并根据目标 SKILL 的复杂度与用户意图自动选择标准或极简模板，输出为以 slug 命名的中文 Markdown 使用手册；支持自定义输出目录，未指定时默认写入当前工作区根目录。 - Skill: `yumih1129/skill-manual-generate` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add yumih1129/skill-manual-generate` - Raw SKILL.md: https://api.skillmd.com/api/skills/yumih1129/skill-manual-generate/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: yumih1129 (https://skillmd.com/u/yumih1129) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/yumih1129/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` 命名。 - 若未生成文件，必须给出明确阻塞原因和下一步建议。