readme-generator skill 解析¶

readme-generator 是一套基于仓库证据生成或重构 README 的文档路由与质量约束框架。它的核心设计思想是：README 的目标是先判断项目是什么类型、面对什么读者、有哪些真实命令和配置、哪些徽章与章节真正有证据支撑，再把这些内容组织成可维护、可复查、对读者友好的 README，同时把证据映射、评分与降级状态留在助手响应里，不污染 README 正文。 因此它把受众与语言、项目类型路由、证据完整性、徽章检测、命令可验证性、导航、端到端示例和输出契约串成了一条明确流程。

1. 定义¶

readme-generator 用于：

• 为 service、library、CLI、monorepo 项目生成 README，并在满足条件时切换到轻量模式
• 按真实仓库形态选择合适模板，而不是套用统一骨架
• 从仓库证据提取命令、配置、结构说明、badge 与社区文件链接
• 重构已有 README，修复伪造 badge、错误配置、过时命令和内部流程标签
• 产出可维护的 README，并同时给出结构化证据映射与维护说明

它输出的不只是 README 内容，还包括：

• project type
• language
• template used
• evidence mapping
• 评分卡
• 降级状态
• badges added
• sections omitted
• 在证据不足时缺失项清单

从设计上看，它更像一个“README 生成治理框架”，而不是一个会写 Markdown 的提示词。

2. 背景与问题¶

这个 skill 要解决的，不是“模型不会写 README”，而是 README 任务天然有两个很容易失控的方向：

• 为了补全结构而凭空猜内容
• 为了交代过程而把内部工作流语言泄漏进 README 正文

如果没有明确约束，常见问题通常集中在 8 类：

readme-generator 的设计逻辑，就是先把“这是什么项目、该给谁看、哪些内容是真实可写的”说清楚，再把模板选择、证据使用、反模式约束和交付格式系统化。

3. 与常见替代方案的对比¶

先看它与几种常见做法的区别：

它的价值，不只是把 README 写得更像文档，而是把 README 生成从一次性的文案输出提升成基于仓库证据的文档工程流程。

4. 核心设计逻辑¶

4.1 先做 受众与语言门禁¶

readme-generator 的第一道门不是模板，而是先判断：

• 目标读者是 contributors、operators、API consumers 还是 end users
• 输出语言是 Chinese、English 还是 bilingual

这一步很关键，因为 README 的顺序、口吻和 section 取舍，本质上都受读者影响。一个公开项目的 README 应该先说明价值和快速开始；一个内部维护型 README 则可以更强调命令与结构。skill 因此默认把顶层 README.md 视为“用户首页优先、维护者参考其次”，除非用户明确要求内部型 README。

4.2 项目类型路由 是整个 skill 的结构中轴¶

这个 skill 会先把仓库主形态分类为：

• service/backend app
• library/SDK
• CLI tool
• monorepo

再决定应该走哪套模板与 section 排布。lightweight 在这里不是和前四类并列的主类型，而是一种附加模式：当仓库满足 lightweight 触发条件中的任意 2 条时，skill 会切换到更克制的 section 组合。

这是一个核心设计决策，因为 README 结构不是抽象审美问题，而是和仓库形态直接绑定。service 需要 Quick Start、Configuration、Testing、Project Structure；library 需要 Installation、Quick Usage、API Overview；CLI 更依赖 Commands and Flags、End-to-End Example；monorepo 则要控制结构视图的粒度，避免把整棵树倾倒进 README。

评估也说明了这一步的重要边界：项目类型路由本身并不是 skill 最大的独有增量，因为基础模型在测试里也能大致判断 service 和 CLI；但它仍然是后续 badge、section、示例与维护规则成立的前提。

4.3 “证据完整性门禁”必须放在写作前¶

readme-generator 要求在起草前至少确认：

• 至少一个 entrypoint
• 已判断项目类型
• 已找到命令来源

并优先运行 scripts/discover_readme_needs.sh。

这层设计的价值，在于 README 的最大风险从来不是“写少了”，而是“写多了，但多出来的是猜的”。discovery script 会确定性扫描：

