readme-writer — 人間向け README スキル
人間に向けた README を書く・改善するスキル。llms-txt-writer が AI 専用サーフェスを担うのに対し、本スキルは 人間サーフェスの単一正準入口を担います。
加えて重要な事実:README は、グラウンディング経路(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 貼り付け / 検索グラウンディングでは README が確実に前提にできる唯一の面」です。別経路(検索インデックスが他ファイルを既にチャンク済み / README からのリンク追跡 / GitHub コネクタ・API でのファイルツリー露出 / 事前学習由来の知識)も存在します。結論が最も強いのは匿名ライブウェブグラウンディングと直接ランディング fetch です。逆に ルーティング型コーディングエージェント(Claude Code / Cursor 等)は llms.txt をオンデマンドで読むため、llms.txt はエージェントチャネルの保険として依然有効です——ただし AI 検索の入口ではありません。
なぜ「構造 lint」と「ホリスティックレビュー」を分けるのか
README 品質には 2 種類のプロパティが混在します。Code-LLM レイヤリング(構造はコードが 100% 精度で所有、意味は LLM が所有)に従い所有者を分けます。判定軸は when-code-when-llm: 「同じバイト列が文脈で違う意味になりうるか?」
| プロパティ | 例 | 種別 | 所有者 |
|---|---|---|---|
| 構造的 | H1 数 / 見出しレベル / alt-text 有無 / ローカルリンク解決 / ラスター図ファイル名 / バッジ数 / details 内の DOI 等 / H1 直後の散文行 | structural | コード(readme_lint.py) |
| 意味的 | リードが人を掴むか / 価値提案の明快さ / README のみで LLM が復元できるか / 物語の流れ / バッジが vanity か | semantic | LLM のホリスティックレビュー |
README に研究値ベースの数値スコアは作りません。llms.txt のセクション比率(ski-ramp 等)は LLM 引用研究で検証された決定論的信号ですが、README の「良い入口か」は意味的判断であり同等の決定論的知見がありません。entity density 等の AI サーフェス指標を人間 README に持ち込むのはアンチパターンです。
ただし「構造的 AI 可読性」は積極採用する(両面ルール)
「AI サーフェス指標を持ち込まない」は半分です。原則は 「アイデアがどう伝わるかは最適化してよい(強度に上限なし)。アイデアが何であるかは決して曲げない」 です。
- 採用(強度無制限): 見出し階層・情報設計・entity anchoring(著者名 / ORCID / DOI / canonical 識別子を散文に書く)・固有/造語語彙の anchoring・answer-first のリード・at-a-glance の表。これらは人間にもグラウンディング経路の LLM にも効く収束ゾーンです。
- 禁止: キーワードスタッフィング・水増し属性・疑問見出しファーミング・用語集投下・検索の報酬関数に合わせた主張の歪曲。引用やスターは成功指標ではありませんので、歪曲が奉仕する目標がそもそもありません。
最小 LLM 読み取り基盤(小さく・非交渉・肥大させない)
規則: README を LLM がそれ一枚だけ読んだ(llms.txt も graph.jsonld も読まれない)として、テキストだけでプロジェクトを復元できること。
基盤要素(散文 / markdown / Mermaid で。画像のみ・details の中のみ・リンク先のみは不可):
- identity 文(最初の 1-2 文・単独で読める): 「X は {誰}向けに {何をする} {カテゴリ} である」
- 解く問題 / 対象者 / 差別化点
- canonical な事実: 実名・言語/スタック/ステータス。研究/DOI リポジトリは DOI + how-to-cite(BibTeX / CITATION)+ 語彙を支える 3-6 個の core concept 定義
- 具体例を 1 つだけ: コードなら関数シグネチャ + 最小実行片(フル実装は載せない——肥大 + ハルシネーション誘発)/ 研究なら核となる主張 + 2-3 個の鍵となる数値
- 深部ドキュメントへのリンクマップはポインタのみ。load-bearing な事実をリンク先 /
llms.txt/graph.jsonldだけに置かない
最重要の落とし穴: 基盤は小さな非交渉コア。「削るな・再構造化せよ」を効かせすぎると、Mermaid / details / 基盤節に情報が温存され、README が偽装
llms-full.txtに肥大します。人間の目標は短くでした。基盤以外は容赦なく削るか relocate する(→ length budget)。
graph.jsonld / llms.txt を README から作る場合、README 散文を構造ソースにしないこと。識別子・グラフ辺は CITATION.cff / .zenodo.json / frontmatter の小さな manifest から derive する(手書きの並行コピーはドリフトします)。
GitHub のメタ面(リポジトリ description / topics / social-preview / CITATION ファイル / release / package metadata)もグラウンディングに効く基盤の一部。README 本文では設定しない(gh repo edit / release-doi 側)が、チェックリストとして揃っているか確認します。
Visual-first(Mermaid 第一・ラスター最後)
「短く・視覚的に」の正しい読み替えは 「散文の壁を走査可能な構造に圧縮する」 です。散文を画像化するのではありません。そして 「Mermaid 第一」≠「何でも Mermaid」——まず 図にすべきか を絞ります。モバイル(狭幅)で潰れない・LLM が拾える形式を選びます。
形式の選択
| 中身 | 最適形式 | 理由 |
|---|---|---|
| 3 ステップの線形 / 単純な列挙 | 散文 / リスト / 小さな表 | 全デバイス(特にモバイル)で読める。図にする価値がない |
| 本当にグラフ形状(関係・多分岐・マトリックス) | Mermaid(TD 縦方向) | ソースがテキストで LLM も読める。縦スクロールはスマホで自然、横(LR)は潰れる |
| 大きい / 複雑な図 | コミットされた SVG(拡大・パン可)/ サブシステム分割 | 巨大 Mermaid はデスクトップでも上限に当たり、モバイルで潰れる |
| 実 UI / 実行結果 / 写真 | ラスター(PNG/JPG/WebP/GIF) | Mermaid で表現できないものだけ |
どの図にも一文のテキスト等価を必ず添える(ハードルール)。これが「人間にも LLM にも届く」を保証する本体: モバイルで図が潰れた人間・```mermaid フェンスを opaque code として読み飛ばす LLM 抽出器・スクリーンリーダを同時に救います。図はその上の視覚的ボーナスであって、情報の唯一の担い手にしません。
Mermaid の要点
- GitHub が theme-aware SVG にネイティブ描画。ソースはテキスト(diff 可能・~10 token/edge)で ピクセルを見られないテキストオンリークローラにも読めます。散文/グラフに埋もれた構造(concept matrix・phase binding・pipeline 段)を Mermaid 化すると短くなり情報密度が上がります。
- モバイル最優先で
TD(縦)。横長LRは狭幅で破綻しやすい。 - 描画上限は文字ベース(
maxTextSize既定 50,000)+ edge ベースで、ノード数ではありません(「50-100 ノードが限界」は俗説)。超えそうならサブシステム分割。特殊な Project README では描画されません。 - 抽出器が Mermaid を落とす可能性があるため、上のテキスト等価で意味を必ず別途担保します。
ラスター / その他
- ラスターは load-bearing な情報を担わせない。alt-text を必須(ハードフロア: テキスト経路は alt しか読まない = alt 無し画像は LLM に不可視。a11y だけの話ではありません)。
- ダーク/ライトは
<picture><source media="(prefers-color-scheme: …)"><img alt="…"></picture>。<img alt>は二重に load-bearing です。 - 画像アセットはリポジトリにコミットし相対パス参照。外部ホットリンク(camo 破綻)とインライン/アニメーション
<svg>/<embed>/<object>(GitHub がサニタイズ)を避ける。 - バッジは 2-4 個の高信号のみ(CI / version / license / 研究リポジトリは DOI)。vanity バッジを避ける。狭幅でバッジ段が嵩張らないよう数を絞る。
- CLI リポジトリ: asciinema → agg GIF + 一文キャプション。UI リポジトリ: スクリーンショット/GIF + alt-text。
稀な bespoke 図は Claude Artifacts / Claude Code の svg・diagram スキル でコミット可能な SVG を生成し
assets/に置く。
Length budget(語数目標は持たない)
語数目標は置かない(「500-1500 語の sweet spot」「visual README はスターが増える(GitHub 研究)」はいずれも捏造/無出典として棄却済み)。代わりに:
- above-the-fold(最初の 1 画面 = 30 秒で「自分向けか」を判断): 任意の hero → H1 → 一行タグライン(価値提案=最も確実に LLM に抽出される行)→ ≤4 機能バッジ → 基盤の事実 → copy-paste の quick start。深い rationale はこの後。
- 順序はリポジトリ種別で変わる: 「quickstart→rationale」はソフトウェア向け。論文 / データセット / 概念 / DOI エッセイリポジトリでは当てはまりません。固定順を強制せず、「identity + canonical facts が deep rationale より前」だけを守る。lint の
identity_leadは「リード文の存在」だけを構造的に見て順序は強制しない。 - 総量は 1 変数で決まる: 正準ドキュメントサイト / ADR が深部を吸収するか。深い「なぜ」/ 設計 rationale は ADR /
docs//llms-full.txt/ 収録論文に移し、README には一行ポインタ(Diátaxis の explanation-displacement)。これが「450 行の研究リポジトリ README」の直接の治療。 <details>は二次的なバルクのみ(オプション表・FAQ・トラブルシューティング・完全な用語集)。人間の視界を整理しつつ LLM には届く。だが基盤を入れない(primacy 喪失 + Ctrl+F 不可。raw-markdown 経路では読めるが、描画ページの要約器は折りたたみを de-prioritize しうる)。
ワークフロー(コードフィルター → LLM レビュー → 人間ゲート)
1. コードフィルター — readme_lint.py(決定論的・構造のみ)
uv run --directory ~/.claude/skills/readme-writer python -m scripts.readme_lint "$ARGUMENTS"
引数は README の絶対パス。--json で機械可読出力。exit code がコード所有ゲート(0=clean または warning のみ / 1=error severity あり / 2=not found・too large)。
検査項目(スコアでなく具体 issue。severity 2 段階):
error(ゲートを落とす・ハード構造)
single_h1— H1 はちょうど 1 個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・スクリーンショット・ロゴは除外badge_budget— バッジが多すぎ(既定 >6)。数のみ判定(vanity か否かは LLM)details_floor_leak—<details>内に DOI / BibTeX / CITATION トークン(基盤漏れの兆候。「真に基盤か」は LLM 判断)identity_lead— H1 と最初のセクションの間に散文のリード文が無い(順序は強制しない。H1 不在はsingle_h1が担当)doi_citation_pairing— DOI があるのに how-to-cite(Citation 節 / BibTeX /CITATION.cff)が無い(DOI を非研究リポジトリに強制しない——DOI がある時だけ発火)
2. LLM ホリスティックレビュー(ルーブリックとしてのレンズ・スコア無し・シグナルファースト)
lint が通ったら Claude が README をホリスティックに読み、次のレンズで具体所見 + 具体 diff を出す:
- 🚩 README-only recovery(旗艦・最高レバレッジ) — README のテキストだけを読み、(identity / 対象者 / 問題 / 差別化点 / 該当すれば DOI・引用 / 3-6 個の core concept / 例 1 つ / 次へのリンク) を復元できるかを確認。欠落を具体的に列挙(「対象者が書かれていない」等)。スコアは付けない。これは「最小 LLM-read フロア」の運用化そのもの。
- リードの What / Who / Why — 最初の画面で「何で・誰向けで・なぜ気にすべきか」が分かるか
- 人間フック / 価値提案 — 抽象語でなく具体で価値が言えているか
- 物語 / スキャナビリティ — 段落・見出し・リスト・Mermaid が人間に追えるか
- 短さの検証(最重要の逆方向チェック) — 基盤以外が relocate されているか。Mermaid / details / フロアに情報を温存して偽装
llms-full.txtに肥大していないか - ビジュアルの妥当性 — 図は Mermaid か(ラスターなら Mermaid 化 / テキスト等価があるか)。バッジは高信号か(vanity でないか)
- ファクト一致 — 主張が機械層(
llms.txt/graph.jsonld)と矛盾しないか →context-syncに委譲
スコアを付けない理由(シグナルファースト + スキャフォールド分解): 「次の行動を変える情報」だけを出す。リード: 6/10 は行動を変えません。「リードが誰向けか言っていない」が行動を変えます。出力は diff 形式で y/n 承認できる粒度に分割。author-reviewer separation のためレビューは実装者と別エージェントプロセスで回すのが望ましい(editor / essay-reviewer と同型)。
3. ファクト一致確認 → context-sync
README の事実が llms.txt / llms-full.txt / graph.jsonld と一致するか(クローキング回避)は 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 に判断させる / 意味的判断を regex で代用する(
when-code-when-llm参照) - AI サーフェスの数値指標(ski-ramp / entity density / 疑問見出しファーミング)を人間 README に流用する(可読性低下)
- 「ビジュアル優先」を散文の画像化と解釈する(ラスター図はテキストオンリー LLM に不可視 = 情報をエージェントから隠す。Mermaid を使う)
- 「削るな・再構造化せよ」を効かせすぎて偽装
llms-full.txt化する(基盤は小さく、上は容赦なく削る/relocate) - 機械層(
llms.txt/graph.jsonld)がバックアップする前提で README 基盤を薄くする(グラウンディング経路で読まれない) llms.txt/graph.jsonldを README 散文から derive する(ドリフト。manifest から derive)- 人間向けに事実を盛る / マネタイズ訴求を足す(authenticity 毀損 + 機械層との矛盾 = クローキング。梱包は変えても主張は変えない)
検証
cd ~/.claude/skills/readme-writer
uv sync --dev
uv run pytest tests/ --cov=scripts --cov-report=term-missing
fixtures/sample_clean.md(issue 0・Mermaid 図を使うベストプラクティス例)と fixtures/sample_issues.md(全 9 チェックを発火させる例)で基本挙動を確認できます。
関連
llms-txt-writer— AI サーフェスの対になる writer(研究値ベースのgeo_check.pyを持つ)。本スキルは人間サーフェス。when-code-when-llm— structural / semantic の判定軸context-sync— README ↔ 機械層のファクト一致 / ドリフト(ファクト検証はこちらに委譲)jsonld-knowledge-graph—graph.jsonld設計writing-ecosystem— 人間向け長文散文の orchestratorinspiration.md— 設計の出自・一次研究の provenance・外部エビデンスの出典(Portability のため SKILL.md 本文から分離)