readme-writerlisted

# readme-writer — Human-Facing README Skill 人間（と、人間が着地する検索 / AI Overviews）に向けた README を書く・改善するスキル。`llms-txt-writer` が AI surface を担うのに対し、本 skill は **人間 surface の単一正準入口**を担う。 ## When to Use - README.md / README.ja.md を新規作成・改善する - repo / プロジェクトの「人間が最初に着地するページ」を整える - 既存 README が「機械寄りで人間に中途半端」なのを人間ファーストに直す **使わない場面**: - `llms.txt` / `llms-full.txt` / FAQ など AI 専用 doc（→ `llms-txt-writer`） - 記事・エッセイ・ブログ等の長文 prose（→ `writing-ecosystem`） - graph.jsonld の設計（→ `jsonld-knowledge-graph`） --- ## なぜ「構造 lint」と「ホリスティック review」を分けるのか README 品質には 2 種類の property が混在する。**AKC ADR-0008 "Code-LLM Layering"** に従い、所有者を分ける: - [agent-knowledge-cycle/docs/adr/0008-code-and-llm-collaboration.md](https://github.com/shimo4228/agent-knowledge-cycle/blob/main/docs/adr/0008-code-and-llm-collaboration.md)（Agent Knowledge Cycle research line, concept DOI [10.5281/zenodo.19200726](https://doi.org/10.5281/zenodo.19200726)） - 判定の軸は [`when-code-when-llm`](../when-code-when-llm/SKILL.md): 「同じバイト列が文脈で違う意味になりうるか?」 | property | 例 | 種別 | 所有者 | |---|---|---|---| | 構造的 | H1 が 1 個か / 見出しレベル飛ばし / alt-text 有無 / ローカルリンク解決 | structural | **code（`readme_lint.py`）** 100% 精度 | | 意味的 | lead が人を掴むか / 価値提案の明快さ / 物語の流れ / 用語の適切さ | semantic | **LLM のホリスティック review** | **`geo_check.py` のような研究値ベースのスコアは README には作らない**。llms.txt のセクション比率（ski-ramp 等）は LLM 引用研究で検証された決定論的シグナルだが、README の「良い人間入口か」は意味的判断であり、同等の決定論的知見は存在しない。entity density 等の AI surface 指標を人間 README に持ち込むのは anti-pattern。 --- ## Workflow（Code filter → LLM → 人間 gate） AK