readme-writer

スター1

フォーク0

更新日2026年7月25日 15:20

README やプロジェクトのトップページ（repo を開いた人が最初に見る入口）を書く・直すときに使う。こんな時に必ず呼ぶ — README が長い／文字の壁で読まれない→短く走査しやすくしたい、開いて数十秒で「何のプロジェクトで自分向けか」が伝わる入口にしたい、構成図・アーキ図を入れたい（PNG や架空図でなく Mermaid を勧める）、badge を貼りすぎたので整理したい、長い rationale や「なぜ」を docs/ に逃がしたい、研究・DOI repo の README を引用付きで読める長さにまとめたい。短く・視覚優先にしつつ、LLM が README 一枚で要点を復元できる情報フロアは残す。CLI でも UI でも研究 repo でも、日本語でも英語でも、新規作成でも既存改善でも対象。AI 専用ドキュメント（llms.txt / llms-full.txt 等）は対象外（→ llms-txt-writer）、記事・エッセイ等の長文 prose は → writing-ecosystem。

インストール

Codex または Claude でインストールこの Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。

ソース

shimo4228

shimo4228/readme-writer

GitHub リポジトリを開く Creator のリポジトリを見る

ダウンロード

readme-writer — Human-Facing README Skill

人間に向けた README を書く・改善するスキル。llms-txt-writer が AI 専用 surface を担うのに対し、本 skill は 人間 surface の単一正準入口を担う。

加えて重要な事実: README は、grounding 経路（AI 検索 / チャットに repo URL を貼る）で LLM が確実に前提にできる唯一の surface でもある。そのため README は「人間向けに短く・視覚的に」しつつ「LLM が README 一枚だけ読んでもプロジェクトを復元できる小さな情報フロア」を必ず残す——この両立が本 skill の中心課題。

When to Use

README.md / README.ja.md を新規作成・改善する
repo / プロジェクトの「人間が最初に着地するページ」を整える
既存 README が「機械寄りで人間に中途半端」/「人間向けに薄すぎて LLM が掴めない」のを直す
README を短く・視覚優先にしたいが情報フロアを落としたくないとき

使わない場面:

llms.txt / llms-full.txt / FAQ など AI 専用 doc（→ llms-txt-writer）
記事・エッセイ・ブログ等の長文 prose（→ writing-ecosystem）
graph.jsonld の設計（→ jsonld-knowledge-graph）

軸は「人間の ATTENTION × LLM の INFORMATION」

README 最適化の本当の対立軸は「人間向け情報 vs LLM 向け情報」ではない。人間の注意（短く・掴む・走査できる）× LLM の情報（README だけで復元できる）である。両者は同じ施策に収束する（後述）ので、トレードオフでなく設計で両取りする。

README は確実に読まれる唯一の surface（だが「only」ではない）

AI 検索 / 引用クローラは llms.txt を実質読まない（複数の 2026 ログ調査で大半がゼロリクエスト、主要検索ベンダーは公式に非対応表明）。
graph.jsonld は直接 fetch では plain text 扱いされ、README の事実の代替にならない（対照実験）。
ゆえに README に置いた情報を「機械層が backstop する」前提で薄くしてはいけない。

ただし重要な較正: 「LLM は README しか読まない」は強すぎる。正しくは「generic な paste-URL / 検索 grounding では README が確実に前提にできる唯一の面」。別経路（検索インデックスが他ファイルを既に chunk 済み / README からのリンク追跡 / GitHub connector・API でのファイルツリー露出 / pretraining 由来の知識）も存在する。結論が最も強いのは匿名 live web grounding と直接ランディング fetch。逆に routed coding agent（Claude Code / Cursor 等）は llms.txt を on-demand で読むので、llms.txt は agentic チャネルの保険として依然有効——ただし AI 検索の入口ではない。

なぜ「構造 lint」と「ホリスティック review」を分けるのか

README 品質には 2 種類の property が混在する。Code-LLM Layering（構造は code が 100% 精度で所有、意味は LLM が所有）に従い所有者を分ける。判定軸は when-code-when-llm: 「同じバイト列が文脈で違う意味になりうるか?」