• cmd/、pkg/、internal/、apps/、packages/
• go.mod、package.json、pyproject.toml、Cargo.toml
• Makefile
• .github/workflows/*
• .env.example
• 社区文件
• 现有 README.md

除此之外，它还会补充：

• go.work、Docker 相关信号、config 目录等仓库形态信息
• license type、quality tools、repo visibility / private 状态
• READY / DEGRADED verdict
• lightweight_candidate 之类后续路由所需信号

也就是说，它先把“仓库里客观存在什么”拉成事实表，再决定 README 该写什么。这个顺序，是它在当前评估中稳定压制伪造内容的重要原因之一。

4.4 宁可写 Not found in repo，也不补全常见答案¶

skill 的 Core Rule 非常明确：如果关键信息缺失，就写 Not found in repo，而不是猜。

这是整个 skill 最重要的设计纪律之一。评估里 without-skill 在重构场景中引入了新的伪造内容：

docker pull acme/notification-svc:latest

仓库里并没有 Docker 相关证据，但基础模型仍然倾向于用“Go 服务通常会这样部署”的通用知识补洞。readme-generator 正是针对这种风险设计的。它要求每个非平凡 section 都能追溯到具体文件，因此缺证据时宁可承认未知，也不追求“看起来完整”。

4.5 徽章检测 Gate 是 Mandatory¶

这个 skill 把 badge 检测列成强制步骤。在强制门禁里，它必须先检查：

1. CI
2. Coverage
3. 语言 version
4. License

在更完整的 Badge Strategy 里，skill 还会在有证据时继续考虑 Release/tag badge。

这种设计很有针对性，因为 README badge 是最容易“看起来合理、实际上乱写”的区域。很多 README 会顺手加 Codecov、Downloads、Release badge，但仓库根本没有对应配置或可推导 URL。skill 通过分层 badge 证据检测，把 badge 从装饰元素变成了可验证元数据。

评估中这条规则的效果非常明显：with-skill 在 3 个场景里都稳定产出了 CI + Go version + License badge，而 without-skill 虽然也会加 CI badge，但不会稳定补足 Go version 和 License。

4.6 强制把 README 正文和过程报告分开¶

readme-generator 明确禁止在 README 正文中出现：

• Verified
• PASS/FAIL
• not verified in this environment
• “Commands are derived from the Makefile and have not been executed” 这类过程语句

这些信息只能进入助手响应中的输出契约、证据映射和评分卡。

这是个非常清楚的设计决策，因为 README 是给读者用的，不是给文档生成流程自证用的。把过程状态写进 README，会同时伤害：

• 用户体验
• 文档寿命
• 正文可读性

因此 skill 把“README 本体”和“生成过程的可审计信息”显式拆层。这个分层设计，是它区别于普通文档生成提示词的关键。

4.7 导航规则 和 ToC 规则会写得这么细¶

这个 skill 对长 README 的导航要求非常明确：

• README 足够长时需要 ToC
• ToC 不能膨胀
• ToC label 必须和 ## heading 完全一致
• contributor-only sections 默认不进 ToC

很多 README 不是内容不够，而是结构不可浏览。这个 skill 把导航单独规则化，就是在解决“长文档的可用性问题”，而不只是“内容是否齐全”。评估里的 CLI 场景也验证了这一点：with-skill 能稳定给出 7-10 项规模、标签与 heading 一致的 ToC，而 without-skill 会直接缺失导航。

4.8 端到端示例规则 对 CLI 特别重要¶

skill 明确要求：对于 CLI、generator、converter 这类项目，README 应优先给出至少一个端到端示例，说明：

1. 输入命令
2. 结果文件名、状态行或响应形态
3. 如果仓库里有证据，再给输出片段

这一步非常有价值，因为很多 README 只会列命令，不会告诉读者“执行后会得到什么”。而对 CLI 来说，输入和输出之间的桥接本来就是理解成本最高的部分。

更重要的是，这条规则又被 no-fabrication 约束住了：如果仓库里没有 sample output，就只能写“写到哪个路径”“会打印什么类型结果”，不能凭空造一个 JSON body。这也是为什么 with-skill 在 CLI 场景能补上端到端示例，同时不引入伪造输出。

4.9 Community and Governance Files 要单列规则¶

readme-generator 会专门检测：

• LICENSE
• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md
• CHANGELOG.md

这层设计看起来简单，但它解决的是 README 很常见的“只讲怎么跑，不讲怎么参与和怎么治理”的问题。评估也说明，这一项不一定总是 skill-only 差异，因为基础模型也可能引用到社区文件；但 skill 把它规则化之后，能让这类 section 更稳定地出现或被正确省略，而不是完全靠临场发挥。

4.10 输出契约、证据映射与维护说明¶

这个 skill 最有辨识度的地方之一，是它要求在 README 之外再交付三层结构化信息：

• 输出契约
• 证据映射
• Documentation Maintenance

这三层分别解决不同问题：

• 输出契约 说明本次 README 走了什么模板、是否发生降级、加了哪些 badge
• 证据映射 说明每个关键 section 对应哪些仓库证据
• 维护说明 说明仓库哪些变化会让 README 过期

评估里这也是最明显的 skill-only 差异：3 个场景里 with-skill 全部产出，without-skill 全部缺失。也就是说，readme-generator 的真正增量不仅是“写 README”，更是“让 README 的生成结果可审计、可维护、可复查”。

4.11 references 采用强条件加载¶

这个 skill 的 references 分层非常清楚：

• templates.md 用于新生成 README
• golden-*.md 只按项目类型加载对应文件
• anti-examples.md 与 checklist.md 主要用于重构
• command-priority.md 只在命令来源冲突时加载
• bilingual-guidelines.md 只在中文或双语场景加载
• monorepo-rules.md 只在 monorepo 场景加载

这说明它虽然是一个大 skill，但不是每次都把全部规则塞进上下文，而是把高频通用规则常驻，把高成本专项规则按场景启用。这种结构既解释了它为什么覆盖面广，也解释了它为什么在典型场景中仍能控制 token 成本。

4.12 Lightweight 模式 是必要设计 vs 简化版模板¶

这个 skill 不是对所有仓库都强行使用完整 README 模板，而是定义了轻量模式的触发条件；当其中任意 2 条满足时，就会切换到轻量模式。例如：

• 顶层功能目录少
• 没有部署/运维工作流
• 没有公开 API/SDK 面
• 目标读者主要是内部贡献者

这层设计很重要，因为 README 也会“过度设计”。如果一个小项目硬塞进 Architecture、Deployment、API、Security、Release 一整套 section，读者读到的不是信息丰富，而是噪声。轻量模式让 skill 能在“完整”与“克制”之间做出结构化选择。

5. 这个设计解决了哪些具体问题¶

结合当前 SKILL.md、discovery script、关键 references 和评估报告，可以把它解决的问题归纳为：

6. 主要亮点¶

6.1 它把 README 写作变成证据路由，而不是模板填空¶

这是整个 skill 最根本的升级之一。先看仓库事实，再决定写什么。

6.2 防伪造规则是最大亮点之一¶

很多 README 任务真正的风险不是漏写，而是为了“完整”而猜。readme-generator 通过 Not found in repo 和 evidence mapping 把这个风险正面制度化了。

6.3 README 正文与过程报告的分层很关键¶

它既保留了可审计性，又避免把 Verified、PASS/FAIL 之类内部语言写进最终文档。

6.4 badge、ToC 和端到端示例都被规则化了¶

这让 skill 的提升不只体现在“内容对不对”，也体现在“读起来是不是好用”。

6.5 维护说明 让 README 真正进入可维护状态¶

这不是一次性交付，而是给后续贡献者留下一套“代码变了，README 哪些地方要跟着变”的更新线索。

6.6 当前版本的真正增量，在 README 治理而不在 Markdown 能力¶

评估已经很清楚：基础模型在项目类型判断、修正明显错误、补一些 section 方面并不差；真正的差距在 输出契约、证据映射、Maintenance、防伪造、ToC 和 badge 纪律这些“文档治理层”。

7. 什么时候适合用，什么时候不该硬用¶

8. 结论¶

readme-generator 的真正亮点，不是它能写出一份语气顺滑的 README，而是它把 README 任务里最容易被忽略的工程判断系统化了：先识别读者和项目类型，再做仓库事实收集，再决定哪些 section、badge、命令和示例有资格进入 README，最后把证据映射、评分和维护触发条件以结构化方式留在 README 外部。

从设计上看，这个 skill 很清楚地体现了一条原则：高质量 README 的关键，不是把每个常见 section 都写出来，而是让每个写进去的 section 都有证据、有读者价值、并且在未来知道什么时候该更新。 这也是它特别适合 README 生成、重构和标准化任务的原因。

9. 文档维护¶

当以下内容发生变化时，这份文档应该同步更新：

• skills/readme-generator/SKILL.md 中的 生成前门禁、徽章检测、命令可验证性、结构策略、导航规则、端到端示例规则、输出契约 或 质量评分卡 发生变化。
• skills/readme-generator/scripts/discover_readme_needs.sh 中的项目类型检测、badge 证据发现、社区文件扫描或 degraded 判定逻辑发生变化。
• skills/readme-generator/references/templates.md、golden-*.md、anti-examples.md、checklist.md、command-priority.md、bilingual-guidelines.md 或 monorepo-rules.md 中的关键规则发生变化。
• evaluate/readme-generator-skill-eval-report.md 或 evaluate/readme-generator-skill-eval-report.zh-CN.md 中支撑本文判断的核心结果发生变化。

建议按季度复查一次；如果 readme-generator 的项目类型路由、证据映射 / 输出契约、或防伪造规则有明显重构，则应立即复查。

10. 相关阅读¶

• skills/readme-generator/SKILL.md
• skills/readme-generator/scripts/discover_readme_needs.sh
• skills/readme-generator/references/templates.md
• skills/readme-generator/references/anti-examples.md
• skills/readme-generator/references/golden-examples.md
• evaluate/readme-generator-skill-eval-report.md
• evaluate/readme-generator-skill-eval-report.zh-CN.md