Skill 中文说明生成器

自动为已安装的 Skill 生成专业、结构化的中文使用说明文档。

触发条件

当用户表达以下意图时激活此 skill：

单数 Skill 处理

• "为 [skill-name] 生成中文说明"
• "给 [skill-name] 添加中文文档"
• "把 [skill-name] 的说明翻译成中文"
• "创建 [skill-name] 的中文 README"
• "为 [skill-name] 写中文使用说明"
• "翻译 [skill-name] 的文档"
• "[skill-name] 中文文档"

批量处理

• "为所有 skill 生成中文说明"
• "批量添加中文文档"
• "给所有 skill 添加中文说明"
• "一键生成中文文档"
• "全部翻译成中文"

关键词触发

包含以下关键词组合时触发：

• "skill" + "中文" + "说明/文档/README"
• "生成" + "中文" + "skill"
• "翻译" + "skill" + "中文"

核心功能

1. 智能解析 - 自动读取并解析 SKILL.md 的 YAML frontmatter 和 Markdown 内容
2. 结构化生成 - 按照标准模板生成包含完整章节的中文文档
3. 批量处理 - 支持单个 skill 或全部已安装 skills 的批量生成
4. 命名规范 - 优先使用 README_CN.md，兼容 使用说明.md
5. 智能跳过 - 自动检测已存在的中文文档，避免重复生成
6. 质量检查 - 生成后自动验证文档完整性和格式正确性

标准工作流程

阶段 1：意图识别与参数提取

用户输入 → 提取 skill 名称 → 判断单数/批量 → 确认执行

步骤 1.1：解析用户输入

• 使用正则表达式提取 skill 名称（匹配引号内内容或特定位置）
• 识别批量关键词："所有"、"全部"、"批量"、"一键"
• 确认生成意图："生成"、"创建"、"添加"、"翻译"

步骤 1.2：验证 skill 存在性

• 扫描 .trae/skills/ 目录
• 匹配 skill 名称（支持模糊匹配）
• 返回匹配结果列表

步骤 1.3：确认执行范围

• 单数模式：确认目标 skill
• 批量模式：列出所有待处理的 skills
• 询问用户确认（可选）

阶段 2：内容读取与解析

步骤 2.1：定位 SKILL.md

路径格式：{skills-dir}/{skill-name}-{version}/SKILL.md
示例：.trae/skills/summarize-1.0.0/SKILL.md

步骤 2.2：解析 YAML Frontmatter

提取字段：

• name - skill 标识名
• description - 功能描述
• homepage - 主页链接（可选）
• metadata - 元数据（emoji、安装要求等）

步骤 2.3：解析 Markdown 内容

提取章节：

• 一级/二级标题
• 功能列表
• 使用示例（代码块）
• 参数表格
• 配置说明
• 注意事项

阶段 3：内容转换与本地化

步骤 3.1：翻译策略

• 保持技术术语准确性（如 API、CLI、JSON 等不翻译）
• 使用专业、简洁的中文表达
• 保留所有代码示例和命令原样
• 参数名、环境变量名保持英文

步骤 3.2：结构映射

阶段 4：文档生成

步骤 4.1：应用标准模板

# {Skill 名称} 使用说明

## 简介
{功能概述，1-2句话}

## 触发条件
{何时使用此 skill，bullet 列表}

## 功能特性
- {功能 1}
- {功能 2}
...

## 使用方法

### {场景 1 名称}
{场景描述}

{示例代码或命令}

### {场景 2 名称}
...

## 参数说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| {param1} | string | 是 | {description} |
...

## 配置说明

### 环境变量
- `{VAR_NAME}` - {说明}

### 配置文件
{配置文件路径和格式}

## 注意事项
- {注意点 1}
- {注意点 2}
...

步骤 4.2：格式规范化

• 统一使用中文标点（，。：；""）
• 代码块标明语言类型（bash、json、markdown 等）
• 表格列宽对齐
• 标题层级正确（# ## ###）

阶段 5：文件保存与确认

步骤 5.1：确定文件名

优先级：

1. README_CN.md（首选）
2. 使用说明.md（备选，当 README_CN.md 已存在时）

步骤 5.2：写入文件

• 路径：{skill-dir}/{filename}
• 编码：UTF-8
• 换行符：根据操作系统（Windows: CRLF, Unix: LF）

步骤 5.3：生成报告

单数模式：

✅ 已生成 {skill-name} 的中文说明
📄 文件路径：{filepath}
📋 内容概要：{简要描述}

批量模式：