property	例	種別	所有者
構造的	H1 数 / 見出しレベル / alt-text 有無 / ローカルリンク解決 / raster 図ファイル名 / badge 数 / details 内の DOI 等 / H1 直後の prose 行	structural	code（`readme_lint.py`）
意味的	lead が人を掴むか / 価値提案の明快さ / README-only で LLM が復元できるか / 物語の流れ / badge が vanity か	semantic	LLM のホリスティック review

README に研究値ベースの数値スコアは作らない。llms.txt のセクション比率（ski-ramp 等）は LLM 引用研究で検証された決定論シグナルだが、README の「良い入口か」は意味的判断であり同等の決定論的知見がない。entity density 等の AI surface 指標を人間 README に持ち込むのは anti-pattern。

ただし「構造的 AI 可読性」は積極採用する（two-sided rule）

「AI surface 指標を持ち込まない」は半分。原則は 「アイデアがどう伝わるかは最適化してよい（強度に上限なし）。アイデアが何であるかは決して曲げない」。

採用（強度無制限）: 見出し階層・情報設計・entity anchoring（著者名 / ORCID / DOI / canonical 識別子をprose に書く）・固有/造語語彙の anchoring・answer-first の lead・at-a-glance の表。これらは人間にも grounding 経路の LLM にも効く収束ゾーン。
禁止: keyword stuffing・水増し属性・疑問見出し farming・glossary 投下・retrieval の報酬関数に合わせた主張の歪曲。引用や star は成功指標ではないので、歪曲が奉仕する目標がそもそも無い。

最小 LLM-read フロア（小さく・非交渉・肥大させない）

規則: README を LLM がそれ一枚だけ読んだ（llms.txt も graph も読まれない）として、テキストだけでプロジェクトを復元できること。

フロア要素（prose / markdown / Mermaid で。画像のみ・details の中のみ・リンク先のみは不可）:

identity 文（最初の 1-2 文・単独で読める）: 「X は {誰}向けに {何をする} {カテゴリ} である」
解く問題 / 対象者 / 差別化点
canonical な事実: 実名・言語/stack/status。研究/DOI repo は DOI + how-to-cite（BibTeX / CITATION）+ 語彙を支える 3-6 個の core concept 定義
具体例を 1 つだけ: コードなら関数 signature + 最小実行片（フル実装は載せない——肥大 + hallucination 誘発）/ 研究なら核となる主張 + 2-3 個の鍵となる数値
深部 doc への link-map はポインタのみ。load-bearing な事実をリンク先 / llms.txt / graph だけに置かない

最重要の落とし穴: フロアは小さな非交渉コア。「削るな・再構造化せよ」を効かせすぎると、Mermaid / details / フロア節に情報が温存され、README が偽装 llms-full.txt に肥大する。人間の目標は短くだった。フロア以外は容赦なく削るか relocate する（→ length budget）。

graph.jsonld / llms.txt を README から作る場合、README prose を構造ソースにしない。識別子・graph 辺は CITATION.cff / .zenodo.json / frontmatter の小さな manifest から derive する（手書きの並行コピーは drift する）。

GitHub のメタ面（repo description / topics / social-preview / CITATION ファイル / release / package metadata）も grounding に効く floor の一部。README 本文では設定しない（gh repo edit / release-doi 側）が、checklist として揃っているか確認する。

Visual-first（Mermaid 第一・raster 最後）

「短く・視覚的に」の正しい読み替えは 「散文の壁を走査可能な構造に圧縮する」。散文を画像化するのではない。そして 「Mermaid 第一」≠「何でも Mermaid」——まず 図にすべきか を絞る。モバイル（狭幅）で潰れない・LLM が拾える形式を選ぶ。

形式の選択

中身	最適形式	理由
3 ステップの線形 / 単純な列挙	prose / list / 小さな表	全デバイス（特にモバイル）で読める。図にする価値がない
本当に graph 形状（関係・多分岐・matrix）	Mermaid（`TD` 縦方向）	ソースがテキストで LLM も読める。縦スクロールはスマホで自然、横（`LR`）は潰れる
大きい / 複雑な図	committed SVG（拡大・パン可）/ subsystem 分割	巨大 Mermaid は desktop でも上限に当たり、モバイルで潰れる
実 UI / 実行結果 / 写真	raster（PNG/JPG/WebP/GIF）	Mermaid で表現できないものだけ

