git:20260422.18125cf to git:20260530.d3be4dd

---

name: create-llms-txt

description: >

Generate a spec-compliant llms.txt file for any project by analyzing its

codebase, docs, and public URLs. Use when creating an llms.txt, making a

project LLM-discoverable, or when the user mentions "llms.txt" in the

context of generating or scaffolding one.

user-invocable: true

metadata:

title: Create llms.txt

category: ai

order: 1

---

# 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.

```markdown

# 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 (`Justfile`, `Makefile`, `docker-compose.yml`, `pyproject.toml`)

- 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):

| Section | Contents |

|---------|----------|

| `## Docs` | README, AGENTS.md, API docs, guides |

| `## API / Key Files` | Entry points, public API, config, schemas |

| `## Skills` | Agent skills if `skills/` directory exists |

| `## Optional` | CONTRIBUTING, LICENSE, changelog, secondary docs |

### 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.