当需要审计或重写仓库 README 时：让陌生开发者在 1…

对仓库 README 做证据驱动的审计与重写，使其成为能快速转化访客为试用者的落地页与路由器。

适用场景

解决思路

1. 先声明目标受众（个人开发者还是企业/采购评估者），写在评分卡顶部，后续所有判断都对照它检查；再确认 README 是否真是瓶颈：若流量尚可但 clone/访客比只有几个百分点，就是本技能要解决的问题；若访客本身就少，则是分发问题，应转向发布或分发工作而非改文案。
2. 收集证据，绝不凭记忆审计：完整读一遍 README 并记录自己困惑之处；运行 `scripts/readme-audit.sh <repo-root>` 做机械审计（影子副本、截断风险、标题树、章节数对比中位数 7、第一条可复制命令前的字数、徽章数、缺失 alt 文本、注册表不友好的原始 HTML、失效相对链接、占位文本、缺失内容类别）；读仓库周边（manifest 中的真实运行时要求、licence 文件、最近提交日期、开放 issue 量、示例是否真实存在）；若可联网，打开包注册表页面与代码托管渲染对比；若有持久记忆，复用已存的定位语句、受众定义与竞品列表。
3. 按评分卡打分：Band A 五项阻断检查（身份、安装真能跑、每条声明可验证、状态诚实、licence 可达），Band B 八项各 2 分；每项附证据（行号、引用句或命令输出）；在重写前先取得用户对诊断的认同。
4. 按「每小时投入回报」排序修复项，并同时说明三种排序：按工作量从小到大为 `status line == badge row > claim check > install path > differentiation paragraph > funnel restructure`；按价值从大到小为 `install path > differentiation paragraph > claim check > status line > funnel restructure > badge row`；按效率优先为 `status line > install path > claim check > differentiation paragraph > badge row > funnel restructure`。首轮默认做前三项；当冷读者因没滚动到足够远而答错、或审计起因是发布时，明确说明并提升 funnel restructure 的优先级。
5. 逐条核验 README 中的每个声明：命令、flag、默认值、环境变量、配置键、endpoint、导出符号、文件路径、版本要求，以及藏在动词里的行为断言（如「自动重连」「重试三次」「大小写不敏感」）；对照各自的真实来源（参数解析器、定义处、路由表、changelog）阅读而非回忆。
6. 实际运行安装路径：从干净状态（容器、全新虚拟环境、临时目录）开始，原样执行文档中的安装命令与第一个用法示例，记录每个缺口（未文档化的运行时版本、假定存在的系统包、必需的环境变量、与 README 不符的输出），把缺口补成显式前置条件或验证步骤后再次从干净状态运行，直到端到端无未文档化步骤。若无法执行命令，明确说明并请用户运行后粘贴输出，绝不凭检查标记通过。任何性能数字、兼容性矩阵、规模上限或「production ready」声明都必须有仓库内来源（benchmark 脚本、CI 矩阵、changelog），否则删除；无法验证时降级为可验证的表述并说明哪部分未确认。
7. 按读者正在「决定什么」而非代码形态选择骨架（库读者判断与现有代码库的契合、CLI 读者对比已装工具、框架读者做多年押注）；按读者能多快排除该项目来排序章节（认知漏斗，最宽且最具排除性的信息在前，非宽松 licence 应靠前）。写前先头脑风暴三个不同维度的候选一句话定位（机械上做什么、消除什么问题、让你不再用什么），附各自取舍与推荐让用户选择。逐节起草并逐节取得认同，每节：写能完整回答其问题的最短版本；把不可证伪的声明（「简单」「极快」「开发者友好」）换成可检查的内容（数字、依赖数、支持平台列表、具名取舍）；为生态外读者可能不懂的术语加链接；写明项目刻意不做什么、何时该用别的；超过一屏的内容移到链接文档并留一行指针（迁移而非删除）。社区健康内容（贡献指南、行为准则、安全披露、支持政策）不写进 README，各自独立成文件；但 licence 文件必须随仓库发布。成品文案先过一遍 humanizer 技能。
8. 校准徽章：保留第三方检查背书的 assessment signals（CI 状态、覆盖率、已发布版本、依赖新鲜度），删掉只表达意图的 conventional signals（如「PRs welcome」）；限制数量（默认上限 4，需为每个幸存者说明它回答读者什么问题）；维护者往往高估徽章价值，可用 Trockman 等对 294,941 个 npm 包的研究数据说服。
9. 修复仓库周边与渲染机制，按效率排序 `furniture > render mechanics > terminal demo`：先修 description、website link、topics、social preview（搜索列表与链接展开时唯一可见的文本）；再修渲染（给所有图片加 alt 文本、把指令/命令/决策相关事实从截图和动图移入文本、删除手写目录、检查相对链接从默认分支根目录可解析且原始 HTML 被剥离时仍可读、只保留一份渲染 README、monorepo 根 README 作为各包 README 的路由）；终端 demo 成本一周且需长期维护，仅当 CLI 或可视化工具（输出即产品）时提升到 render mechanics 之前，并用脚本生成而非手录；无可见输出的库直接删除 demo。
10. 仅当第 1 步声明了企业或采购受众时，才添加企业信任信号，按效率排序 `support expectation == release cadence > security policy > named adopters > governance and maintainer depth > supply-chain attestation > foundation affiliation`；默认做前三项（一个下午即可完成）；有具体交易在谈且有人问「还有谁在用」时加 named adopters；当项目被当作基础设施采用、或反复因基金会层级而丢单时，把 foundation affiliation 决策交给用户（其不可逆成本不是文档成本）。被用户上限排除的信号直接删除，不要列为未来工作。
11. 重新打分：五项阻断检查全过且计分项至少 14/16（默认阈值，用户可说明理由调整并记录在报告中）；再做冷读者测试（5 个问题、60 秒、全对才通过），用真人或一个无仓库上下文的全新 agent 会话，每个错误答案映射到具体检查项。若有持久记忆，存下商定的一句话定位、受众定义、竞品列表与最终得分。
12. 后续追踪：记录上线日期，对比前后各一个完整周期并标注混杂因素，4-6 周后重测；优先追踪 support load（每月「怎么安装」「这是做什么的」issue 数）、conversion rate（clone 或下载除以独立访客）、contributor conversion（一个季度后再看）；完全放弃 stars 指标（只增不减，无法显示回归）。若 clone 上升但贡献者数不变，是贡献路径坏了而非 README 问题。
13. 避免常见失败模式：先诊断再重写（评审模式下未经要求不重写）；不要为显得严肃而堆章节（5-12 节、中位数 7，单用途项目 4 节即完整）；不要用营销腔（无证据的最高级会降低信任）；不要只审计一个渲染目标；不要编造状态（「production ready」「久经考验」或未经用户确认的用户数）；不要先做最便宜的修复（徽章行最快但几乎最没价值）。
14. 拒绝传播三条无出处的民间统计：「详细 README 的仓库贡献多 50%」「star 历史图提升约 15% star 转化」「62% 的头部仓库有 GIF 演示」；用户引用时说明其无出处。只承诺项目被更好地评估，绝不承诺百分比提升。

适用边界 · 注意事项

• 用户真正的问题是文档站、入门页、贡献路径、发布说明、发布活动或个人 profile README 时——应转交对应技能，而不是把 README 撑大来覆盖。
• 当代码托管流量数据显示访客本身就很少时——这是分发问题而非文案问题，应转向发布或分发工作。
• 在评审模式下，除非用户明确要求，否则不要重写。
• 当用户上限（时间、预算、法律许可）排除了某项修复时，直接删除该项，不要列为未来工作。