Llms Txt Writer

llms-txt-writer — AI-Facing Writing Skill

AI 検索エンジン（ChatGPT / Perplexity / Gemini）と AI エージェントに引用・参照されることを最適化した文書を書くスキル。静的解析（GEO-SFE）と Answer.AI llms.txt 標準の両方をカバーする。

When to Use

以下のいずれかに該当するとき:

• llms.txt / llms-full.txt を新規作成・更新する
• FAQ / 用語集など AI 検索引用を狙うドキュメントを書く
• 既存の AI-facing 文書の GEO スコアを診断・改善する

使わない場面:

• README / repo のトップページ（readme-writer を使う — 証拠スクリプト + fresh context の判定器 + review panel を持つ）
• 記事 / エッセイ / ブログポスト等の人間向けコンテンツ（writing-ecosystem を使う）
• 人間可読性を最優先したいドキュメント

Audience Separation: Human vs AI

ドキュメントは 人間 primary か AI primary かで最適化が根本的に異なる。1 ファイルで両立させると、どちらにも中途半端になる。

本 skill は AI primary の最適化のみ扱う。

Answer.AI llms.txt Standard（v2 — as-of 2026-08-23 に一次ソース確認）

llmstxt.org（Jeremy Howard / Answer.AI。2024-09-03 公開、v2 は 2026-08-10 更新）。

spec が定めるのは llms.txt だけ:

• 必須は H1（プロジェクト名）のみ。順序は BOM（任意）→ H1 → 要約 blockquote → 見出し以外の詳細 markdown → H2 区切りのファイルリスト
• Optional セクション = 二次情報。「より短い context が要るときエージェントが スキップしてよいリンク」という意味（機械的な必須/任意の区別ではない）
• 発見用の link relation（HTTP Link ヘッダまたは HTML <link> で提供する）: rel="describedby" → llms.txt 本体、rel="alternate" type="text/markdown" → markdown 版ページ
• .md URL 規約: page.html.md（付加）/ page.md（置換）/ ルートは index.html.md または index.md
• サブパスの llms.txt: 「A file covers the URLs under its path」。複数該当するときは 最も具体的なものを使う

llms-full.txt は spec に無い（llms_txt2ctx の context expansion も v2 の本文に記載なし）。 以下の 2 ファイル構成はコミュニティ慣行として本 skill が採る運用であって、標準準拠ではない:

llms.txt（Navigator）の標準フォーマット

# Project Name

> 1-2 文の要約。何を提供するプロジェクトか。

## Core documentation

- [Full AI Reference](llms-full.txt): self-contained content
- [README](README.md): human-facing narrative
- [Contributor guide](CLAUDE.md): ...

## Architecture

- [Architecture overview](docs/...): ...

## Related

