readme-writer

# 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-de...