Communitygithub.com

shimo4228/readme-writer

Claude Code 技能:编写与改进面向人类的 README——作为人类、搜索引擎和 AI 概览的唯一规范入口。偏向人类表面的技能,与 llms-txt-writer 对应。采用确定性结构检查与非评分整体性 LLM 审查(遵循 AKC ADR-0008 Code-LLM 分层原则)。

readme-writer 是什么?

readme-writer 是一个用于编写和优化 README 文件的 Claude Code 技能,专注于将 README 打造为人类(以及搜索和 AI 概要)的单一规范入口。它承认 README 是 LLM 在 grounding 路径(如粘贴仓库 URL)中唯一可依赖的表面,因此需要在“面向人类简洁直观”与“为 LLM 提供足够信息以复原项目”之间取得平衡。技能的核心原则是区分结构 lint(由代码决定,通过 `readme_lint.py` 执行)与语义审查(由 LLM 整体评估,但不输出分数)。它强制要求 README 必须包含一个“最小 LLM 可读基座”(identity 句、问题与对象、关键事实、一个具体示例等),且只允许使用 Mermaid 图(而非栅格图)以保证文本代理的可访问性。此外,技能规定了严格的行为边界:不触碰 `llms.txt`、`graph.jsonld`、长文博客或仓库元数据,这些均由其关联技能处理。

兼容平台✓Claude Code~Codex CLI✓Cursor✓Antigravity
npx skills add shimo4228/readme-writer

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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 是否虚荣semanticLLM 的整体审查

不创建基于研究值分数的 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 内部、仅链接目标 均不可接受):

  1. identity 句(开头的 1-2 句,可独立阅读):"X 是面向 {谁} 实现 {什么} 的 {类别}"
  2. 解决的问题 / 目标受众 / 差异化点
  3. canonical 事实:真实姓名、语言/技术栈/状态。研究/DOI 仓库 须包含 DOI + 引用方式(BibTeX / CITATION)+ 支撑词汇的 3-6 个核心概念定义
  4. 仅一个具体示例:代码仓库提供函数签名 + 最小可运行片段(不提供完整实现——会导致膨胀并诱发幻觉);研究仓库提供核心主张 + 2-3 个关键数值
  5. 指向深层文档的链接映射仅含指针。不要将承载关键功能的事实仅置于链接目标 / 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 个 H1
  • heading_levels — 标题层级不跳跃
  • alt_text — 所有图像都有 alt(硬性基座: 无 alt = 对 LLM 不可见)
  • local_link — 本地相对链接/图像 src 实际存在

warning(建议,不阻断门控) — 结构性可检测,但“是否真正有问题”属于判断,因此只针对表面。语义判断委派给 LLM 审查:

  • raster_diagram_hint — 文件名类似图表的栅格(architecture/flow/diagram/pipeline 等 .png/.jpg/.webp/.gif)→ 建议 Mermaid 化。排除 SVG、截图、logo
  • badge_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 正文分离)

相关技能