Skill 中文使用示例生成器是一个专业的文档自动化生成工具，旨在为其他 Skill 创建结构化、工业级标准的中文使用说明文档。该工具通过智能解析目标 Skill 的 SKILL.md 源文件，自动提取关键信息并生成完整的使用指南。
该 Skill 采用多阶段处理流程：
生成的使用说明文档包含以下核心章节：
执行本 Skill 前，系统必须满足以下条件：
功能说明：
自动检测并解析用户输入中的目标 Skill 路径信息。系统支持多种路径输入格式，并具备智能路径推断能力。
输入模式识别：
输入模式识别:
├── 完整路径: "./skills/xlsx" → 直接使用
├── 相对路径: "skills/xlsx" → 转换为 "./skills/xlsx"
├── Skill名称: "xlsx" → 搜索匹配 "./skills/xlsx"
└── 无路径: 询问用户 "请提供目标 Skill 的路径，例如：./skills/xlsx"
路径解析策略：
./ 或绝对路径开头的字符串
./skills/xlsx、/home/user/skills/pdf
./ 前缀的相对路径
./ 前缀
skills/xlsx → ./skills/xlsx
./skills 目录下搜索匹配
功能说明：
对获取的目标路径进行多维度验证，确保路径有效且具备必要的访问权限。
验证步骤：
验证步骤:
1. 检查路径是否存在
2. 检查是否为目录
3. 检查 SKILL.md 是否存在
4. 检查文件是否可读
5. 检查目录是否可写
详细验证流程：
验证失败处理策略：
| 错误类型 | 错误代码 | 恢复策略 | 用户通知 |
|----------|----------|----------|----------|
| 路径不存在 | E001 | 列出可用 Skill 路径 | "未找到目标 Skill，可用选项：..." |
| 非目录路径 | E001 | 提示正确路径格式 | "请提供有效的 Skill 目录路径" |
| SKILL.md 缺失 | E002 | 提供创建模板选项 | "SKILL.md 不存在，是否创建模板？" |
| 无读取权限 | E003 | 提示权限提升方法 | "需要读取权限，请检查文件权限" |
| 无写入权限 | E003 | 建议更换输出路径 | "需要写入权限，请检查目录权限或更换路径" |
功能说明：
解析 SKILL.md 文件的 YAML frontmatter 部分，提取元数据信息。
提取字段定义：
必需字段:
- name: Skill 名称
用途: 生成文档标题、标识 Skill
缺失处理: 使用目录名作为替代
- description: 功能描述
用途: 生成简介部分的核心内容
缺失处理: 从正文提取或标记为待完善
可选字段:
- version: 版本号
用途: 文档版本追踪、变更管理
缺失处理: 使用 "1.0.0" 作为默认值
- author: 作者
用途: 文档归属信息
缺失处理: 使用 "Unknown" 作为默认值
- tags: 标签列表
用途: 文档分类、检索
缺失处理: 从描述中提取关键词
- triggers: 触发词列表
用途: 生成触发方式部分
缺失处理: 从正文中提取关键词
Frontmatter 解析规则：
--- 包裹区域
功能说明：
提取 SKILL.md 文档的各个章节内容，用于生成对应的使用说明章节。
章节映射关系：
| 源文档章节 | 提取内容 | 目标文档章节 | 处理方式 |
|------------|----------|--------------|----------|
| 功能概述 | 核心功能描述 | 简介 | 翻译润色 |
| 触发条件 | 关键词列表 | 触发方式 | 分类整理 |
| 工作流程 | 步骤说明 | 功能说明 | 详细展开 |
| 参数说明 | 参数表格 | 参数说明 | 格式转换 |
| 示例 | 使用示例 | 使用示例 | 补充完善 |
| 注意事项 | 提示信息 | 注意事项 | 归纳整理 |
内容提取策略：
功能说明：
检查提取的信息是否足够生成完整的使用说明文档，对缺失信息进行智能补充。
完整性检查清单：
检查清单:
□ 名称已提取
└─ 未提取 → 使用目录名作为名称
□ 描述已提取
└─ 未提取 → 从内容中推断或标记为待完善
□ 至少1个触发词
└─ 未提取 → 从正文中提取关键词
□ 至少1个功能点
└─ 未提取 → 基于描述生成基础功能
□ 示例或功能描述足够生成示例
└─ 不足 → 基于功能点生成基础示例
信息补充策略：
skill_example_generator → Skill Example Generator
功能说明：
基于工业级文档标准，定义使用说明文档的完整结构模板。
标准文档结构：
---
document_version: 1.0.0
generated_at: YYYY-MM-DD HH:mm:ss
generator_version: X.X.X
source_skill_version: X.X.X
source_skill_hash: [hash]
generator: skill-example-generator
---
# [Skill名称] 使用说明
## 简介
[功能概述，翻译为中文]
[核心价值]
[适用场景]
## 触发方式
[主要触发词列表]
[辅助触发词列表]
[触发优先级说明]
## 功能说明
[功能1详细说明]
[功能2详细说明]
...
## 参数说明
[参数表格]
[参数依赖关系]
[复杂参数展开]
## 使用示例
[示例1：快速入门]
[示例2：进阶技巧]
[示例3：最佳实践]
[示例4：故障排除]
## 常见问题
[FAQ列表]
## 注意事项
[重要提示]
[最佳实践建议]
## 文档变更历史
[版本记录]
---
*本文档由 skill-example-generator 自动生成*
功能说明：
按照模板结构，逐章节生成文档内容。
生成流程：
功能说明：
管理生成文档的输出路径和文件存储。
输出路径规则：
默认输出路径: [目标Skill路径]/examples/使用说明.md
路径处理逻辑:
1. 检查目标目录是否存在 examples 子目录
2. 如不存在，自动创建 examples 目录
3. 生成文件：使用说明.md
4. 如文件已存在，提供覆盖或增量更新选项
文件命名规则：
使用说明.md
使用说明_[语言代码].md（如 使用说明_en.md）
使用说明_v[版本号].md（用于归档）
功能说明：
生成完成后，向用户提供详细的执行结果报告和质量评估。
结果反馈内容：
✅ 使用说明文档生成成功
📄 文件路径: [完整路径]
📊 文档统计:
- 功能说明: X 个
- 使用示例: X 个
- 参数说明: X 个
- 注意事项: X 条
- 文档总行数: X 行
- 文档大小: X KB
📝 生成内容:
✓ 简介与概述
✓ 触发方式说明
✓ 功能详细说明
✓ 参数参考表格
✓ 实际使用示例
✓ 常见问题解答
✓ 注意事项提醒
✓ 版本元数据
✓ 变更历史
📈 质量评分: [XX]/100 [等级]
💡 建议:
- 检查生成的示例是否符合实际使用场景
- 验证参数说明的准确性
- 根据实际使用情况补充特定场景示例
质量报告生成：
基于预设的质量标准，对生成的文档进行自动评分：
| 维度 | 权重 | 得分 | 评价 |
|------|------|------|------|
| 完整性 | 25% | [X] | [评价] |
| 准确性 | 25% | [X] | [评价] |
| 可读性 | 20% | [X] | [评价] |
| 实用性 | 20% | [X] | [评价] |
| 规范性 | 10% | [X] | [评价] |
质量等级：
| 英文术语 | 中文译法 | 备注 |
|----------|----------|------|
| Skill | Skill/技能 | 保留英文或中文均可 |
| trigger | 触发词 | 标准译法 |
| workflow | 工作流程 | 标准译法 |
| parameter | 参数 | 标准译法 |
| API | API | 保留英文 |
| CLI | 命令行工具 | 中文译法 |
根据 Skill 类型和复杂度，示例分为以下类别：
| 类别 | 适用场景 | 示例数量 | 详细程度 |
|------|----------|----------|----------|
| 快速入门 | 首次使用 | 1个 | 最简步骤 |
| 基础用法 | 核心功能 | 2-3个 | 标准流程 |
| 进阶技巧 | 复杂场景 | 2个 | 详细说明 |
| 最佳实践 | 生产环境 | 1-2个 | 完整工作流 |
| 故障排除 | 常见问题 | 1-2个 | 问题+解决方案 |
每个功能示例必须包含以下要素：
### 示例 [N]: [场景标题]
**场景描述**:
[描述使用场景、目标用户、解决的问题]
**适用条件**:
- [条件1]
- [条件2]
**输入**:
[用户的具体输入内容]
**操作步骤**:
1. [步骤1：具体操作]
2. [步骤2：具体操作]
3. [步骤3：具体操作]
**预期输出**:
[系统返回的结果，包含关键信息]
**结果验证**:
- [验证点1]
- [验证点2]
**关键说明**:
> [补充说明、注意事项、最佳实践建议]
根据提取的信息自动生成示例：
策略 1: 基于工作流程生成
输入: 工作流程步骤
输出: 每个主要步骤对应一个示例
规则:
- 首步骤 → 快速入门示例
- 核心步骤 → 基础用法示例
- 复杂步骤 → 进阶技巧示例
策略 2: 基于参数组合生成
输入: 参数列表
输出: 不同参数组合的示例
规则:
- 必填参数 → 基础示例
- 可选参数 → 进阶示例
- 参数组合 → 复杂场景示例
策略 3: 基于使用场景生成
输入: Skill描述中的关键词
输出: 场景化示例
规则:
- 提取动词+名词组合作为场景
- 根据 Skill 类型匹配典型场景
生成示例后执行以下检查：
□ 完整性检查
□ 包含场景描述
□ 包含输入示例
□ 包含操作步骤
□ 包含预期输出
□ 包含验证方法
□ 准确性检查
□ 输入格式正确
□ 步骤逻辑连贯
□ 输出结果合理
□ 与原始 SKILL.md 一致
□ 可读性检查
□ 语言简洁明了
□ 无歧义表述
□ 格式统一规范
□ 代码可执行
□ 实用性检查
□ 解决实际问题
□ 覆盖常见场景
□ 包含边界情况
□ 提供最佳实践
从 SKILL.md 中提取参数信息的优先级：
| 字段 | 说明 | 格式要求 | 示例 |
|------|------|----------|------|
| 参数名 | 参数标识符 | 小写+下划线 | file_path |
| 类型 | 数据类型 | 标准类型名 | string |
| 必填 | 是否必须 | 是/否/条件 | 条件 |
| 默认值 | 默认值 | 具体值或- | "utf-8" |
| 说明 | 参数用途 | 简洁描述 | 文件路径 |
| 约束 | 取值限制 | 范围/格式/枚举 | ^\.[a-z]+$ |
| 示例值 | 有效示例 | 具体值 | "./data.txt" |
| 类型标识 | 说明 | 示例值 | 约束格式 |
|----------|------|--------|----------|
| string | 字符串 | "hello" | 长度、格式正则 |
| number | 数字 | 42 | 范围、精度 |
| integer | 整数 | 100 | 范围 |
| boolean | 布尔 | true | 无 |
| array | 数组 | ["a", "b"] | 元素类型、长度 |
| object | 对象 | {"key": "value"} | 必需字段 |
| enum | 枚举 | "option1" | 可选值列表 |
| path | 路径 | "./file.txt" | 绝对/相对 |
| url | URL | "https://..." | 协议限制 |
| datetime | 日期时间 | "2024-01-01" | 格式 |
对于存在依赖关系的参数，添加依赖说明：
**参数依赖**:
| 参数A | 依赖条件 | 参数B |
|-------|----------|-------|
| `output_format` | 当 `export=true` 时必填 | `export` |
| `password` | 当 `auth_type="basic"` 时必填 | `auth_type` |
对于对象类型的复杂参数，展开子字段：
**options 参数详情**:
| 子参数 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| options.encoding | string | 否 | 编码格式 | `"utf-8"` |
| options.timeout | integer | 否 | 超时时间(秒) | `30` |
| options.retry | boolean | 否 | 是否重试 | `true` |
为 ./skills/xlsx 生成使用说明
处理流程:
./skills/xlsx
./skills/xlsx/examples/使用说明.md
给 xlsx 写个使用说明
处理流程:
xlsx
./skills/xlsx
怎么使用 skill-example-generator？
处理流程:
为所有 skill 生成使用说明
处理流程:
./skills 目录下所有 Skill
批量生成规则:
examples/使用说明.md 的 Skill（除非用户要求覆盖）
输出示例:
🚀 开始批量生成使用说明文档...
📋 发现 29 个 Skill 待处理：
1. admapix-1.0.28
2. agent-chronicle-0.7.2
3. canvas-design
...
⏳ 开始逐个生成：
[1/29] admapix-1.0.28
✅ 生成成功 → ./skills/admapix-1.0.28/examples/使用说明.md
[2/29] agent-chronicle-0.7.2
✅ 生成成功 → ./skills/agent-chronicle-0.7.2/examples/使用说明.md
[3/29] canvas-design
⚠️ 已存在，跳过（使用 "覆盖" 强制重新生成）
...
📊 批量生成完成！
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 成功：27 个
⚠️ 跳过：1 个（已存在）
❌ 失败：1 个（权限不足）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📁 生成的文档列表：
- ./skills/admapix-1.0.28/examples/使用说明.md
- ./skills/agent-chronicle-0.7.2/examples/使用说明.md
- ...
💡 提示：
- 使用 "为所有 skill 生成示例并覆盖" 可强制重新生成所有文档
- 使用 "为 [skill-name] 生成示例" 可单独生成特定 Skill
| 错误代码 | 错误类型 | 严重程度 | 说明 |
|----------|----------|----------|------|
| E001 | 路径错误 | 高 | 目标 Skill 路径不存在或无效 |
| E002 | 文件缺失 | 高 | SKILL.md 文件不存在 |
| E003 | 权限错误 | 高 | 无读取或写入权限 |
| E004 | 格式错误 | 中 | SKILL.md 格式不符合规范 |
| E005 | 内容缺失 | 中 | 关键信息（名称/描述）缺失 |
| E006 | 解析错误 | 中 | Markdown 解析失败 |
| E007 | 生成错误 | 低 | 文档生成过程中出现异常 |
| E008 | 写入错误 | 高 | 文件写入失败 |
在执行核心逻辑前进行预检查：
预检查清单:
□ 工作目录可写
□ 目标路径格式正确
□ 系统资源充足
□ 依赖服务可用
每个阶段设置错误捕获点：
错误捕获点:
├── 路径验证阶段
│ └── 捕获: E001, E002, E003
├── 文件解析阶段
│ └── 捕获: E004, E005, E006
├── 内容生成阶段
│ └── 捕获: E007
└── 文件输出阶段
└── 捕获: E008
| 错误类型 | 恢复策略 | 用户通知 |
|----------|----------|----------|
| 路径错误 | 列出可用 Skill 路径 | "未找到目标 Skill，可用选项：..." |
| 文件缺失 | 提供创建模板选项 | "SKILL.md 不存在，是否创建模板？" |
| 权限错误 | 提示权限提升方法 | "需要写入权限，请检查目录权限" |
| 格式错误 | 尝试容错解析 | "格式不规范，已尝试最佳 effort 解析" |
| 内容缺失 | 使用默认值补充 | "部分信息缺失，已使用默认值填充" |
| 解析错误 | 降级为文本提取 | "解析失败，已降级处理" |
| 生成错误 | 分段重试生成 | "部分生成失败，已重试" |
| 写入错误 | 更换输出路径 | "写入失败，尝试备用路径..." |
❌ 错误 [E###]: [错误标题]
📋 错误详情:
[详细描述]
🔧 建议解决方案:
1. [方案1]
2. [方案2]
📖 相关文档: [链接]
生成文档按以下维度评分（满分 100 分）：
| 维度 | 权重 | 评分标准 | 扣分项 |
|------|------|----------|--------|
| 完整性 | 25% | 包含所有必需章节 | 每缺失一个章节 -5 分 |
| 准确性 | 25% | 内容与原始文档一致 | 每处不一致 -3 分 |
| 可读性 | 20% | 语言流畅、格式规范 | 每处格式错误 -2 分 |
| 实用性 | 20% | 示例具有参考价值 | 示例不合理 -5 分/个 |
| 规范性 | 10% | 符合文档规范 | 每处不规范 -2 分 |
质量等级划分:
□ 文档标题存在且正确
□ 所有必需章节存在
□ 章节顺序正确
□ 标题层级正确
□ 简介非空且有意义
□ 触发词列表非空
□ 功能说明详细
□ 参数表格完整
□ 示例数量达标
□ 注意事项存在
□ Markdown 语法正确
□ 表格格式正确
□ 代码块标注语言
□ 链接格式正确
□ 图片引用正确
□ 术语使用一致
□ 参数名一致
□ 示例与描述一致
□ 格式风格一致
生成质量检查报告：
## 文档质量报告
**生成时间**: YYYY-MM-DD HH:mm:ss
**目标 Skill**: [skill-name]
**质量评分**: [XX]/100 [等级]
### 详细评分
| 维度 | 得分 | 权重 | 加权得分 | 评价 |
|------|------|------|----------|------|
| 完整性 | [X] | 25% | [X] | [评价] |
| 准确性 | [X] | 25% | [X] | [评价] |
| 可读性 | [X] | 20% | [X] | [评价] |
| 实用性 | [X] | 20% | [X] | [评价] |
| 规范性 | [X] | 10% | [X] | [评价] |
### 问题列表
| 序号 | 问题类型 | 位置 | 描述 | 建议 |
|------|----------|------|------|------|
| 1 | [类型] | [章节] | [描述] | [建议] |
### 改进建议
1. [建议1]
2. [建议2]
生成的使用说明文档采用语义化版本控制：
版本格式: 主版本.次版本.修订号
示例: 1.2.3
版本递增规则:
- 主版本: 重大结构调整、不兼容变更
- 次版本: 新增功能、章节、示例
- 修订号: 错误修复、内容优化
在生成的文档头部添加版本信息：
---
document_version: 1.0.0
generated_at: 2026-05-12 10:30:00
generator_version: 1.1.0
source_skill_version: 2.0.0
source_skill_hash: abc123
generator: skill-example-generator
---
记录文档变更历史：
## 文档变更历史
| 版本 | 日期 | 变更类型 | 变更内容 | 作者 |
|------|------|----------|----------|------|
| 1.1.0 | 2026-05-12 | 新增 | 添加高级用法示例 | AI |
| 1.0.1 | 2026-05-11 | 修复 | 修正参数说明错误 | AI |
| 1.0.0 | 2026-05-10 | 创建 | 初始版本 | AI |
| 类型标识 | 说明 | 使用场景 |
|----------|------|----------|
| 创建 | 首次生成 | 新 Skill 文档 |
| 新增 | 添加内容 | 新增章节、示例 |
| 修改 | 更新内容 | 功能变更、描述优化 |
| 修复 | 纠正错误 | 错误修正 |
| 删除 | 移除内容 | 过时内容移除 |
| 重构 | 结构调整 | 文档重组 |
当目标 Skill 更新时，支持增量更新：
更新检测:
1. 计算 source_skill_hash
2. 与上次生成时对比
3. 如不一致，触发更新
增量更新策略:
├── 新增内容 → 追加到文档
├── 修改内容 → 更新对应章节
├── 删除内容 → 标记为过时
└── 结构变更 → 重新生成
| 版本 | 日期 | 更新内容 |
|------|------|----------|
| 1.0.0 | - | 初始版本 |
| 1.1.0 | 2026-05-12 | 第一次优化：完善工作流程、增强触发条件、添加验证机制 |
| 1.2.0 | 2026-05-12 | 第二次优化：增强示例生成规则、完善参数处理规范 |
| 1.3.0 | 2026-05-12 | 第三次优化：添加错误处理体系、质量保障机制、版本控制策略 |
共 2 个版本