- [Related repo](https://...): ...

llms-full.txt の標準フォーマット

# Project — AI Reference

Intro paragraph（audience が AI である明示を含む）.

> **Audience**: AI search engines and AI agents.

## Project Facts
（エンティティ爆弾 bullet リスト）

## Prior Research References
（引用テーブル、冒頭配置で ski-ramp 効く）

## What is X? （Q1）
（50-150 語の回答）

## How does Y work? （Q2）
...

三層構造（README と合わせて）

my-project/
  README.md         → human-facing narrative（人間向け）
  llms.txt          → AI navigator（~5 KB、link 主体）
  llms-full.txt     → AI self-contained content（~20 KB、Q&A + 定義）

責務完全分離。overlap なし。

GEO/AEO 静的解析 (GEO-SFE 3 階層)

実証研究ベースの閾値:

5 Checks

重要: スクリプトは H2 (##) のみをカウントする。H3 以下は親 H2 chunk にマージされる（AI 検索エンジンが引用単位として H2 chunk を使う設計）。FAQ Q&A は すべて H2 に並べる。

Execution

uv run --directory ~/.claude/skills/llms-txt-writer python -m scripts.geo_check "$ARGUMENTS"

引数は解析対象 Markdown / llms-full.txt の絶対パス。--json を付けると機械可読 JSON を出力。

Post-script Interpretation (解釈レイヤー)

script の stdout 数値レポートを受け取ったら、Claude は以下を必ず行う:

1. FAIL / WARN 項目ごとに具体的な修正案を提示する

• 質問見出し率 FAIL: 対象の ## 見出しから 1-2 個を選び、質問形式の 2 案を提示
  • 例: 「背景」 → 「なぜ GEO は主戦場になったか？」「GEO はどこから来たか？」
• エンティティ密度 WARN/FAIL: script が出力する「薄い段落」を特定し、固有名詞（ブランド / ツール / 人名 / arXiv 番号）を 3-5 個候補提示
• スキーランプスコア WARN/FAIL: 以下の「Practical Ski-ramp Optimization」を参照
• チャンク範囲外: 長すぎるセクションは分割点を具体指示、短すぎるセクションは統合候補を提示

2. script が判定できない質的観点を補う

• 数値上 OK でも、定義的表現の中身が空洞（「X とは Y」だけで Y が曖昧）なら指摘する
• エンティティが抽象度高すぎる（「AI」「LLM」だけで具体製品名がない）なら具体化を勧める
• 冒頭 30% に数値はあるが「読者の why」が不在なら、問題提起の追加を勧める

3. Edit 提案は diff 形式で分割して提示

ユーザーが y/n 承認できる粒度（1 提案 = 1 edit）にする。一括書き換えはしない。

Practical Ski-ramp Optimization (実戦知見)

ski-ramp（冒頭 30% にエンティティ 45%+ 集中）は素の Q&A 文書では届かないことが多い。以下の手法で押し上げる。

手法 1: Project Facts ブロックを冒頭に

タイトル・要約の直後にエンティティ爆弾 bullet リストを置く:

## Project Facts

- **Version**: 2.0.0
- **DOI**: 10.5281/zenodo.XXXXXXX
- **License**: MIT
- **Tests**: NNNN passing
- **Runtime**: Python 3.10+, Qwen3.5 9B, nomic-embed-text 768-dim
- **Dependencies**: requests, numpy, rank-bm25
- **ADRs**: N (ADR-0001 through ADR-NN)
（その他具体数値・ブランド名・パス等を 15-20 個）

version 番号、DOI、テスト数、モデル名、依存パッケージ名、パス — 数字と固有名詞が連続するので entity 密度が跳ね上がる。

手法 2: Prior Research / References テーブルを冒頭に

学術論文テーブルは entity の宝庫（著者名・年・arXiv 番号・ジャーナル名）。末尾ではなく Project Facts の直後に置く:

## Prior Research References

| Short Name | Full Citation | Relation |
|---|---|---|
| A-MEM | Xu et al. (2025). arXiv:2502.12110 | ... |
| Zep | Rasmussen et al. (2025). arXiv:2501.13956 | ... |
...

手法 3: 用語定義の - Prior research: bullet を削除

各用語定義に - **Prior research**: Xxx et al. (2025) ... を書くと、それらが back half の entity 密度を押し上げる。冒頭にテーブルがあれば重複なので削除する。情報損失なし、entity 分布だけが前に寄る。

実戦事例

contemplative-agent プロジェクト（2026-04-19）:

• 施策前: ski-ramp 23.5% FAIL
• 手法 1 (Project Facts) 単独: 23.5% → 28.4%（改善軽微）
• 手法 1 + 2 + 3 の合わせ技: 23.5% → 55.0% ✅ OK
• 全 5 指標 OK 達成（question_heading 0.91, chunk 0.83, entity 0.31, definition 1.79）

教訓: 手法 1 単独では効果薄。手法 2（前置き）+ 手法 3（重複削除）が ski-ramp 押し上げの本体。

Anti-patterns

• 数値スコアだけ表示して具体案なしで終わる（recommender 型の罠）
• 「AI 向けに SEO キーワードを詰め込め」と解釈する（読みやすさ低下で逆効果、AI 判定にもマイナス）
• script 結果を無視して Claude が独自にフルレビューする（script の決定論性が台無し）
• 人間向け README / 記事に本 skill を適用する（質問見出し化 / TL;DR ブロック等が可読性を下げる）
• H3 以下で Q&A を並べる（geo_check は H2 のみカウント。H3 Q は見えない）

Companion JSON-LD Graph (Optional)

Project が安定した concept-level 構造（matrix / hierarchy / phase-binding 等）を持ち、prose だけでは LLM に triple として伝えにくい場合、graph.jsonld を companion file として置ける。

llms.txt / llms-full.txt 側でやること:

• llms.txt 冒頭に Graph-first reading order block 追加（> AI agents should read graph.jsonld first blockquote + numbered "Recommended reading order" section）
• ## Core documentation の 最上位 に navigator entry を追加（"Read first" qualifier 推奨）
• llms-full.txt 末尾に question-form H2（"How do X and Y relate as a graph?"）を追加し graph.jsonld を参照（question-form は 2.8x citation boost）
• README 側の置き方は readme-writer が正本（本 skill は README に手を入れない）。あちらの規約は「AI 向けの機械可読導線（graph.jsonld / llms.txt）は <details> に入れず、末尾に平文 1–2 行」で、理由は rendered-HTML の crawler と HTML ブロックを不透明扱いする抽出器に折りたたみが見えないこと。冒頭の <details> block を README に足さない
• hub-and-spoke topology の場合、line 側 README から hub graph への reverse-link を上記の平文行に含める（配置の判断は readme-writer）

graph 自体の設計、schema vocabulary、cross-graph @id 規約、file-level 構造との役割境界、verification workflow は別 skill が正本を持つ。

See skill: jsonld-knowledge-graph

Verification

cd ~/.claude/skills/llms-txt-writer
uv sync --dev
uv run pytest tests/ --cov=scripts --cov-report=term-missing

fixtures/sample_ja.md と sample_en.md で基本挙動を確認できる。

Related

• writing-ecosystem skill（~/MyAI_Lab/zenn-content 常駐）— 人間向け執筆の orchestrator（役割は完全に分離。本 skill は AI 向けのみ）
• llmstxt.org — Answer.AI llms.txt 標準の原典