人类可读文档生成助手 Skill 技能

技能简介

brownbull-human-docs（人类可读文档生成） 处理的是 AI 时代的新问题：项目里的 AI 上下文文件越写越详细，人反而读不完了。这个 Skill 以 ai 文件夹中的 AI 文档为源，自动在 docs 文件夹生成配套的人类可读版本——执行摘要、快速开始指南、Mermaid 可视化图和导航 README，并在源文档更新时同步刷新产出。技能在 Skillstore 质量评分 81 分（silver 档），riskLevel 为 safe，已完成安全审计（结论：全部静态发现均为 Markdown 代码围栏造成的误报，未发现可执行命令逻辑、凭证处理或提示注入），支持 Claude、Codex、Claude Code，采用 MIT 许可，累计浏览 390 次。

核心能力

• 镜像目录产出：读取 ai 文件夹内的 AI 文档，在 docs 文件夹生成结构一一对应的输出。
• 摘要文档：自动生成含执行摘要、关键要点、速查表的总结文档。
• 快速开始指南：产出带前置条件、操作步骤、验证方法、常见问题的上手文档。
• Mermaid 可视化：为架构、流程、时序、数据模式、状态生成 Mermaid 图集。
• 增量刷新：源 AI 文档变更时更新已生成的人类文档，带标记的手工增补内容会被保留。
• 导航维护：自动生成并维护 docs/README.md，把产出的文档串成可浏览的目录。

安装配置

1. 在项目目录执行 npx skillstore add brownbull/human-docs 完成安装。
2. 前置条件：仓库中必须已有足够详细的 AI 文档（ai 文件夹），该技能只做"转译"不做凭空创作。
3. 保持文件命名规范，让 docs 输出与 ai 源目录结构一一对应，便于增量刷新对位。
4. 需要人工保留的增补内容要打上明确标记，否则刷新时会被生成内容覆盖。

使用步骤

1. 生成摘要：指定某个 AI 源文档（如后端需求文档），让它在对应 docs 目录产出人类可读摘要。
2. 生成快速开始：基于规格文档产出五分钟上手指南，含前置条件、步骤、验证与常见问题。
3. 生成可视化图：针对工作流与数据流文档，生成概览图、数据流图、组件交互图等 Mermaid 图集。
4. 批量刷新：对整个目录执行刷新，保留带标记的手工增补，并重建 docs/README.md 导航。
5. 发布前复核：人工检查摘要与图表准确性后再对外分享。

适用场景

• 新人入职：让新工程师不读完全部 AI 上下文文件也能掌握架构全貌。
• 高管简报：把详细技术规格转成简洁摘要加图表，供规划与评审会使用。
• 开发实施支持：用快速开始指南帮开发者走通关键工作流、验证环境配置。
• 文档持续维护：AI 源文档更新后批量刷新人类文档，避免两套文档各自漂移。

适用人群

技术负责人、文档工程师、工程经理与需要做汇报的负责人、新加入项目急需上手的开发者，以及维护 AI 上下文文档体系的团队。

工作原理

该技能把 AI 文档视为唯一事实源，遵循"源在 ai/、产出在 docs/"的单向流水线：读取 ai 文件夹的目标文档后，按类型分流处理——摘要类产出执行摘要+要点+速查表，上手类产出前置条件+步骤+验证+排障，视觉类渲染 Mermaid 架构/流程/时序/模式/状态图；随后重建 docs/README.md 导航。刷新时以源文档差异驱动，带标记的人工增补跳过覆盖。使用边界也很清楚：源材料不清晰时不要生成图表、不要用本技能替代详细的 AI 上下文文档、改了产出必须回写源文档，官方建议所有生成的摘要与图表发布前都经人工审阅。

官方链接

• 技能主页：https://skillstore.io/skills/brownbull-human-docs
• 源码仓库：https://github.com/Brownbull/khujta_ai_business/tree/main/.claude/skills/human-docs
• 技能清单：https://skillstore.io/api/skills/brownbull-human-docs/manifest