readme-generator Skill 评审报告¶

评估框架: skill-creator 评估日期: 2026-03-19 评估对象: readme-generator

readme-generator 是一个面向仓库结构的 README 生成与重构 skill，用于为 service、library、CLI、monorepo 等项目产出可维护、基于证据的项目首页文档。它的三个主要亮点是：先做项目类型路由和模板选择，让 README 结构贴合真实仓库形态，而不是落入通用化套板；通过 Evidence Mapping、badge 检测和 no-fabrication 规则，把各 section 锚定到真实文件、命令和配置，减少凭空补全；以及提供结构化 Output Contract 和维护说明，让生成结果更易评审、更易长期维护，也更容易随着代码演进持续同步。

一、评估概览¶

本次评估从实际任务表现和 Token 效费比两个维度对 readme-generator skill 进行全面评审。设计 3 个递进复杂度的 README 生成/重构场景（Go 服务从零生成、Go CLI 工具生成、问题 README 重构），每个场景分别运行 with-skill 和 without-skill 配置，共 3 场景 × 2 配置 = 6 次独立 subagent 运行，对照 42 条 assertion 进行评分。

二、测试方法¶

2.1 场景设计¶

2.2 测试仓库结构¶

Eval 1 仓库 (/tmp/readme-eval/eval-repos/go-service): - cmd/api/main.go — entrypoint（handler → service → repository 分层） - internal/handler/user.go — 3 个 HTTP 端点（GET/POST /users，GET /users/:id） - .env.example — 5 个环境变量（DATABASE_URL、REDIS_URL、JWT_SECRET、LOG_LEVEL、PORT） - .github/workflows/ci.yml — GitHub Actions（运行 make ci，Go 1.23） - Makefile — 9 个 target，COVER_MIN=80，golangci-lint@v1.62.2 - LICENSE — MIT；Go 1.23，模块 github.com/acme/user-service

Eval 2 仓库 (/tmp/readme-eval/eval-repos/go-cli): - cmd/root/root.go — cobra root + 2 个全局 flag（--output/-o、--format/-f） - cmd/generate/generate.go、cmd/validate/validate.go — 2 个子命令 - Makefile — 4 个 target（build-schema-gen、test、lint、install） - .github/workflows/ci.yml、LICENSE（Apache 2.0）、CONTRIBUTING.md - Go 1.22，无 .env.example；无 sample output 文件

Eval 3 仓库 (/tmp/readme-eval/eval-repos/refactor-stale) — 预置问题 README： - 伪造 badge：Travis CI、Codecov、npm Downloads（repo 使用 GitHub Actions） - 错误配置列：DB_HOST/DB_PORT 等（.env.example 实为 POSTGRES_DSN/REDIS_ADDR 等 7 个变量） - 过时命令：go run main.go（Makefile 有 make run-server） - 内部标签：Testing 表格含 ✅ Verified / ⚠️ Not verified - 实际内容：.env.example（7 变量）、Makefile（9 target）、CONTRIBUTING.md、SECURITY.md、Go 1.24

2.3 执行方式¶

• 每个场景创建独立 Git 仓库并预置代码、go.mod、Makefile 等文件
• With-skill 运行先读取 SKILL.md，按技能工作流生成/重构 README
• Without-skill 运行不读取任何 skill，按模型默认行为完成同一任务
• 所有 6 次运行并行执行

三、Assertion 通过率¶

3.1 总览¶

3.2 Without-Skill 失败的 16 条 Assertion 归类¶

3.3 趋势：Skill 优势随场景复杂度递增¶

Eval 3 优势最大，因为重构场景要求在修复已知问题的同时主动发现并补充新 section（社区文件、维护说明），这类"扫描-补全"行为是 skill 工作流的固有步骤，without-skill 倾向于只修复明显问题而停止。

四、逐维度对比分析¶

4.1 Output Contract 与结构化报告¶

这是 Skill 独有的差异化产出，3/3 场景全部产出，without-skill 0/3。

实际价值： - PR review 时可核查每个 section 对应哪个文件 - sections_omitted 明确跳过原因，避免"为什么没有 X section"的疑问 - scorecard 分层（Critical/Standard/Hygiene）让 reviewer 快速定位质量问题

4.2 Documentation Maintenance 维护说明¶

Skill 的 Hygiene Tier H1 要求，3/3 场景全通过，without-skill 0/3。

With-skill Eval 1 输出示例：

实际价值：解决"README 与代码逐渐脱节"的维护痛点，让贡献者知道改了什么代码就该更新哪部分 README。

4.3 CLI 端到端示例与 No-Fabrication¶

Skill 的 End-to-End Example Rule 要求 CLI 工具提供"输入命令 → 输出描述"的完整示例，并明确禁止在无证据时伪造 JSON/YAML 输出体。

With-Skill（Eval 2）：

schema-gen generate --format json --output ./schemas ./internal/models
# → writes schema file(s) to ./schemas/

