1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | md-document-alirezarezvani-claude-skills |
| 作者/维护者 | Alireza Rezvani |
| 来源链接 | https://github.com/alirezarezvani/claude-skills/tree/main/markdown-html/skills/md-document |
| 许可证 | MIT（GitHub API 获取） |
| GitHub Stars | 24,359（合集仓库整体数字，来自 GitHub API；不代表本技能自身热度） |
| Forks | 3,425（GitHub API） |
| 最新版本 | 2.10.1（SKILL.md front matter 自带版本号，2026-06-02 发布） |
| 安装方式 | 见第 10 章，支持 Claude Code 插件市场 / 手动复制 / Codex / OpenClaw / Hermes 多渠道 |
2. 功能介绍与亮点
md-document 把长篇 Markdown（技术方案、RFC、报告、说明文档）转换成单文件、轻交互的 HTML，内置粘性侧边栏目录（TOC）、全文搜索过滤、滚动高亮（scrollspy）、代码块一键复制。转换流程由三个纯标准库 Python 脚本串联完成：markdown_parser.py（Markdown → JSON AST）→ html_renderer.py（AST → HTML）→ interactivity_injector.py（注入交互脚本），不依赖任何前端构建工具链，产物是可直接双击打开、可邮件分享的单个 HTML 文件。
亮点：
- 零外部依赖：唯一的外部资源是 Google Fonts 与 Prism.js 的 CDN 引用（用于渲染字体与代码高亮），HTML 之外不联网、不上传数据。
- 品牌一致性：读取同域下 design-system 技能生成的 12 个 CSS 变量（主色、字体、圆角等），产出风格统一、通过 WCAG 2.2 AA 对比度校验的页面。
- 明确的拒绝逻辑：输入低于 100 行、或未完成一次性的品牌设置时会主动拒绝并提示原因，避免生成半成品。
- 设计有据可查：SKILL.md 附带的“追问清单”逐条引用 Tufte《Envisioning Information》、NN/g 目录可用性研究、WCAG 2.2 等公开资料说明每个交互决策的依据。
3. 适用场景
所属分类：文档与办公自动化
适合需要把 Agent 生成或人工撰写的长篇 Markdown（架构方案、RFC、周报/复盘报告、产品说明书）快速变成一份可独立打开、带目录导航和搜索的网页文档的开发者与技术写作者——例如把一份多章节的技术方案发给非技术同事审阅，或把研究笔记整理成可分享的说明页。
4. 跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | 原生支持 | 仓库提供 /plugin marketplace add + /plugin install markdown-html-skills@claude-code-skills 一键安装 |
| Codex | 原生支持 | README 提供 npx agent-skills-cli add ... --agent codex 及 codex-install.sh 两条官方安装路径 |
| OpenClaw | 原生支持 | README 提供一行 bash <(curl ...) openclaw-install.sh 安装脚本 |
| Hermes Agent | 需适配 | 官方标注为 “BYO-sync tier”：需先本地运行一次 sync-hermes-skills.py 才能安装，格式仍是标准 SKILL.md，无需转换 |
5. 推荐理由
它是同域五个转换技能里通用性最强的一个——覆盖“把长文档变网页”这个最常见的场景，输出是不依赖任何服务器或构建步骤的单文件 HTML，安全边界清晰（纯本地文本处理、无联网上传、无需任何密钥），近期仍在维护，且四个目标 Agent 生态都有对应的官方安装路径，适合初中级用户直接上手。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 5 | 个人开发者出品（非官方/非公认权威机构）；所属仓库是数百个技能共享的合集，24,359 stars 是整个仓库的数字，并非本技能独有的热度信号；目前查无该子技能自身的独立第三方讨论或评价 |
| 可用性 | 8 | 完成一次性品牌设置后单条命令即可使用；三脚本流水线 + 参考文档齐全；所属功能域最近一次提交日期为 2026-06-10；无付费依赖 |
| 安全性 | 8 | 执行范围明确的本地 Python 脚本，无外发数据，License 清晰可审计（见下方检查清单） |
| 综合 | 7.0 | 三项均值 |
安全检查清单： ① Shell 命令：不执行任意 shell 命令，仅运行自带的 3 个 Python 脚本，权限范围限于读输入文件、写输出 HTML；② 联网外发：生成过程不联网，输出 HTML 仅静态引用 Google Fonts / Prism.js CDN（浏览器打开时才会加载，目标透明）；③ 凭据：不需要任何 API Key 或凭据；④ 可疑指令：未发现 prompt injection 或混淆代码；⑤ 作者信誉：个人开发者，无刷星或造假迹象，代码开源可审计；⑥ License：MIT，明确；⑦ 维护时间：所属功能域最近一次提交为 2026-06-10，内容为修复 11 处 P0 正确性缺陷。
7. 跟同类 Skills 相比的优势
同一仓库的 markdown-html 功能域下还有三个姊妹转换器和一个共享的品牌配置技能，彼此按输入内容类型分工：
| Skill | 定位 | 与 md-document 的差异 |
|---|---|---|
| md-slides | 把带 --- 分隔符的 Markdown 讲义转成单文件 HTML 幻灯片，支持演讲者模式与打印导出 PDF |
只处理结构清晰的分页内容，长文档、报告类输入会被拒绝并建议改用 md-document |
| md-review | 把带 diff 代码块与严重级别标注（[!BLOCKER] 等）的 PR 评审文档转成左右两栏 HTML 评审页 |
要求输入必须含 diff 块且显式指定审阅人，通用文档不适用 |
| design-system | 10 道问题的品牌设置向导，产出配色与字体的 CSS 变量供三个转换器复用 | 本身不产出最终文档，是转换器的前置配置工具 |
| markdown-html-orchestrator | 按内容特征自动路由到上述三个转换器之一 | 承担分发角色，不直接生成 HTML |
md-document 覆盖的是这一组技能里最通用的“长文档转 HTML”场景，不要求输入满足幻灯片分页或代码评审的特定格式，是四者中最容易直接套用到日常写作与文档整理的一个。
8. 用户评价
该技能目前在第三方平台（Reddit、Hacker News 等）尚无具名用户评价，所属仓库的官方文档站也未公布针对该技能的下载量或使用数据。
9. 其他补充
markdown-html 功能域的版本节奏：v2.10.0（orchestrator + design-system 基础设施，2026-05-29）→ v2.10.1（md-document，2026-06-02）→ v2.10.2（md-review，2026-06-03）→ v2.10.3（md-slides，2026-06-03）→ 2026-06-10 一次性修复 11 处 P0 正确性缺陷。五个技能共享同一套设计话语（引用 Tufte、NN/g、WCAG、Matt Pocock 的“追问清单”写法），风格统一。
10. 安装使用方式
- Claude Code：
/plugin marketplace add alirezarezvani/claude-skills后/plugin install markdown-html-skills@claude-code-skills（会连同 md-slides / md-review / design-system / orchestrator 一并安装） - 手动安装（通用）：
git clone https://github.com/alirezarezvani/claude-skills.git，将markdown-html/skills/md-document/整个文件夹复制到对应 Agent 的 skills 目录（Claude Code 为~/.claude/skills/） - Codex：
npx agent-skills-cli add alirezarezvani/claude-skills --agent codex，或克隆后运行./scripts/codex-install.sh - OpenClaw：
bash <(curl -s https://raw.githubusercontent.com/alirezarezvani/claude-skills/main/scripts/openclaw-install.sh) - Hermes Agent：克隆后运行一次
python scripts/sync-hermes-skills.py
安装后注意事项：首次使用前必须先完成一次品牌设置（/cs:design-system 或直接运行 onboard.py --defaults 走零配置默认值），否则转换会被主动拒绝；无需重启 Agent，设置完成后即可直接对 Markdown 文件触发 /cs:md-document <路径>.md。
11. 注意事项
- 仅支持 CommonMark 的一个子集：不支持嵌套列表、内嵌 HTML、脚注、定义列表；任务列表复选框会被渲染成纯文本。
- 输入低于 100 行时会被拒绝（作者认为短文档 Markdown 本身已经够用）。
- 一次性品牌设置是全域共享的前置步骤，不算重量级配置，但首次使用前必须完成。
- 作者为个人开发者而非厂商官方团队，长期维护的连续性弱于官方出品的技能，建议关注仓库后续更新。