| name | open-source-docs |
| description | 开源项目文档建设技能，用于为 GitHub / GitLab 等开源项目规划、重写和纠偏 README、docs、示例说明与文档命名。当用户提到开源项目 README、最佳实践文档、文档信息架构、中文友好化、图片接入、许可证说明、致谢、示例文档同步、文档命名与内容纠偏时，优先使用此 Skill。尤其在“文档写成了迭代过程说明”“README 不像正式开源项目门面”“图文资产没有接入”“英文过重不利于中文团队阅读”这类场景下必须触发。 |
开源项目文档建设 Skill
本 Skill 用于把一个项目的文档体系整理成更接近优秀开源项目的状态，而不是停留在“开发过程记录”或“本次迭代说明”。
目标不是单纯补几段文字，而是让项目同时具备：
- 对外门面清晰的根 README
- 结构稳定的 docs 文档体系
- 与实际产物一致的 examples 与操作说明
- 中文团队可读、开源社区也能理解的文档表达
- 图片、许可证、致谢、架构说明等资产被正确接入
重要提示：默认使用简体中文写作；命令、路径、接口名、协议名、类名等保留必要英文。
何时触发
当用户出现以下意图时，应优先调用本 Skill：
- “把 README 改成像优秀开源项目”
- “整理 docs 结构”
- “把文档从迭代说明改成正式文档”
- “把图片、示意图、架构图接进文档”
- “中文友好化全文档”
- “文档命名和内容语义不一致，帮我纠偏”
- “examples 不是最新产物，文档同步一下”
- “补许可证说明、致谢、贡献指引”
- “参考主流开源项目把文档重构一下”
工作原则
1. 把项目当成产品来写文档
README 是项目门面，不是开发日志。docs 是长期资产，不是一次性汇报材料。
2. 先做信息架构，再写正文
不要一上来改段落。先判断哪些内容应该进入：
- 根 README
- docs 首页
- 教程 / 指南类文档
- 参考类文档
- 架构 / 设计说明
- examples 目录说明
3. 保留项目已有的高质量资产
如果仓库已有图片、致谢、许可证说明、优秀段落或清晰结构，不要为了“重写”而清空它们。优先修复错位、缺链、命名漂移和表达不统一的问题。
4. 文档必须服务真实用户
至少要覆盖四类读者中的主要角色：
- 第一次进入仓库的外部读者
- 准备接入或试用的开发者
- 维护者或贡献者
- 中文语境下需要快速理解系统的内部团队
5. 文字要稳定，少写时态化内容
避免把正文写成“本次迭代新增了”“这次我们做了”。这类过程说明最多进入变更日志，不应占据 README 和长期文档主体。
标准执行流程
步骤 1：盘点现状
先检查这些内容：
- 根 README 是否像项目门面，还是像迭代记录
docs/ 是否有索引页、清晰分层和交叉链接docs/images/ 或其他图片目录是否存在未接入资产examples/ 是否与当前功能和命令一致- 是否已有许可证、致谢、贡献指南、行为准则
- 文档标题、文件名、正文语义是否一致
- 是否存在旧命名、旧命令、旧术语残留
如果用户要求“参考业界主流”，优先参考优秀开源项目常见结构，再落到当前仓库。
步骤 2：先定信息架构
优先形成以下判断：
根 README 通常承载
- 项目定位与一句话价值
- 核心能力
- 快速开始
- 主要接入方式或使用方式
- 文档导航
- 示例导航
- 许可证与致谢
docs 通常承载
- 架构、设计、部署、开发、测试、故障排查
- 面向特定入口或协议的指南
- 深入解释类内容
- API / CLI / 配置参考
examples 通常承载
- 最小可运行样例
- 与 README / docs 一致的目录结构
- 每类入口的使用示例
步骤 3：重写 README 为“开源项目门面”
根 README 至少检查以下部分：
- 项目标题、副标题和 Badge 是否准确
- 是否有一句话清楚说出项目是什么、解决什么问题
- 是否用最短路径告诉用户如何开始
- 是否给出主要能力、接入方式或场景
- 是否链接到核心文档与示例
- 是否保留许可证、致谢、贡献入口
写 README 时遵守以下约束：
- 优先用正式的项目介绍语气
- 保持段落短、扫描成本低
- 不把 README 写成需求评审纪要
- 不把 README 塞满实现细节
步骤 4：整理 docs 为稳定文档体系
处理 docs 时，优先按“入口页 + 专题页”组织：
docs/README.md 作为总索引- 关键专题单独成文
- 文档之间互相链接，避免孤岛
- 一篇文档只聚焦一个主题
如果发现“文档名与正文不一致”，要一起纠偏：
- 正文内容匹配文件名
- 文件名反映真实语义
- 被其他文档引用时，同步更新链接
步骤 5：接入图片、示意图和静态资产
如果仓库里已有图片或架构图：
- 找到它们最合适的承载位置，而不是只放在目录里
- README 放总览图、架构图、能力图更常见
- 专题文档放与正文直接相关的图
- 保证图片路径有效、渲染正常、上下文能解释图的意义
不要无说明地堆图。每张图都应该回答一个问题。
步骤 6：做中文友好化，但不要破坏技术准确性
中文友好化不等于全翻译。处理原则：
- 标题、说明、步骤、注意事项优先中文
- 命令、代码、接口路径、字段名保留英文
- 常见术语中英混用时，以中文解释配英文实体名
- 避免全文大段英文说明让中文团队难以快速扫描
步骤 7：同步 examples 与操作说明
如果 examples 不是最新产物：
- 先更新 examples，再更新文档引用
- README / docs 中的示例路径、命令、截图必须指向真实存在的产物
- 不要让文档展示旧命令、旧目录、旧接口
步骤 8：清理残留与命名漂移
必须主动扫描并处理：
- 旧命令名
- 旧能力名
- 旧术语
- 已废弃入口
- 与代码、示例、文档不一致的历史说法
如果清理会影响已有链接或使用方式，要同步修正文档引用。
步骤 9：最终自检
交付前至少检查：
- README 是否像正式开源项目首页
- docs 是否可导航
- 图片是否都真正接入
- examples 是否为最新
- 许可证、致谢、贡献入口是否保留
- 文档名与正文是否一致
- 中文说明是否足够友好
- 是否仍残留“本次迭代”“本轮改动”式过程表述
推荐交付结构
完成任务后，优先交付这些结果：
- 根 README
docs/README.md- 若干专题文档
examples/README.md 或分类说明- 必要时的文档重命名与链接修复
推荐文档骨架
README 常见骨架
# 项目名
一句话介绍项目定位与价值。
## 核心能力
## 快速开始
## 主要接入方式 / 使用方式
## 文档导航
## 示例
## 贡献
## 许可证
## 致谢
docs 首页常见骨架
# 文档中心
## 快速导航
## 概念与架构
## 接入与使用
## 开发与运维
## 参考资料
反模式清单
出现以下情况时，应判定文档质量不合格并主动修正：
- README 大篇幅描述“这次做了什么”
- 删除已有高质量内容却没有更好的替代
- 图片存在但没有在正文中接入
- examples 与实际产物不一致
- 文档文件名和正文主题不一致
- 全文只顾英文术语，中文读者难以快速理解
- 许可证、致谢、贡献说明被遗漏
- 根 README 过度技术化，首次访问者无法快速判断项目价值
输出要求
最终面向用户汇报时，至少说明：
- 新增或重构了哪些核心文档
- 是否做了图片接入、命名纠偏、中文友好化
- 是否同步了 examples 和入口说明
- 还有哪些风险或后续可选优化项
参考资料
需要更细的模板、检查表与写法提示时，继续阅读：