schema-gen validate ./schemas/models.json
# → prints validation result to stdout

Without-Skill（Eval 2）：只有命令示例，无 input→output 描述；通过 Usage section 的 Examples 展示命令变体，但读者无法预期输出是什么。

4.4 伪造内容防御¶

这是本次评估中 without-skill 最值得关注的失败：

Without-skill Eval 3 在修复旧伪造内容（Travis CI badge、DB_HOST 配置）时，主动引入了新的伪造内容：

## Installation
docker pull acme/notification-svc:latest

With-skill 的 Evidence Completeness Gate 明确要求"base every statement on repository evidence"，3/3 场景均未出现新增伪造。

4.5 Badge 策略¶

Skill 的 Badge Detection Gate 要求按 CI → Coverage → Language version → License 顺序扫描，最终 3 badge 组合（CI + Go + License）在三个场景中均稳定产出。Without-skill 只主动添加 CI badge，Go version 和 License 两类需要明确规则指引才能一致产出。

4.6 ToC 导航质量（CLI 场景）¶

With-skill Eval 2 的 ToC：

- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Commands & Flags](#commands--flags)
- [End-to-End Example](#end-to-end-example)
- [Project Structure](#project-structure)
- [Development Commands](#development-commands)
- [Contributing](#contributing)
- [License](#license)
- [Documentation Maintenance](#documentation-maintenance)

4.7 与 Claude 基础模型能力的边界¶

基础模型已具备的能力（Skill 无增量）¶

基础模型的能力缺口（Skill 填补）¶

五、Token 效费比分析¶

5.1 Skill 体积¶

readme-generator 是一个多文件 skill，SKILL.md 包含核心规则，参考资料按需加载。

典型加载场景（按 Load References Selectively 原则）：

5.2 Token 换取的质量提升¶

5.3 Token 分段效费比¶

将 SKILL.md 内容按功能模块拆分：

5.4 高杠杆 vs 低杠杆指令¶

高杠杆（~1,620 tokens → 直接贡献 11+ 条 assertion 差值）： - Documentation Maintenance（200 tok → 3 条） - Evidence Mapping（150 tok → 3 条） - Output Contract + Scorecard（600 tok → 3 条） - End-to-End Example + No-fabrication（220 tok → 1 条 + 防御） - Badge Detection（250 tok → 2 条） - Command Verifiability Gate（250 tok → 1 条 + 防御）

中杠杆（~750 tokens → 间接贡献）： - README Navigation Rule / ToC（200 tok → 1 条） - Anti-Example 1（200 tok → 防御性保障） - Structure Policy（350 tok → section 完整性）

低杠杆（~550 tokens → 0 条直接差值，本次未测试场景）： - Chinese/Bilingual Guidelines（加载 bilingual-guidelines.md，~271 tok）— 按需，未触发 - Monorepo Rules（加载 monorepo-rules.md，~421 tok）— 按需，未触发

参考资料（~2,500-5,200 tokens 按场景）： - golden-*.md 提供 README 结构模板（间接贡献 section 顺序和完整度） - templates.md 提供完整骨架（间接贡献项目类型路由一致性） - discover_readme_needs.sh 确定性扫描（间接贡献证据完整性）

5.5 Token 效率评级¶

5.6 与 go-makefile-writer Skill 的效费比对比¶

readme-generator 的 SKILL.md 约为 go-makefile-writer 的 2.4x，每 1% 通过率的 Token 成本约为 2.0x。考虑到 readme-generator 需要覆盖 5 种项目类型路由、多语言支持、重构与生成双模式，以及比 Makefile 生成更复杂的"证据驱动"约束体系，这个差距是任务复杂度差异的合理映射，并非效率低下。

六、综合评分¶

6.1 分维度评分¶

6.2 加权总分¶

七、改进建议¶

7.1 [P1] Project Structure 最小覆盖约束¶

问题：Eval 3 的 with-skill README 中 Project Structure 仅一行：

cmd/server/     # server entry point

缺少 internal/api/、internal/db/、pkg/cache/ 等目录，这些在 cmd/server/main.go 的 import 语句中有明确证据。

建议：在 Generation Workflow Step 1 (Discover) 中增加：扫描 entrypoint 的 import 路径以补充 internal/、pkg/ 层目录，并设置"Project Structure 至少列出 3 个有意义目录"的下限。

7.2 [P2] License Section vs Badge 优先级规则明确化¶

问题：SKILL.md 在 Community and Governance Files 中规定"LICENSE → Add License section or badge"，but 两者优先级不明确，导致不同场景产出不一致（有时只有 badge，有时只有 section）。

建议：明确优先级规则： - README > 80 行：添加 License badge 即可，不强制独立 section - README ≤ 80 行或面向公开仓库：badge + 独立 License section 同时保留

7.3 [P3] 增加更多评估场景¶

八、评估材料¶