どの図にも一文のテキスト等価を必ず添える（hard rule）。これが「人間にも LLM にも届く」を保証する本体: モバイルで図が潰れた人間・```mermaid fence を opaque code として読み飛ばす LLM 抽出器・スクリーンリーダを同時に救う。図はその上の視覚的ボーナスであって、情報の唯一の担い手にしない。

Mermaid の要点

GitHub が theme-aware SVG にネイティブ描画。ソースはテキスト（diff 可能・~10 token/edge）で pixel を見られない text-only クローラにも読める。散文/graph に埋もれた構造（concept matrix・phase binding・pipeline 段）を Mermaid 化すると短くなり情報密度が上がる。
モバイル最優先で TD（縦）。横長 LR は狭幅で破綻しやすい。
描画上限は char ベース（maxTextSize 既定 50,000）+ edge ベースで、ノード数ではない（「50-100 node が限界」は俗説）。超えそうなら subsystem 分割。special な Project README では描画されない。
抽出器が Mermaid を落とす可能性があるので、上のテキスト等価で意味を必ず別途担保する。

raster / その他

raster は load-bearing な情報を担わせない。alt-text を必須（hard floor: text 経路は alt しか読まない = alt 無し画像は LLM に不可視。a11y だけの話ではない）。
dark/light は <picture><source media="(prefers-color-scheme: …)"><img alt="…"></picture>。<img alt> は二重に load-bearing。
画像 asset は repo に commit し相対パス参照。外部 hotlink（camo 破綻）と inline/animated <svg>/<embed>/<object>（GitHub が sanitize）を避ける。
badge は 2-4 個の高信号のみ（CI / version / license / 研究 repo は DOI）。vanity badge を避ける。狭幅で badge 段が嵩張らないよう数を絞る。
CLI repo: asciinema→agg GIF + 一文キャプション。UI repo: スクショ/GIF + alt-text。

稀な bespoke 図は Claude Artifacts / Claude Code の svg・diagram skill で committable な SVG を生成し assets/ に置く。

Length budget（語数目標は持たない）

語数目標は置かない（「500-1500 語の sweet spot」「visual README は star が増える（GitHub 研究）」はいずれも捏造/無出典として棄却済み）。代わりに:

above-the-fold（最初の 1 画面 = 30 秒で「自分向けか」を判断）: 任意の hero → H1 → 一行 tagline（価値提案＝最も確実に LLM に抽出される行）→ ≤4 functional badge → フロアの事実 → copy-paste の quick start。深い rationale はこの後。
順序は repo 種別で変わる: 「quickstart→rationale」はソフトウェア向け。論文 / dataset / 概念 / DOI essay repo では当てはまらない。固定順を強制せず、「identity + canonical facts が deep rationale より前」だけを守る。lint の identity_lead は「lead 文の存在」だけを構造的に見て順序は強制しない。
総量は 1 変数で決まる: 正準 docs サイト / ADR が深部を吸収するか。深い「なぜ」/ 設計 rationale は ADR / docs/ / llms-full.txt / deposited paper に移し、README には一行ポインタ（Diátaxis の explanation-displacement）。これが「450 行の研究 repo README」の直接の治療。
<details> は二次的な bulk のみ（option 表・FAQ・troubleshooting・full glossary）。人間の視界を整理しつつ LLM には届く。だがフロアを入れない（primacy 喪失 + Ctrl+F 不可。raw-markdown 経路では読めるが、描画ページの要約器は折りたたみを de-prioritize しうる）。

Workflow（Code filter → readme-reviewer agent → 人間 gate）

1. Code filter — `readme_lint.py`（決定論的・structural only）

uv run --directory ~/.claude/skills/readme-writer python -m scripts.readme_lint "$ARGUMENTS"

引数は README の絶対パス。--json で機械可読出力。exit code が code-owned gate（0=clean または warning のみ / 1=error severity あり / 2=not found・too large）。

検査項目（スコアでなく具体 issue。severity 2 段階）:

error（gate を落とす・ハード構造）

single_h1 — H1 はちょうど 1 個
heading_levels — 見出しレベルを飛ばさない
alt_text — すべての画像に alt（hard floor: alt 無し = LLM に不可視）
local_link — ローカル相対リンク / 画像 src が実在する

warning（助言・gate を落とさない） — 構造的に検出するが「本当に問題か」は判断なので surface のみ。意味判断は LLM review に委ねる:

raster_diagram_hint — 図っぽいファイル名の raster（architecture/flow/diagram/pipeline 等の .png/.jpg/.webp/.gif）→ Mermaid 化を提案。SVG・スクショ・logo は除外
badge_budget — badge が多すぎ（既定 >6）。数のみ判定（vanity か否かは LLM）
details_floor_leak — <details> 内に DOI / BibTeX / CITATION トークン（floor 漏れの兆候。「真に floor か」は LLM 判断）
identity_lead — H1 と最初の section の間に prose の lead 文が無い（順序は強制しない。H1 不在は single_h1 が担当）
doi_citation_pairing — DOI があるのに how-to-cite（Citation 節 / BibTeX / CITATION.cff）が無い（DOI を非研究 repo に強制しない——DOI がある時だけ発火）

2. LLM review — `readme-reviewer` agent を起動（author-reviewer separation）

lint が通ったら readme-reviewer agent を起動する。実装者（本 skill を回している Claude）と別 agent プロセスでレビューを回すことで author bias の盲点を避ける（editor / essay-reviewer と同型）。レビュー基準の正本は agent 定義（~/.claude/agents/readme-reviewer.md）— lens の一覧だけ挙げると:

README-only recovery（最重要） — テキストだけでプロジェクトを復元できるか、フロア欠落の具体列挙
Lead の What / Who / Why
人間フック / 価値提案
物語 / scannability
短さの検証（偽装 llms-full.txt 化の逆方向チェック）
visual の妥当性（Mermaid / テキスト等価 / badge vanity）
lint warning の意味判断（badge_budget → vanity か、raster_diagram_hint → Mermaid 化すべきか等）

出力は数値スコアでなく 具体所見 + y/n 承認できる粒度の具体 diff（signal-first: Lead: 6/10 は行動を変えない、「lead が誰向けか言っていない」が行動を変える）。Overall Assessment（EXCELLENT / GOOD / NEEDS REVISION / MAJOR ISSUES）だけは chain の早期停止判断が消費するため verdict として出す。

Cross-model 並列（条件付き）: 公開 repo の README なら codex-review を readme-reviewer と並列起動してよい（脱相関レビュー）。その場合は prompt-driven モードで writing 観点の指示を渡す — scoped モードは Codex 組み込みのコード向けレビュー指示が走るため prose に不適。例:

/codex-review "Review the README changes as prose, not code: is the project recoverable from the README text alone, is the lead clear about what/who/why, is anything load-bearing hidden in images or collapsed sections?"

3. fact 一致確認 → `context-sync`

README の事実が llms.txt / llms-full.txt / graph.jsonld と一致するか（cloaking 回避）は context-sync が正本。本 skill では再実装しない。

4. 人間 gate

README 本文を提示して承認を取り、適用する。ここで人間が判断するのは文章の正しさではなく「この入口を公開物として引き受けるか」（README は公開・不可逆で、テキストが意図そのもの）。構造的な品質は Step 1 の readme_lint.py と Step 2 の readme-reviewer が既に持っている（rules/common/human-gate.md）。

What This Skill Does NOT Do（境界）

llms.txt / llms-full.txt を書かない（→ llms-txt-writer）
graph.jsonld を設計しない（→ jsonld-knowledge-graph）
cross-surface の drift 検出 / 同期をしない（→ context-sync / release-doi）
記事 / エッセイを編集しない（→ writing-ecosystem）
repo の description / topics / social-preview を設定しない（gh repo edit / release-doi 側。本 skill は checklist として提示するのみ）
品質スコア / grade / 評点を出さない

Anti-patterns

数値スコアだけ出して具体案なしで終わる（recommender 型の罠）
構造 lint で済む項目を LLM に判断させる / 意味的判断を regex で代用する（when-code-when-llm 参照）
AI surface の数値指標（ski-ramp / entity density / 疑問見出し farming）を人間 README に流用する（可読性低下）
「ビジュアル優先」を散文の画像化と解釈する（raster 図は text-only LLM に不可視 = 情報をエージェントから隠す。Mermaid を使う）
「削るな・再構造化せよ」を効かせすぎて偽装 llms-full.txt 化する（フロアは小さく、上は容赦なく削る/relocate）
機械層（llms.txt/graph）が backstop する前提で README フロアを薄くする（grounding 経路で読まれない）
llms.txt/graph を README prose から derive する（drift。manifest から derive）
人間向けに事実を盛る / マネタイズ訴求を足す（authenticity 毀損 + 機械層との矛盾 = cloaking。梱包は変えても主張は変えない）

Verification

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 図を使う best-practice 例）と fixtures/sample_issues.md（全 9 チェックを発火させる例）で基本挙動を確認できる。

readme-reviewer agent（~/.claude/agents/readme-reviewer.md）— 本 skill の Step 2 を担うレビュー agent。レビュー基準の正本
codex-review — 公開 README への cross-model 並列レビュー（prompt-driven モード）
llms-txt-writer — AI surface の対になる writer（研究値ベースの geo_check.py を持つ）。本 skill は人間 surface。
when-code-when-llm — structural / semantic の判定軸
context-sync — README ↔ 機械層の fact 一致 / drift（fact 検証はこちらに委譲）
jsonld-knowledge-graph — graph.jsonld 設計
writing-ecosystem — 人間向け長文 prose の orchestrator
inspiration.md — 設計の出自・一次研究の provenance・外部エビデンスの出典（Portability のため SKILL.md 本文から分離）

name	readme-writer
description	README やプロジェクトのトップページ（repo を開いた人が最初に見る入口）を書く・直すときに使う。こんな時に必ず呼ぶ — README が長い／文字の壁で読まれない→短く走査しやすくしたい、開いて数十秒で「何のプロジェクトで自分向けか」が伝わる入口にしたい、構成図・アーキ図を入れたい（PNG や架空図でなく Mermaid を勧める）、badge を貼りすぎたので整理したい、長い rationale や「なぜ」を docs/ に逃がしたい、研究・DOI repo の README を引用付きで読める長さにまとめたい。短く・視覚優先にしつつ、LLM が README 一枚で要点を復元できる情報フロアは残す。CLI でも UI でも研究 repo でも、日本語でも英語でも、新規作成でも既存改善でも対象。AI 専用ドキュメント（llms.txt / llms-full.txt 等）は対象外（→ llms-txt-writer）、記事・エッセイ等の長文 prose は → writing-ecosystem。
compatibility	Requires Python 3.11+ and uv. Developed and tested on Claude Code; portable to other Agent Skills-compatible agents.
user-invocable	true
origin	shimo4228

readme-writer — Human-Facing README Skill

人間に向けた README を書く・改善するスキル。llms-txt-writer が AI 専用 surface を担うのに対し、本 skill は 人間 surface の単一正準入口を担う。

When to Use

README.md / README.ja.md を新規作成・改善する
repo / プロジェクトの「人間が最初に着地するページ」を整える
既存 README が「機械寄りで人間に中途半端」/「人間向けに薄すぎて LLM が掴めない」のを直す
README を短く・視覚優先にしたいが情報フロアを落としたくないとき

使わない場面:

llms.txt / llms-full.txt / FAQ など AI 専用 doc（→ llms-txt-writer）
記事・エッセイ・ブログ等の長文 prose（→ writing-ecosystem）
graph.jsonld の設計（→ jsonld-knowledge-graph）

軸は「人間の ATTENTION × LLM の INFORMATION」

README は確実に読まれる唯一の surface（だが「only」ではない）

AI 検索 / 引用クローラは llms.txt を実質読まない（複数の 2026 ログ調査で大半がゼロリクエスト、主要検索ベンダーは公式に非対応表明）。
graph.jsonld は直接 fetch では plain text 扱いされ、README の事実の代替にならない（対照実験）。
ゆえに README に置いた情報を「機械層が backstop する」前提で薄くしてはいけない。

なぜ「構造 lint」と「ホリスティック review」を分けるのか

property	例	種別	所有者
構造的	H1 数 / 見出しレベル / alt-text 有無 / ローカルリンク解決 / raster 図ファイル名 / badge 数 / details 内の DOI 等 / H1 直後の prose 行	structural	code（`readme_lint.py`）
意味的	lead が人を掴むか / 価値提案の明快さ / README-only で LLM が復元できるか / 物語の流れ / badge が vanity か	semantic	LLM のホリスティック review

ただし「構造的 AI 可読性」は積極採用する（two-sided rule）

採用（強度無制限）: 見出し階層・情報設計・entity anchoring（著者名 / ORCID / DOI / canonical 識別子をprose に書く）・固有/造語語彙の anchoring・answer-first の lead・at-a-glance の表。これらは人間にも grounding 経路の LLM にも効く収束ゾーン。
禁止: keyword stuffing・水増し属性・疑問見出し farming・glossary 投下・retrieval の報酬関数に合わせた主張の歪曲。引用や star は成功指標ではないので、歪曲が奉仕する目標がそもそも無い。

最小 LLM-read フロア（小さく・非交渉・肥大させない）

規則: README を LLM がそれ一枚だけ読んだ（llms.txt も graph も読まれない）として、テキストだけでプロジェクトを復元できること。

フロア要素（prose / markdown / Mermaid で。画像のみ・details の中のみ・リンク先のみは不可）:

identity 文（最初の 1-2 文・単独で読める）: 「X は {誰}向けに {何をする} {カテゴリ} である」
解く問題 / 対象者 / 差別化点
canonical な事実: 実名・言語/stack/status。研究/DOI repo は DOI + how-to-cite（BibTeX / CITATION）+ 語彙を支える 3-6 個の core concept 定義
具体例を 1 つだけ: コードなら関数 signature + 最小実行片（フル実装は載せない——肥大 + hallucination 誘発）/ 研究なら核となる主張 + 2-3 個の鍵となる数値
深部 doc への link-map はポインタのみ。load-bearing な事実をリンク先 / llms.txt / graph だけに置かない

最重要の落とし穴: フロアは小さな非交渉コア。「削るな・再構造化せよ」を効かせすぎると、Mermaid / details / フロア節に情報が温存され、README が偽装 llms-full.txt に肥大する。人間の目標は短くだった。フロア以外は容赦なく削るか relocate する（→ length budget）。

Visual-first（Mermaid 第一・raster 最後）

形式の選択

中身	最適形式	理由
3 ステップの線形 / 単純な列挙	prose / list / 小さな表	全デバイス（特にモバイル）で読める。図にする価値がない
本当に graph 形状（関係・多分岐・matrix）	Mermaid（`TD` 縦方向）	ソースがテキストで LLM も読める。縦スクロールはスマホで自然、横（`LR`）は潰れる
大きい / 複雑な図	committed SVG（拡大・パン可）/ subsystem 分割	巨大 Mermaid は desktop でも上限に当たり、モバイルで潰れる
実 UI / 実行結果 / 写真	raster（PNG/JPG/WebP/GIF）	Mermaid で表現できないものだけ

Mermaid の要点

GitHub が theme-aware SVG にネイティブ描画。ソースはテキスト（diff 可能・~10 token/edge）で pixel を見られない text-only クローラにも読める。散文/graph に埋もれた構造（concept matrix・phase binding・pipeline 段）を Mermaid 化すると短くなり情報密度が上がる。
モバイル最優先で TD（縦）。横長 LR は狭幅で破綻しやすい。
描画上限は char ベース（maxTextSize 既定 50,000）+ edge ベースで、ノード数ではない（「50-100 node が限界」は俗説）。超えそうなら subsystem 分割。special な Project README では描画されない。
抽出器が Mermaid を落とす可能性があるので、上のテキスト等価で意味を必ず別途担保する。

raster / その他

raster は load-bearing な情報を担わせない。alt-text を必須（hard floor: text 経路は alt しか読まない = alt 無し画像は LLM に不可視。a11y だけの話ではない）。
dark/light は <picture><source media="(prefers-color-scheme: …)"><img alt="…"></picture>。<img alt> は二重に load-bearing。
画像 asset は repo に commit し相対パス参照。外部 hotlink（camo 破綻）と inline/animated <svg>/<embed>/<object>（GitHub が sanitize）を避ける。
badge は 2-4 個の高信号のみ（CI / version / license / 研究 repo は DOI）。vanity badge を避ける。狭幅で badge 段が嵩張らないよう数を絞る。
CLI repo: asciinema→agg GIF + 一文キャプション。UI repo: スクショ/GIF + alt-text。

稀な bespoke 図は Claude Artifacts / Claude Code の svg・diagram skill で committable な SVG を生成し assets/ に置く。

Length budget（語数目標は持たない）

語数目標は置かない（「500-1500 語の sweet spot」「visual README は star が増える（GitHub 研究）」はいずれも捏造/無出典として棄却済み）。代わりに:

above-the-fold（最初の 1 画面 = 30 秒で「自分向けか」を判断）: 任意の hero → H1 → 一行 tagline（価値提案＝最も確実に LLM に抽出される行）→ ≤4 functional badge → フロアの事実 → copy-paste の quick start。深い rationale はこの後。
順序は repo 種別で変わる: 「quickstart→rationale」はソフトウェア向け。論文 / dataset / 概念 / DOI essay repo では当てはまらない。固定順を強制せず、「identity + canonical facts が deep rationale より前」だけを守る。lint の identity_lead は「lead 文の存在」だけを構造的に見て順序は強制しない。
総量は 1 変数で決まる: 正準 docs サイト / ADR が深部を吸収するか。深い「なぜ」/ 設計 rationale は ADR / docs/ / llms-full.txt / deposited paper に移し、README には一行ポインタ（Diátaxis の explanation-displacement）。これが「450 行の研究 repo README」の直接の治療。
<details> は二次的な bulk のみ（option 表・FAQ・troubleshooting・full glossary）。人間の視界を整理しつつ LLM には届く。だがフロアを入れない（primacy 喪失 + Ctrl+F 不可。raw-markdown 経路では読めるが、描画ページの要約器は折りたたみを de-prioritize しうる）。

Workflow（Code filter → readme-reviewer agent → 人間 gate）

1. Code filter — `readme_lint.py`（決定論的・structural only）

uv run --directory ~/.claude/skills/readme-writer python -m scripts.readme_lint "$ARGUMENTS"

引数は README の絶対パス。--json で機械可読出力。exit code が code-owned gate（0=clean または warning のみ / 1=error severity あり / 2=not found・too large）。

検査項目（スコアでなく具体 issue。severity 2 段階）:

error（gate を落とす・ハード構造）

single_h1 — H1 はちょうど 1 個
heading_levels — 見出しレベルを飛ばさない
alt_text — すべての画像に alt（hard floor: alt 無し = LLM に不可視）
local_link — ローカル相対リンク / 画像 src が実在する

warning（助言・gate を落とさない） — 構造的に検出するが「本当に問題か」は判断なので surface のみ。意味判断は LLM review に委ねる:

raster_diagram_hint — 図っぽいファイル名の raster（architecture/flow/diagram/pipeline 等の .png/.jpg/.webp/.gif）→ Mermaid 化を提案。SVG・スクショ・logo は除外
badge_budget — badge が多すぎ（既定 >6）。数のみ判定（vanity か否かは LLM）
details_floor_leak — <details> 内に DOI / BibTeX / CITATION トークン（floor 漏れの兆候。「真に floor か」は LLM 判断）
identity_lead — H1 と最初の section の間に prose の lead 文が無い（順序は強制しない。H1 不在は single_h1 が担当）
doi_citation_pairing — DOI があるのに how-to-cite（Citation 節 / BibTeX / CITATION.cff）が無い（DOI を非研究 repo に強制しない——DOI がある時だけ発火）

2. LLM review — `readme-reviewer` agent を起動（author-reviewer separation）

README-only recovery（最重要） — テキストだけでプロジェクトを復元できるか、フロア欠落の具体列挙
Lead の What / Who / Why
人間フック / 価値提案
物語 / scannability
短さの検証（偽装 llms-full.txt 化の逆方向チェック）
visual の妥当性（Mermaid / テキスト等価 / badge vanity）
lint warning の意味判断（badge_budget → vanity か、raster_diagram_hint → Mermaid 化すべきか等）

/codex-review "Review the README changes as prose, not code: is the project recoverable from the README text alone, is the lead clear about what/who/why, is anything load-bearing hidden in images or collapsed sections?"

3. fact 一致確認 → `context-sync`

README の事実が llms.txt / llms-full.txt / graph.jsonld と一致するか（cloaking 回避）は context-sync が正本。本 skill では再実装しない。

4. 人間 gate

What This Skill Does NOT Do（境界）

llms.txt / llms-full.txt を書かない（→ llms-txt-writer）
graph.jsonld を設計しない（→ jsonld-knowledge-graph）
cross-surface の drift 検出 / 同期をしない（→ context-sync / release-doi）
記事 / エッセイを編集しない（→ writing-ecosystem）
repo の description / topics / social-preview を設定しない（gh repo edit / release-doi 側。本 skill は checklist として提示するのみ）
品質スコア / grade / 評点を出さない

Anti-patterns

数値スコアだけ出して具体案なしで終わる（recommender 型の罠）
構造 lint で済む項目を LLM に判断させる / 意味的判断を regex で代用する（when-code-when-llm 参照）
AI surface の数値指標（ski-ramp / entity density / 疑問見出し farming）を人間 README に流用する（可読性低下）
「ビジュアル優先」を散文の画像化と解釈する（raster 図は text-only LLM に不可視 = 情報をエージェントから隠す。Mermaid を使う）
「削るな・再構造化せよ」を効かせすぎて偽装 llms-full.txt 化する（フロアは小さく、上は容赦なく削る/relocate）
機械層（llms.txt/graph）が backstop する前提で README フロアを薄くする（grounding 経路で読まれない）
llms.txt/graph を README prose から derive する（drift。manifest から derive）
人間向けに事実を盛る / マネタイズ訴求を足す（authenticity 毀損 + 機械層との矛盾 = cloaking。梱包は変えても主張は変えない）

Verification

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 図を使う best-practice 例）と fixtures/sample_issues.md（全 9 チェックを発火させる例）で基本挙動を確認できる。

readme-reviewer agent（~/.claude/agents/readme-reviewer.md）— 本 skill の Step 2 を担うレビュー agent。レビュー基準の正本
codex-review — 公開 README への cross-model 並列レビュー（prompt-driven モード）
llms-txt-writer — AI surface の対になる writer（研究値ベースの geo_check.py を持つ）。本 skill は人間 surface。
when-code-when-llm — structural / semantic の判定軸
context-sync — README ↔ 機械層の fact 一致 / drift（fact 検証はこちらに委譲）
jsonld-knowledge-graph — graph.jsonld 設計
writing-ecosystem — 人間向け長文 prose の orchestrator
inspiration.md — 設計の出自・一次研究の provenance・外部エビデンスの出典（Portability のため SKILL.md 本文から分離）

readme-writer

readme-writer — Human-Facing README Skill

When to Use

軸は「人間の ATTENTION × LLM の INFORMATION」

README は確実に読まれる唯一の surface（だが「only」ではない）

なぜ「構造 lint」と「ホリスティック review」を分けるのか

ただし「構造的 AI 可読性」は積極採用する（two-sided rule）

最小 LLM-read フロア（小さく・非交渉・肥大させない）

Visual-first（Mermaid 第一・raster 最後）

形式の選択

Mermaid の要点

raster / その他

Length budget（語数目標は持たない）

Workflow（Code filter → readme-reviewer agent → 人間 gate）

1. Code filter — readme_lint.py（決定論的・structural only）

2. LLM review — readme-reviewer agent を起動（author-reviewer separation）

3. fact 一致確認 → context-sync

4. 人間 gate

What This Skill Does NOT Do（境界）

Anti-patterns

Verification

Related

readme-writer — Human-Facing README Skill

When to Use

軸は「人間の ATTENTION × LLM の INFORMATION」

README は確実に読まれる唯一の surface（だが「only」ではない）

なぜ「構造 lint」と「ホリスティック review」を分けるのか

ただし「構造的 AI 可読性」は積極採用する（two-sided rule）

最小 LLM-read フロア（小さく・非交渉・肥大させない）

Visual-first（Mermaid 第一・raster 最後）

形式の選択

Mermaid の要点

raster / その他

Length budget（語数目標は持たない）

Workflow（Code filter → readme-reviewer agent → 人間 gate）

1. Code filter — readme_lint.py（決定論的・structural only）

2. LLM review — readme-reviewer agent を起動（author-reviewer separation）

3. fact 一致確認 → context-sync

4. 人間 gate

What This Skill Does NOT Do（境界）

Anti-patterns

Verification

Related

1. Code filter — `readme_lint.py`（決定論的・structural only）

2. LLM review — `readme-reviewer` agent を起動（author-reviewer separation）

3. fact 一致確認 → `context-sync`

1. Code filter — `readme_lint.py`（決定論的・structural only）

2. LLM review — `readme-reviewer` agent を起動（author-reviewer separation）

3. fact 一致確認 → `context-sync`