Create llms.txt

Generate a high-quality, spec-compliant llms.txt that gives LLMs maximum understanding of a project with minimum tokens.

Spec (llmstxt.org)

The file uses markdown with this exact section order:

1. H1 (required) — project name
2. Blockquote (optional) — one-paragraph summary with key context
3. Prose (optional) — additional detail, any markdown except headings
4. H2 sections (optional) — lists of [name](url): description links
5. ## Optional (special) — links that can be skipped for shorter context

No other heading levels allowed. Every list entry must be a markdown hyperlink. Descriptions after : are optional.

# Project Name

> One-paragraph summary covering what it is, who it's for, and key capabilities.

## Docs

- [README](url): Installation, usage, examples
- [API Reference](url): Endpoint documentation

## Optional

- [CONTRIBUTING](url): How to contribute

Procedure

1. Discover project identity

Read these files (skip missing ones):

• README.md — name, summary, features
• AGENTS.md — architecture, key directories
• package.json / Cargo.toml / pyproject.toml / go.mod — name, description, repo URL
• CHANGELOG.md — exists? link it
• CONTRIBUTING.md — exists? link in Optional
• LICENSE — exists? link in Optional

Determine the repo base URL from git remote or manifest. All links must be absolute URLs pointing to the main branch (e.g. https://github.com/{owner}/{repo}/blob/main/{path}).

2. Identify key files

Scan for files that help an LLM understand the project:

• Entry points (main.go, src/lib.rs, src/index.ts, app.py, etc.)
• Public API surface (exported modules, route definitions, CLI entry)
• Config files that define behavior (flake.nix, Justfile, Makefile, docker-compose.yml)
• Schema definitions (OpenAPI, GraphQL, DB migrations)
• Skills (skills/*/SKILL.md)

Limit to 6-10 key files. Prefer files that explain what the project does over internal implementation.

3. Write the blockquote

One paragraph, 2-3 sentences max. Cover:

• What the project is
• Who it’s for / what problem it solves
• Key differentiating capabilities

Do NOT pad with generic filler. Every word should help an LLM decide whether this project is relevant to a query.

4. Organize sections

Use these H2 sections (omit empty ones):

5. Write link descriptions

Each : description should be 3-10 words explaining what the LLM will find there. Skip the description only if the link name is already self-explanatory.

Bad: - [README](url): The README file Good: - [README](url): Installation, usage, and examples

6. Validate

Before writing the file, check:

• H1 is the first line, matches project name
• Blockquote is present and concise
• All URLs are absolute and resolve to real files
• Sections appear in order: Docs, API/Key Files, domain sections, Optional last
• No H3+ headings used (spec only allows H1 and H2)
• ## Optional is last if present
• Total file is under 50 lines (aim for density)
• No duplicate links across sections
• Every list item has a markdown hyperlink

Gotchas

• No relative links. LLMs fetch llms.txt from a URL — relative paths break. Always use absolute URLs.
• Don’t link directories. Link to the actual markdown/source file, not a directory path. skills/configure-ai/SKILL.md not skills/configure-ai/.
• The ## Optional heading is semantic. It tells LLMs they can drop these links when context is tight. Put truly skippable content there — not your API docs.
• Don’t duplicate the README. The blockquote is a summary for LLMs, not a copy of your README’s first paragraph. Write it fresh with an LLM audience in mind.
• Keep it short. An llms.txt that’s 200 lines defeats the purpose. Aim for 20-50 lines. If you need more, your project needs better docs, not a longer index.
• Repo URL detection: check git remote get-url origin and normalize to HTTPS. Strip .git suffix. Use blob/main/ for file links.