ring-generating-llms-txt

name

ring:generating-llms-txt

description

Generating or auditing a repository's llms.txt per the llmstxt.org spec, and creating CLAUDE.md / AGENTS.md when missing, by analyzing README, build files, docs, and API surface. Use when creating an llms.txt, auditing an existing one for spec compliance and live links, or improving a repo's AI readability. Skip when the llms.txt is current, the task is code-only with no doc scope, or the repo needs no LLM discoverability.

LLMs.txt & AI Documentation Generator

When to use

• Creating a new llms.txt for a repository
• Auditing an existing llms.txt for completeness
• Generating CLAUDE.md or AGENTS.md for AI coding agents
• Improving AI readability of a repository

Skip when

• Repository already has a complete, up-to-date llms.txt
• Task is code implementation with no documentation scope
• Repository is private/internal with no LLM discoverability need

Related

Complementary: ring:running-dev-cycle, ring:implementing-tasks

Generates llms.txt, CLAUDE.md, and AGENTS.md for repositories.

Step 1: Analyze Repository

1. Read README.md — project name, description, purpose
2. Read CONTRIBUTING.md — build, test, lint instructions (if exists)
3. Read Makefile / package.json / go.mod — build system, language, dependencies
4. Scan /docs/ — available documentation
5. Scan /api/ or OpenAPI specs — API surface
6. Read existing llms.txt / CLAUDE.md / AGENTS.md (if mode=audit)
7. Identify: language, architecture, test framework

Step 2: Generate llms.txt

Follow llmstxt.org specification exactly:

# {Project Name}

> {One-line description: language, what it does, license.}

{Optional: architecture, key concepts, domain terminology needed to work with this project.}

## Docs

- [{Doc title}]({url}): {Brief description}

## API Reference

- [{API name}]({url}): {What this covers}

## Code

- [{Key module}]({path}): {What this module does}

## Optional

- [{Secondary resource}]({url}): {Description}

Rules:

• One H1 (project name), required
• Blockquote summary — required, include language and license
• H2 sections only (no H3+)
• Links: [title](url): description format
• File in repo root: /llms.txt
• Target: fits in ~2K tokens

MUST include: name, architecture overview, key domain concepts, links to README/CONTRIBUTING/API docs/key modules.

MUST NOT include: internal-only docs, CI/CD details, issue tracker, full dependency lists, changelog.

Step 3: Generate CLAUDE.md

Read by Claude Code at session start. Must be actionable with exact commands:

# {Project Name}

## Quick Start
{How to build and run locally — exact copy-pasteable commands}

## Testing
{How to run tests — exact commands including single-test}

## Linting & Formatting
{Lint/format commands, CI expectations}

## Architecture
{Brief: layers, key directories, patterns}
e.g., "Business logic in /internal/domain/, HTTP handlers in /internal/adapters/http/"

## Key Conventions
{Naming conventions, error handling, logging patterns with examples}
e.g., "Functions use camelCase: processTransaction()"

## Common Pitfalls
{What trips up new contributors or AI agents}

Rules:

• Commands must be copy-pasteable (no placeholders)
• Architecture must name actual directories
• Conventions must have inline examples
• Keep under 3K tokens

Step 4: Generate AGENTS.md

Same structure as CLAUDE.md but vendor-neutral language. If CLAUDE.md exists: AGENTS.md can reference it:

# {Project Name} — AI Agent Context

See [CLAUDE.md](./CLAUDE.md) for complete setup and conventions.

## Additional Notes
{Any agent-specific guidance not in CLAUDE.md}

Audit Mode (mode=audit)

For existing files, check:

Check	Pass Condition
llms.txt has H1 + blockquote	Required fields present
All links resolve	No 404s
Spec compliance	No H3+, no non-list content in sections
CLAUDE.md commands valid	All commands runnable, no stale references
Under token budget	llms.txt < 2K tokens, CLAUDE.md < 3K tokens

Output

## LLM Documentation Report

Mode: create | audit | full
Repository: {repo_path}

### Files Generated/Updated
| File | Action | Tokens |
|------|--------|--------|
| llms.txt | Created/Updated/OK | ~{N} |
| CLAUDE.md | Created/Updated/OK | ~{N} |
| AGENTS.md | Created/Updated/OK | ~{N} |

### Audit Results (audit mode)
| Check | Status | Details |
|-------|--------|---------|