Skip to main content

llms.txt

Large language models work best when they have accurate, structured context about the libraries they’re working with. The llms.txt convention gives LLM-based tools a machine-friendly summary of your package: what it does, what its API looks like, and where to find the full documentation. Great Docs generates two files automatically during every build:

Both files are placed in the root of your documentation site and are available at predictable URLs (e.g., https://your-docs-site.com/llms.txt). No configuration is needed so if your project has an API reference defined in great-docs.yml, the files are generated automatically.

What Goes Into Each File

Great Docs generates both files from the same source data but at different levels of detail. The compact llms.txt is a quick-reference index whereas llms-full.txt is the complete picture.

llms.txt

The compact index follows the llms.txt format:

# my_package

> A short description of the package

## Docs

### API Reference

#### Data Processing
> Functions for loading and transforming data

- [read_csv](https://example.com/reference/read_csv.html): Read a CSV file into a DataFrame
- [to_parquet](https://example.com/reference/to_parquet.html): Write a DataFrame to Parquet format

#### Visualization
> Plotting and display utilities

- [plot](https://example.com/reference/plot.html): Create a plot from a DataFrame
- [show](https://example.com/reference/show.html): Display a plot in the browser

The content is derived from:

  • Package name and description from pyproject.toml
  • Section titles and descriptions from the api-reference.sections block in great-docs.yml
  • One-line docstring summaries extracted by importing the package at build time
  • URLs constructed from the site-url in great-docs.yml or the Documentation URL in pyproject.toml

This file is typically small (a few KB) and is designed to give an LLM a quick overview of the API surface without overwhelming its context window.

When WebMCP is turned on, llms.txt ends with a “WebMCP tools” section, so an agent that reads the file learns that it can also call tools on the site’s pages. The last four tools appear when the site has a CLI reference, versions, a changelog or Agent Skills:

## WebMCP tools

An AI agent in a browser that supports WebMCP can call these tools on this site's pages. Results are JSON objects with absolute URLs.

- [WebMCP manifest](https://example.com/gd-webmcp.json): The site's sections, pages and API names, which the tools read

- `get_site_overview`: The package, its version and install commands, the site's sections and these tools
- `get_current_page`: The open page as Markdown, or as an outline of its headings
- `list_pages`: The site's pages grouped by section
- `get_page`: One page, or one section of it, as Markdown
- `search_docs`: Ranked matches for a query, by page section
- `list_api`: The documented objects grouped by reference section
- `get_api_reference`: One object's signature, parameters, returns and examples
- `get_cli_help`: The help text of a CLI command
- `list_versions`: The documented versions, with this page's URL in each
- `get_changelog`: One release's changelog entry, or the latest few
- `get_agent_skill`: A published SKILL.md and its companion files

Scripts on the site's pages can call the same tools:

```js
window.greatDocs.tools.list();
await window.greatDocs.tools.call("search_docs", { query: "install" });
```

llms-full.txt

The comprehensive file includes everything in llms.txt plus:

  • Full function and class signatures with all parameters and type annotations
  • Complete docstrings (not just the first line)
  • CLI help text for all commands and subcommands (if CLI documentation is enabled)
  • User guide content from all user guide pages, with YAML frontmatter stripped

This file can be large (tens of KB to hundreds of KB depending on your API surface and user guide size). It’s intended for tools that can handle larger context windows or that retrieve sections selectively.

How It Works

Both files are generated during Step 3 of the build pipeline (great-docs build), right after the API reference configuration is refreshed and before the SKILL.md is generated. The generation requires an api-reference block in great-docs.yml. Without one, both files are silently skipped.

Great Docs imports your package at build time to extract docstrings and signatures. This means the package must be importable in the build environment. For CI builds, make sure your package is installed before running great-docs build.

The build log shows the generation as a single step:

━━ Step 3/18 ─ Generate llms.txt / llms-full.txt ━━━━━━━━
   ✔ Created llms.txt + llms-full.txt                <0.2s

Relationship to Agent Skills

The llms.txt files and Agent Skills serve complementary purposes:

llms.txt / llms-full.txt SKILL.md
Audience Any LLM-based tool AI coding agents specifically
Content Auto-generated from code Hand-written (recommended) or auto-generated
Scope Full API surface + docs Curated cheat sheet: gotchas, decisions, patterns
Size Can be very large Under 500 lines (recommended)
Protocol Direct URL fetch .well-known discovery + install CLI

A typical setup uses both: llms-full.txt for comprehensive reference and SKILL.md for opinionated guidance that can’t be inferred from code alone. Skills often link to llms-full.txt in their Resources section so agents can pull in more detail when needed.

Verifying the Output

After a build, you can inspect the generated files directly:

# Check that both files were created
ls -la docs/_site/llms.txt docs/_site/llms-full.txt

# Preview the compact index
head -30 docs/_site/llms.txt

# Check the size of the full file
wc -l docs/_site/llms-full.txt

Or visit them on your deployed site:

https://your-docs-site.com/llms.txt
https://your-docs-site.com/llms-full.txt

If the files are missing after a build, check that your great-docs.yml has an api-reference block with at least one section and that the package is importable in the build environment.

Next Steps

The llms.txt files are generated automatically with no configuration required. For more targeted AI agent context, consider authoring a SKILL.md alongside them.

  • Agent Skills: hand-crafted context for AI coding agents
  • WebMCP: tools that AI agents in the reader’s browser can call
  • Configuration: all great-docs.yml options
  • Building: the full build pipeline and step order
  • API Documentation: configuring the api-reference sections that feed into llms.txt