前言¶

自己写的 Agent Skill 往往只有一份 SKILL.md：触发词、工作流和参数都写在里面，但团队或用户更需要一份结构固定、能直接阅读的中文「使用说明」。手工从 SKILL.md 抄章节、补表格、写示例，重复劳动多，格式也容易不统一。

下面介绍 SkillHub 上的社区 Skill @user_211e8f0b/skill-example-generator（页面名称：为 skill 提供中文使用示例的 skill）。它面向通用 SKILL.md 格式，自动解析源文件并生成结构化中文文档，也可在 Agent 对话里用自然语言触发。

这是什么¶

一句话定位：解析目标 Skill 的 SKILL.md，生成带固定章节的中文使用说明，默认写入目标目录下的 examples/使用说明.md。

• 坐标：@user_211e8f0b/skill-example-generator
• SkillHub 版本：1.5.0（community，发布者 user_211e8f0b）
• 分类：knowledge-management（SkillHub 元数据）
• 是否需要 API Key：否（requires_api_key=false）
• 简介（官方）：自动解析 SKILL.md，生成结构化中文使用说明文档

包内 SKILL.md 将本工具称为「Skill 中文使用示例生成器」，作者为马立波，许可 MIT，目标平台包括 Cursor、Claude Code 等；与 SkillHub 商店页上的对外名称略有不同，以安装后的包内容为准。

核心功能¶

以下能力来自 SkillHub 简介及包内 SKILL.md 的说明，均为已写明的行为，而非对目标 Skill 功能的评测。

1. 解析 SKILL.md：读取 frontmatter、章节结构、触发词、参数等；对路径、编码（UTF-8 / GBK）、破损 YAML 等按文档中的边界规则降级或报错。
2. 生成结构化中文文档：按模板输出简介、触发方式、功能说明、参数表、使用示例、常见问题、注意事项等章节。
3. 可执行生成器：提供 generate_readme.py（Python 3.11+，纯标准库），支持单 Skill、按名称搜索、批量生成与自检；产物 frontmatter 含 generator_version、source_skill_version、source_skill_hash 等字段，便于复现与校验。
4. Agent 内执行：无法运行脚本时，按包内「代理执行指令」用 Read / Glob / Write 完成同等流程，并做质量自检（QualityReport）。
5. 多语言输出（可选）：支持 zh / en / ja / ko 等语言参数；无翻译服务时正文可能保留中文并带 [原文] 标记，文档中已说明降级策略。

明确不做的事：只生成使用说明，不修改目标 Skill 的逻辑，也不保证目标 Skill 行为正确。

安装与启用¶

1. 安装 SkillHub CLI¶

若尚未安装，可按官方安装说明检查或安装：

command -v skillhub && skillhub --version

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

完整步骤见 SkillHub 安装与优先源配置。

2. 安装本 Skill¶

安装时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认装到 ./skills/ 可能不会被识别。

Cursor（skills 目录为 ~/.cursor/skills/）：

skillhub install skill-example-generator --namespace user_211e8f0b --dir ~/.cursor/skills/

Claude Code：

skillhub install skill-example-generator --namespace user_211e8f0b --dir ~/.claude/skills/

Codex（常见路径为 ~/.codex/skills/ 或项目下的 .agents/skills/，以你当前环境为准）：

skillhub install skill-example-generator --namespace user_211e8f0b --dir ~/.codex/skills/

也可在对话中让 Agent 按 SkillHub 页面提示，依据 https://skillhub.cn/install/skillhub.md 安装 @user_211e8f0b/skill-example-generator。

安装完成后，按你所用客户端的要求刷新或重启 Agent，使新 Skill 生效。

典型用法¶

方式一：在对话中触发¶

包内列出的主要触发词包括：「生成示例」「使用说明」「使用指南」「写文档」「生成文档」「创建示例文档」。

典型说法示例：

为 ./skills/my-skill 生成使用说明

执行逻辑（摘要）：确认目标路径 → 读取并校验 SKILL.md → 抽取元数据与章节 → 生成 examples/使用说明.md → 自检并反馈质量报告。目标目录需可读可写，且存在有效的 SKILL.md（含基本 frontmatter）。

方式二：命令行调用 generate_readme.py¶

进入本 Skill 安装目录后，可使用包内脚本（路径以你本机安装位置为准，例如 ~/.cursor/skills/@user_211e8f0b/skill-example-generator/）：

# 为指定路径的 skill 生成使用说明
python generate_readme.py ./skills/xlsx

# 按名称在 skillsRoot 下搜索并生成
python generate_readme.py xlsx --skills-root ./skills

# 批量生成（跳过已存在，失败隔离）
python generate_readme.py --batch --skills-root ./skills

# 自检：用当前 generator 真实重生成本仓库示例
python generate_readme.py --self-check

输出文件为 [目标]/examples/使用说明.md。包内 _demos/ 下附有若干第三方 Skill 的生成示例，可作格式参考。

适用场景与注意¶

适合谁

• 刚写完或改版 SKILL.md，需要配套中文用户文档的 Skill 作者。
• 维护多个 Skill，希望使用说明章节结构一致、减少手工排版。
• 需要在 Cursor / Claude Code 等环境中，用同一套流程批量产出 examples/ 文档。

使用前要满足

1. 目标路径下存在可读的 SKILL.md。
2. 对目标目录有写权限（用于创建 examples/）。
3. 命令行方式需 Python 3.11+。

限制与坑

• 复杂嵌套表格或非标准 Markdown 可能丢格式，生成后建议人工校对。
• 多语言正文依赖外部翻译服务；无服务时按文档降级，不要误以为已全部本地化。
• --strict 主要约束参数类型越界，不改变翻译降级行为。
• SkillHub 商店元数据中的下载量、评分会变动；撰写时以页面与 CLI 搜索结果为准（例如 skillhub search skill-example-generator）。

结尾¶

skill-example-generator 把「从 SKILL.md 到中文使用说明」收成可重复流程：对话触发或 generate_readme.py 均可，产物落在目标 Skill 的 examples/ 下，便于分发与版本对照。

• SkillHub 页面：https://www.skillhub.cn/skills/user_211e8f0b/skill-example-generator
• API 坐标入口：https://api.skillhub.cn/user_211e8f0b/skill-example-generator