llms.txt Generator

Generate llms.txt files — LLM-friendly markdown indexes of project documentation.

Path convention: Commands below assume cwd is $(git rev-parse --show-toplevel) (project root). Prefix paths with "$(git rev-parse --show-toplevel)/" when invoking from subdirectories.

When to Use

• Project needs LLM-friendly documentation index
• User asks for "llms.txt", "LLM documentation", "AI-friendly docs"
• Publishing docs site and want AI discoverability
• After major documentation updates (Phase 6 Reflect)

Explicit: the llms skill [path] [--full]

Workflow Integration

Operates in Phase 6 (Reflect) or on-demand. Output supports the documenter agent.

Arguments

Flag	Effect
(no args)	Scan ./docs directory
path	Scan specific directory
--full	Also generate llms-full.txt with inline content
--output path	Custom output location (default: project root)
--url base	Base URL prefix for links

Scripts

Script-first approach — the Python script handles all deterministic work (scanning, extracting, categorizing, generating). Codex only reviews and improves the output.

# Generate llms.txt (script does the heavy lifting)
.agents/skills/.venv/bin/python3 .agents/skills/llms/scripts/generate-llms-txt.py \
  --source ./docs [--output .] [--base-url https://example.com/docs] [--full]

# Preview metadata first (Codex reviews before generating)
.agents/skills/.venv/bin/python3 .agents/skills/llms/scripts/generate-llms-txt.py \
  --source ./docs --json

Process

1. Run script — execute generate-llms-txt.py --source <path> --json to preview metadata
2. Review metadata — check project name, description, file categorization
3. Generate — run script again without --json to produce llms.txt
4. Review output — read generated llms.txt, improve descriptions if needed
5. Validate — check: H1 present, blockquote summary, valid link format, Optional section last
6. If --full: review llms-full.txt for completeness

Output Format

# {Project Name}

> {Brief project description with essential context.}

## {Section Name}

- [{Doc Title}]({url}): {Brief description}
- [{Another Doc}]({url}): {What this covers}

## Optional

- [{Less Important Doc}]({url}): {Supplementary info}

References

Reference	When to load	Content
llms-txt-spec.md	Step 4 — generating	Full llmstxt.org specification rules

Failure Handling

Failure	Recovery
No .md files found	Report "No documentation found in {path}"
No H1 in doc file	Use filename as title, warn user
Output path not writable	Suggest alternative path

Constraints

• Never fabricate documentation content — only index what exists
• Follow llmstxt.org spec strictly
• Keep descriptions concise — one sentence per entry

Gotchas

• Python venv required: run .codex/scripts/bin/setup-workflow once from the project root before invoking this skill. Re-run after upgrading the toolkit.