📊 批量生成报告
================
✅ 成功：{count} 个
❌ 失败：{count} 个
⏭️  跳过（已存在）：{count} 个

详细列表：
- {skill-name}: ✅ 已生成
- {skill-name}: ⏭️ 已存在 README_CN.md
- {skill-name}: ❌ SKILL.md 不存在

输出规范

文件命名

• 首选：README_CN.md
• 备选：使用说明.md
• 避免覆盖：如果文件已存在，询问用户是否覆盖或创建备选

文档结构标准

1. 一级标题 - Skill 名称 + "使用说明"
2. 简介 - 1-2 句话概括功能
3. 触发条件 - 明确的激活场景（bullet 列表）
4. 功能特性 - 3-5 个核心功能（bullet 列表）
5. 使用方法 - 2-3 个典型场景，含代码示例
6. 参数说明 - 表格，四列（参数、类型、必填、说明）
7. 配置说明 - 环境变量、配置文件（如有）
8. 注意事项 - 2-3 条使用提示或限制

格式要求

• 标题：使用 # ## ### 层级
• 代码块：使用 ``` 包裹，标明语言
• 表格：使用标准 Markdown 表格语法
• 列表：使用 - 或 1. 2. 3.
• 强调：使用 粗体 或 代码
• 标点：使用中文标点（，。：；""''）

批量处理模式

执行流程

开始
  ↓
扫描 .trae/skills/ 目录
  ↓
获取所有 skill 目录列表
  ↓
遍历每个 skill
  ├─ 检查 SKILL.md 是否存在
  │   └─ 不存在 → 记录失败，跳过
  │
  ├─ 检查 README_CN.md 或 使用说明.md 是否存在
  │   └─ 存在 → 记录跳过，询问是否覆盖
  │
  └─ 生成中文文档
      └─ 记录成功
  ↓
生成汇总报告
  ↓
结束

跳过策略

• 已存在 README_CN.md → 跳过（或询问覆盖）
• 已存在 使用说明.md → 跳过（或询问覆盖）
• 不存在 SKILL.md → 跳过并记录错误
• Skill 目录损坏 → 跳过并记录警告

错误处理

SKILL.md 不存在

症状：目标 skill 目录中没有 SKILL.md 文件

处理：

• 提示用户该 skill 可能未正确安装
• 建议检查 skill 名称拼写
• 记录错误，继续处理其他 skills（批量模式）

内容解析失败

症状：SKILL.md 格式非标准，无法解析

处理：

• 尝试直接翻译原始 Markdown 内容
• 使用通用模板组织内容
• 提示用户文档结构可能非标准，建议手动检查

文件写入失败

症状：权限不足或磁盘空间不足

处理：

• 检查目录写入权限
• 尝试使用备选文件名（添加数字后缀）
• 提示用户检查磁盘空间

命名冲突

症状：README_CN.md 和 使用说明.md 都已存在

处理：

• 询问用户是否覆盖
• 或创建 README_CN_新.md
• 或跳过该 skill

最佳实践

翻译准则

1. 技术术语保留英文：API、CLI、JSON、URL、SDK 等
2. 命令和代码不翻译：保持原样，确保可执行
3. 参数名保持英文：如 --length、--model
4. 环境变量保持英文：如 OPENAI_API_KEY
5. 使用专业表达：避免口语化，保持文档专业性

内容组织

1. 重要信息前置：简介和触发条件放在前面
2. 示例要完整：提供可复制的代码示例
3. 表格要清晰：参数说明使用表格，一目了然
4. 注意事项不可少：提醒用户常见问题和限制

边界情况处理

空内容或极简 SKILL.md

场景：SKILL.md 只有 YAML frontmatter，没有实质内容

处理：

• 基于 description 生成简介
• 提示用户该 skill 文档不完整
• 生成基础框架，建议用户补充

超大 SKILL.md

场景：SKILL.md 超过 1000 行

处理：

• 提取关键章节（触发条件、使用方法、参数）
• 精简示例，保留核心内容
• 提示用户文档已精简

多语言混合

场景：SKILL.md 已包含部分中文

处理：

• 识别已有中文内容，避免重复翻译
• 统一语言风格
• 保持术语一致性

特殊字符和格式

场景：SKILL.md 包含 Mermaid 图表、HTML 标签等

处理：

• 保留原始格式标记
• 翻译说明文字
• 确保 Markdown 渲染正确

质量检查清单

生成文档后，自动检查以下项目：

• [ ] 一级标题格式正确：# {Skill 名称} 使用说明
• [ ] 包含所有必需章节（简介、触发条件、使用方法）
• [ ] 代码示例使用正确的语法高亮
• [ ] 参数表格格式正确（4 列，对齐）
• [ ] 使用中文标点符号
• [ ] 技术术语未错误翻译
• [ ] 无明显的语法或拼写错误
• [ ] 文档长度适中（不少于 20 行，不超过 500 行）

示例

示例 1：单数 Skill 处理

用户输入：

为 summarize 生成中文说明

处理过程：

1. 提取 skill 名称："summarize"
2. 定位目录：.trae/skills/summarize-1.0.0/
3. 读取 SKILL.md
4. 解析内容并翻译
5. 生成 README_CN.md

输出结果：

# Summarize 使用说明

## 简介
Summarize 是一个快速命令行工具，用于总结网页链接、本地文件和 YouTube 视频内容。

## 触发条件
- 需要快速了解网页内容时
- 需要总结 PDF、图片或音频文件时
- 需要提取 YouTube 视频要点时

## 功能特性
- 支持网页 URL 内容总结
- 支持本地文件（PDF、图片、音频）总结
- 支持 YouTube 视频内容提取
- 多种 AI 模型可选

## 使用方法

### 总结网页

summarize "https://example.com" --model google/gemini-3-flash-preview

### 总结本地文件

summarize "/path/to/file.pdf" --model google/gemini-3-flash-preview

### 总结 YouTube 视频

summarize "https://youtu.be/dQw4w9WgXcQ" --youtube auto

## 参数说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `--length` | string | 否 | 总结长度：short、medium、long、xl、xxl 或字符数 |
| `--model` | string | 否 | AI 模型，默认 google/gemini-3-flash-preview |
| `--max-output-tokens` | number | 否 | 最大输出 token 数 |
| `--json` | flag | 否 | 输出 JSON 格式 |

## 配置说明

设置 API 密钥环境变量：
- `OPENAI_API_KEY` - OpenAI API 密钥
- `ANTHROPIC_API_KEY` - Anthropic API 密钥
- `GEMINI_API_KEY` - Google API 密钥

## 注意事项
- 使用前请确保已设置相应的 API 密钥
- 默认使用 Google Gemini 3 Flash Preview 模型
- 对于被屏蔽的网站，使用 `--firecrawl always` 参数

示例 2：批量处理

用户输入：

为所有 skill 生成中文说明

处理过程：

1. 扫描 .trae/skills/ 目录
2. 发现 15 个已安装 skills
3. 检查每个 skill 的中文文档状态
4. 为 12 个缺失中文文档的 skills 生成
5. 生成汇总报告

输出报告：

📊 批量生成中文说明报告
========================

处理时间：2026-01-15 10:30:45
总计 Skills：15 个

✅ 成功生成（12 个）：
  - summarize → README_CN.md
  - docx → README_CN.md
  - xlsx → README_CN.md
  - pdf → README_CN.md
  - ...

⏭️  已存在，跳过（2 个）：
  - admapix（已存在 README_CN.md）
  - canvas-design（已存在 使用说明.md）

❌ 生成失败（1 个）：
  - custom-skill（SKILL.md 不存在）

所有中文说明文档已保存到对应的 skill 目录中。

示例 3：边界情况 - 已存在中文文档

用户输入：

为 summarize 生成中文说明

系统检测：发现 summarize-1.0.0/README_CN.md 已存在

处理：

⚠️ 检测到 summarize 已存在中文说明
📄 现有文件：.trae/skills/summarize-1.0.0/README_CN.md

请选择操作：
1. 覆盖现有文件
2. 创建备份后覆盖（重命名为 README_CN.md.bak）
3. 跳过，保持现有文件
4. 创建新文件（README_CN_新.md）

请输入选项（1-4）：

示例 4：边界情况 - SKILL.md 不存在

用户输入：

为 unknown-skill 生成中文说明

系统检测：未找到 unknown-skill 目录或 SKILL.md

处理：

❌ 无法生成中文说明

原因：未找到 unknown-skill 的 SKILL.md 文件

可能的原因：
- Skill 名称拼写错误
- 该 skill 未正确安装
- Skill 目录结构损坏

建议操作：
1. 检查 skill 名称拼写
2. 使用 "npx skills list" 查看已安装的 skills
3. 重新安装该 skill

版本历史

v1.0.0 (2026-01-15)

• 初始版本发布
• 支持单数和批量模式
• 完整的错误处理和边界情况支持
• 质量检查清单