llms-txt-writer
August 19, 2026 · View on GitHub
An Agent Skill that writes documents optimized to be cited by AI search engines (ChatGPT / Perplexity / Gemini) and AI agents. Combines Answer.AI's llms.txt standard with GEO-SFE 3-layer static analysis backed by empirical research (Victorino LLC's 1.2M ChatGPT response study, The Digital Bloom, Position Digital, Omniscient Digital, arXiv:2603.29979).
Install
Claude Code
# Copy skill into your global skills directory
cp -r skills/llms-txt-writer ~/.claude/skills/llms-txt-writer
cd ~/.claude/skills/llms-txt-writer && uv sync
SkillsMP
/skills add shimo4228/llms-txt-writer
How It Works
- Target detection — point the skill at an
llms.txt,llms-full.txt, FAQ page, or glossary. geo_check.pystatic analysis — computes 5 GEO metrics in one pass: ski-ramp score, chunk self-containment, question-heading ratio, entity density, definitional-expression density.- Score interpretation — Claude reads the FAIL / WARN list and proposes concrete edits (entity insertion, heading rewrites, chunk splits) keyed to the failing metric.
- Diff-mode edits — each suggestion is presented as a small diff for
y/napproval (no bulk rewrites). - Re-check — re-run
geo_check.pyuntil all 5 metrics are OK.
Key Concept: AI Primary vs. Human Primary
Documents optimize differently depending on audience. Mixing audiences makes both worse.
| Axis | Human primary | AI primary |
|---|---|---|
| Structure | Narrative, flowing paragraphs | Q&A / definitional, H2-independent chunks |
| Headings | Declarative, terse | Question-form, 20%+ |
| Entity placement | Natural to context | Concentrated 45%+ in first 30% (ski-ramp) |
| Definitions | Inferred from context | Explicit X is defined as Y |
| Section length | Proportional to importance | Even, 50–150 words / 150–450 chars |
| Readability | Top priority | Can be sacrificed |
This skill targets AI primary only. For human-facing writing (README, articles, blog posts) use writing-ecosystem + article-writing instead.
Usage
# Run from anywhere; uv handles the project env
uv run --directory ~/.claude/skills/llms-txt-writer \
python -m scripts.geo_check /path/to/llms-full.txt
# JSON output for machine consumption
uv run --directory ~/.claude/skills/llms-txt-writer \
python -m scripts.geo_check --json /path/to/llms-full.txt
GEO Metrics
The skill targets 5 metrics with thresholds derived from empirical studies of AI citation behavior:
| Layer | Metric | OK threshold | Source |
|---|---|---|---|
| Macro | Ski-ramp score | 45%+ entities in first 30% → score 50+ | Victorino LLC (44.2% first-30% citation share) |
| Meso | Chunk self-containment | 80%+ of H2 sections within 50–150 words (EN) / 150–450 chars (JA) | The Digital Bloom (2.3× citation lift) |
| Meso | Question-heading ratio | 20%+ of ## headings end with ? ？ か。 | Position Digital (2.8× citation lift) |
| Micro | Entity density | 15%+ overall | Victorino LLC (20.6% observed, vs. 5–8% normal) |
| Micro | Definitional expression density | 1.0+ per 100 words (EN), 0.5+ per 100 chars (JA) | Omniscient Digital (36.2% citation rate vs. 20.2%) |
Important: geo_check.py counts ## headings only — H3 and below merge into the parent H2 chunk. Put every FAQ Q&A at H2 level.
Real-World Results
Dogfooded on the contemplative-moltbook project (2026-04-19):
| Step | Ski-ramp | All 5 metrics |
|---|---|---|
| Baseline | 23.5% FAIL | FAIL |
| Technique 1 (Project Facts) alone | 28.4% | FAIL |
| Technique 1 + 2 + 3 combined | 55.0% OK | OK ✅ |
Techniques 2 (Prior Research table up-front) and 3 (delete duplicate - Prior research: bullets) carry the ski-ramp lift — Technique 1 alone is insufficient.
Requirements
- Python >= 3.11
uv(for environment management)- Dependencies:
markdown-it-py,textstat,ginza,ja-ginza
Tests
cd skills/llms-txt-writer && uv run pytest -v # 48 tests
Related skills (siblings)
skill-comply— measures whether agents actually follow skill / rule definitionscontext-sync— audits and fixes project documentation rolessearch-first— research-before-coding workflowskill-stocktake— quality audit for skills and commandsrules-distill— scan installed skills, extract cross-cutting principles, and distill them into ruleslearn-eval— extract reusable patterns from sessions, self-evaluate quality, and save to the right locationdaily-research— cron-driven daily research digest — theme selection, multi-stage web research, LLM-as-Judge evaluation
About this skill
This skill is a component skill of the Authorship Strategy research line (DOI 10.5281/zenodo.20263316) maintained by @shimo4228. It is the operational form of the prose-form navigator half of the dual entry point that ADR-0006 normatively requires for any framework-governed artifact. Its companion is jsonld-knowledge-graph, which operationalizes the concept-form graph half; per ADR-0006, deploying only one half leaves the strategy one-lunged — each entry point addresses a distinct LLM-mediated reader sub-population the other cannot reach.
The skill is published alongside the broader research program: three agent-design lines (Agent Knowledge Cycle — mechanism, DOI 10.5281/zenodo.19200726; Contemplative Agent — disposition, DOI 10.5281/zenodo.19212118; Agent Attribution Practice — accountability practice, DOI 10.5281/zenodo.19652013) and two cross-cutting lines (Authorship Strategy itself; Attention, Not Self — Buddhist Abhidharma meets computational phenomenology, DOI 10.5281/zenodo.20262112).
License
MIT
日本語
AI 検索エンジン（ChatGPT / Perplexity / Gemini）と AI エージェントに引用・参照されることを最適化したドキュメント（llms.txt / llms-full.txt / FAQ / 用語集）を書くスキルです。Answer.AI の llms.txt 標準準拠と、実証研究ベースの GEO-SFE 3 階層静的解析（マクロ：ski-ramp、メソ：チャンク自己完結性 + 質問見出し率、ミクロ：エンティティ密度 + 定義表現密度）の両輪で AI primary なドキュメントを評価・改善します。
人間向け README / 記事 / ブログには使いません（writing-ecosystem + article-writing を使用）。
詳細は skills/llms-txt-writer/SKILL.md を参照してください。