readme-writer — 面向人类的 README 技能
编写和改善面向人类的 README。llms-txt-writer 负责 AI 专用表面,而本技能负责人类表面的单一规范入口。
额外重要的事实:README 是 grounding 路径(AI 搜索/通过仓库 URL 聊天)中 LLM 唯一能可靠依赖的表面。因此,README 必须在“面向人类简短视觉化”的同时,始终保留一个“LLM 仅凭 README 就能复原项目的微型信息基座”——这种平衡是本技能的核心挑战。
何时使用
- 创建或改进
README.md/README.ja.md - 调整仓库/项目的“人类首先着陆的页面”
- 修复现有 README 的“偏向机器但不完全适合人类”或“过于面向人类而 LLM 无法抓取核心”的问题
- 希望 README 简短、视觉优先,但不想丢失信息基座
不应使用的场景:
llms.txt/llms-full.txt/ FAQ 等 AI 专用文档(→llms-txt-writer)- 文章、随笔、博客等长文散文(→
writing-ecosystem) graph.jsonld的设计(→jsonld-knowledge-graph)
核心:人类的注意力 × LLM 的信息量
README 优化的真正对立面不是“面向人类的信息 vs 面向 LLM 的信息”。而是人类的注意力(简短、抓住重点、可扫描)× LLM 的信息(仅凭 README 就能复原项目)。两者收敛于相同的策略(见下文),因此并非权衡,而是通过设计同时实现。
README 是唯一确定会被读取的表面(但不是“唯一”的)
- AI 搜索/引用爬虫实际上不读
llms.txt(基于 2026 年的多个日志调查,绝大多数请求数为零,主要搜索供应商已官方声明不支持)。 graph.jsonld在直接 fetch 时被视为纯文本,不能替代 README 的事实(经过对比实验验证)。- 因此,不应因“机器层会兜底”而稀释 README 的内容。
但需校准的重要事实:“LLM 只读 README”这种说法过于绝对。正确的说法是:“在通用的粘贴 URL / 搜索 grounding 中,README 是唯一能可靠依赖的表面”。 其他路径(搜索索引已对其他文件分块、通过 README 链接追踪、GitHub connector/API 暴露文件树、预训练知识)也可能存在。结论最强烈的场景是匿名实时网页 grounding 和直接着陆页 fetch。反之,路由后的编码代理(如 Claude Code、Cursor)可以按需读取 llms.txt,因此 llms.txt 作为代理渠道的保险仍然有效——但并非 AI 搜索的入口。
为什么将“结构检查”与“整体审查”分开?
README 质量包含两种属性,它们相互混合。根据 Code-LLM 分层(结构由代码以 100% 精度负责,含义由 LLM 负责)分离所有者。判断依据来自 when-code-when-llm:“相同的字节序列是否因上下文而产生不同含义?”
| 属性 | 示例 | 类型 | 所有者 |
|---|---|---|---|
| 结构性 | H1 数量 / 标题层级 / alt-text 有无 / 本地链接可解析 / 栅格图文件名 / badge 数量 / details 内的 DOI 等 / H1 后的 prose 行数 | structural | 代码(readme_lint.py) |
| 语义性 | lead 是否吸引人 / 价值主张的清晰度 / 仅凭 README 能否被 LLM 复原 / 故事流程 / badge 是否虚荣 | semantic | LLM 的整体审查 |
不创建基于研究值分数的 README 评分。llms.txt 的章节比例(ski-ramp 等)是经过 LLM 引用研究验证的确定性信号,但“是否是好的入口”是语义判断,缺乏同等确定性的见解。将 entity density 等 AI 表面指标引入人类 README 是反模式。
但“结构化的 AI 可读性”会被积极采纳(两面规则)
“不引入 AI 表面指标”的说法只对了一半。原则是:“可以优化如何传达想法(强度无上限)。绝不扭曲想法的本质。”
- 采纳(强度无限制): 标题层级、信息架构、实体锚定(在 prose 中写入作者名/ORCID/DOI/canonical 标识符)、专有/自创词汇的锚定、答案优先的 lead、一目了然的表格。这些是同时面向人类和 grounding 路径中 LLM 的收敛区域。
- 禁止: 关键词堆砌、填充属性、疑问标题农场、词汇表投喂、调整主张以迎合检索的奖励函数。引用和 star 并非成功指标,因此扭曲本身就没有服务目标。
最小 LLM 可读基座(小型、不可协商、不膨胀)
规则: 当 LLM 仅阅读该 README 一份文件(既不含 llms.txt,也不含 graph)时,应能仅凭文本复原项目。
基座要素(须通过 prose / markdown / Mermaid 表达。仅图像、仅 details 内部、仅链接目标 均不可接受):
- identity 句(开头的 1-2 句,可独立阅读):"X 是面向 {谁} 实现 {什么} 的 {类别}"
- 解决的问题 / 目标受众 / 差异化点
- canonical 事实:真实姓名、语言/技术栈/状态。研究/DOI 仓库 须包含 DOI + 引用方式(BibTeX / CITATION)+ 支撑词汇的 3-6 个核心概念定义
- 仅一个具体示例:代码仓库提供函数签名 + 最小可运行片段(不提供完整实现——会导致膨胀并诱发幻觉);研究仓库提供核心主张 + 2-3 个关键数值
- 指向深层文档的链接映射仅含指针。不要将承载关键功能的事实仅置于链接目标 /
llms.txt/ graph 中
最重要的陷阱: 基座应该是小型的不可协商核心。“不要删除,要重构”如果使用过度,信息可能被保留在 Mermaid / details / 基座章节中,导致 README 膨胀成伪装的
llms-full.txt。人类的目标是简短。除基座外,毫不犹豫地删除或迁移内容(→ 长度预算)。
当从 README 生成 graph.jsonld / llms.txt 时,不要将 README prose 作为结构源。应从 CITATION.cff / .zenodo.json / frontmatter 的小型 manifest 中导出标识符和 graph 边(手工的平行复制会产生漂移)。
GitHub 的元数据面(仓库描述、topics、社交预览、CITATION 文件、发布版本、包元数据)也是 grounding 中有效的基座部分。这些不在 README 正文中设置(由 gh repo edit / release-doi 管理),但作为检查清单确认其完备性。
视觉优先(Mermaid 优先,栅格最后)
“简短、视觉化”的正确解读是**“将散文的墙壁压缩成可扫描的结构”**,而不是将散文图像化。而且 “Mermaid 优先”≠“什么都用 Mermaid”——首先判断是否需要图表。选择在移动设备(窄屏)中不崩溃、LLM 可拾取的格式。
格式选择
| 内容 | 最佳格式 | 理由 |
|---|---|---|
| 3 步线性流程 / 简单枚举 | prose / 列表 / 小表格 | 在所有设备(尤其是移动设备)上可读。不值得图表化 |
| 真正的 graph 形状(关系、多分支、矩阵) | Mermaid(TD 纵向) | 源码为文本,LLM 也可读。纵向滚动在手机上自然,横向(LR)会崩溃 |
| 大 / 复杂图表 | committed SVG(可缩放/平移)/ 子系统拆分 | 大型 Mermaid 即使在桌面上也可能达到上限,并在移动设备上崩溃 |
| 实际 UI / 运行结果 / 照片 | 栅格(PNG/JPG/WebP/GIF) | 仅当 Mermaid 无法表示时使用 |
任何图表都必须附上一句文本等价描述(硬性规则)。这保证了“同时触及人类和 LLM”:拯救移动设备上图表崩溃的用户、将 ````mermaid fence 视为不透明代码跳过的 LLM 提取器、以及屏幕阅读器。图表应是其上方的视觉奖励,而非信息的唯一载体。
Mermaid 要点
- GitHub 原生渲染为 theme-aware SVG。源码为文本(可 diff、约 ~10 token/边),对无法查看像素的纯文本爬虫也可读。将散落于散文/graph 中的结构(概念矩阵、阶段绑定、流水线步骤)Mermaid 化,能使其更短、信息密度更高。
- 移动优先,使用
TD(纵向)。横向LR在窄屏下容易崩溃。 - 渲染上限基于字符(
maxTextSize默认 50,000)和边,而非节点数(“50-100 节点是上限”是误解)。若接近上限,则进行子系统拆分。特殊项目的 README 可能不被渲染。 - 由于提取器可能丢弃 Mermaid,文本等价描述必须始终独立承载含义。
栅格 / 其他
- 栅格图不得承载关键功能信息。必须包含 alt-text(硬性基座:文本路径只读取 alt-text = 无 alt 的图像对 LLM 不可见。这不只关乎无障碍性)。
- 暗/亮模式使用
<picture><source media="(prefers-color-scheme: …)"><img alt="…"></picture>。<img alt>双重承载关键功能。 - 图片资源应提交到仓库并使用相对路径引用。避免外部 hotlink(camo 会失效)以及内嵌/动画
<svg>/<embed>/<object>(GitHub 会 sanitize)。 - badge 仅使用 2-4 个高信号 badge(CI / 版本 / 许可 / 研究仓库的 DOI)。避免虚荣 badge。限制 badge 数量以防窄屏下 badge 行堆积。
- CLI 仓库:使用 asciinema→agg GIF + 一句说明。UI 仓库:使用截图/GIF + alt-text。
罕见的定制图表可通过 Claude Artifacts / Claude Code 的 svg、diagram 技能生成可提交的 SVG 并放置于
assets/。
长度预算(不设定字数目标)
不设定字数目标(“500-1500 字最佳区间”“视觉 README 会增加 star(GitHub 研究)”均已因缺乏来源而被驳回)。取而代之:
- above-the-fold(首屏 = 30 秒内判断“是否适合自己”): 任意 hero → H1 → 一行 tagline(价值主张 = 最可能被 LLM 提取的行)→ ≤4 个功能 badge → 基座事实 → 可复制粘贴的 quick start。深度 rationale 在此之后。
- 顺序因仓库类型而异: “quickstart→rationale”适用于软件仓库。不适用于论文/数据集/概念/DOI 文章仓库。不强制固定顺序,仅坚持 “identity + canonical facts 必须位于 deep rationale 之前”。lint 中的
identity_lead仅结构性检查 “lead 句是否存在”,不强制顺序。 - 总量由 1 个变量决定:规范文档站点 / ADR 是否吸收了深层内容。将深层的“为什么”/设计 rationale 迁移至 ADR /
docs//llms-full.txt/ 已发表的论文,并在 README 中保留一行指针(Diátaxis 中的 explanation-displacement)。这直接解决了“450 行的研究仓库 README”。 <details>仅用于次要的大块内容(选项表、FAQ、故障排除、完整词汇表)。既整理人类视角,又能被 LLM 触及。但不要将基座放入其中(失去首屏优先性 + Ctrl+F 不可用。原始 markdown 路径可读,但渲染页面的摘要器可能对折叠内容降权)。
工作流程(代码过滤器 → LLM 审查 → 人工门控)
1. 代码过滤器 — readme_lint.py(确定性、仅结构)
uv run --directory ~/.claude/skills/readme-writer python -m scripts.readme_lint "$ARGUMENTS"
参数为 README 的绝对路径。使用 --json 输出机器可读结果。退出码为代码拥有的门控信号(0=干净或仅有 warning / 1=存在 error 严重级别 / 2=未找到或过大)。
检查项(非评分,而是具体问题,严重性分 2 级):
error(阻断门控、硬性结构)
single_h1— 恰好有 1 个 H1heading_levels— 标题层级不跳跃alt_text— 所有图像都有 alt(硬性基座: 无 alt = 对 LLM 不可见)local_link— 本地相对链接/图像 src 实际存在
warning(建议,不阻断门控) — 结构性可检测,但“是否真正有问题”属于判断,因此只针对表面。语义判断委派给 LLM 审查:
raster_diagram_hint— 文件名类似图表的栅格(architecture/flow/diagram/pipeline 等 .png/.jpg/.webp/.gif)→ 建议 Mermaid 化。排除 SVG、截图、logobadge_budget— badge 过多(默认 >6)。仅依据数量判断(是否为虚荣由 LLM 判断)details_floor_leak—<details>内包含 DOI / BibTeX / CITATION token(可能是基座泄漏的迹象。“是否真正属于基座”由 LLM 判断)identity_lead— H1 与第一个章节之间没有 prose lead 句(不强制顺序。H1 缺失由 single_h1 负责)doi_citation_pairing— 存在 DOI 但缺少引用方式(Citation 节 / BibTeX / CITATION.cff)(不强制非研究仓库添加 DOI——仅当 DOI 存在时触发)
2. LLM 整体审查(评估框架作为镜头·不评分·信号优先)
lint 通过后,Claude 会整体阅读 README,并使用以下镜头输出具体发现 + 具体 diff:
- 🚩 README-only recovery(旗舰、最高杠杆) — 仅阅读 README 的文本,检查是否能复原 (identity / 目标受众 / 问题 / 差异化点 / 若相关则包括 DOI、引用 / 3-6 个核心概念 / 1 个示例 / 指向下一处的链接)。具体列出缺失项(如“未描述目标受众”)。不评分。这是“最小 LLM 可读基座”的实际运作。
- Lead 的 What / Who / Why — 首屏是否能清楚传达“是什么、为谁、为什么在意”
- 人类钩子 / 价值主张 — 是否以具体而非抽象的措辞表达价值
- 故事性 / 可扫描性 — 段落、标题、列表、Mermaid 是否对人类友好
- 简洁性验证(最重要的反向检查) — 基座以外的内容是否已迁移。是否因在 Mermaid / details / 基座中保存信息而膨胀成伪装的
llms-full.txt - 视觉合理性 — 图表是否为 Mermaid(若为栅格,是否有 Mermaid 化方案 / 文本等价描述)。badge 是否为高信号(非虚荣)
- 事实一致性 — 主张是否与机器层(
llms.txt/graph.jsonld)矛盾 → 交给context-sync处理
不评分的原因(信号优先 + 支架消解): 仅输出“能改变后续行动的信息”。Lead: 6/10 不会改变行动。“lead 未说明目标受众”才会改变行动。输出应以 diff 格式呈现,并可拆分为 y/n 批准粒度。为实现作者-评审者分离,审查最好在实现者之外的不同代理进程中运行(与 editor / essay-reviewer 同理)。
3. 事实一致性检查 → context-sync
README 中的事实是否与 llms.txt / llms-full.txt / graph.jsonld 一致(避免 cloaking)由 context-sync 作为权威处理。本技能不重新实现。
4. 人工门控
diff 由人工批准后应用。
本技能不涵盖的内容(边界)
- 不编写
llms.txt/llms-full.txt(→llms-txt-writer) - 不设计
graph.jsonld(→jsonld-knowledge-graph) - 不进行跨表面的漂移检测/同步(→
context-sync/release-doi) - 不编辑文章/随笔(→
writing-ecosystem) - 不设置仓库的 description / topics / social-preview(由
gh repo edit/release-doi管理。本技能仅作为检查清单提示) - 不输出质量分数 / 等级 / 评分
反模式
- 仅给出数值分数而不提供具体建议(推荐器模式的陷阱)
- 将结构 lint 就能处理的项目委派给 LLM 判断 / 将语义判断用正则表达式代替(参见
when-code-when-llm) - 将 AI 表面的数值指标(ski-ramp / entity density / 疑问标题农场)应用于人类 README(降低可读性)
- 将“视觉优先”误解为将散文图像化(栅格图对纯文本 LLM 不可见 = 信息对代理隐藏。应使用 Mermaid)
- 过度使用“不要删除,要重构”导致伪装成
llms-full.txt(基座要小,其余毫不犹豫地删除/迁移) - 基于机器层(
llms.txt/ graph)兜底的假设而稀释 README 基座(grounding 路径不读取这些) - 从 README prose 派生
llms.txt/ graph(导致漂移。应从 manifest 派生) - 为迎合人类添加事实或套利诉求(损害真实性 + 与机器层矛盾 = cloaking。包装可以变,但主张不变)
验证
cd ~/.claude/skills/readme-writer
uv sync --dev
uv run pytest tests/ --cov=scripts --cov-report=term-missing
可使用 fixtures/sample_clean.md(0 issue、使用 Mermaid 图的最佳实践示例)和 fixtures/sample_issues.md(触发全部 9 项检查的示例)验证基本行为。
相关技能
llms-txt-writer— AI 表面的对应编写技能(拥有基于研究值的geo_check.py)。本技能是面向人类的表面。when-code-when-llm— structural / semantic 的判断依据context-sync— README ↔ 机器层的事实一致性/漂移(事实验证委托至此)jsonld-knowledge-graph—graph.jsonld设计writing-ecosystem— 面向人类长文散文的协调器inspiration.md— 设计起源、一次研究来源、外部证据来源(为实现可移植性,与 SKILL.md 正文分离)