mk-llms - SKILL.md Agent Skill

name: mk:llms description: Generate llms.txt files from project documentation following the llmstxt.org spec. Use when asked to create AI-friendly documentation indexes, generate llms.txt, or make a project discoverable by AI assistants. argument-hint: '[path] [--full] [--output path] [--url base]' source: local original_path: .claude/skills/llms/SKILL.md adapted_for: claude-code keywords: - llms - llms-txt - llm-friendly-docs - ai-discoverability - agentic-content when_to_use: Use when generating llms.txt or LLM-friendly documentation for AI consumers. user-invocable: true owner: docs criticality: medium status: active runtime: claude-code

llms.txt Generator

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

Path convention: Commands below assume cwd is $CLAUDE_PROJECT_DIR (project root). Prefix paths with "$CLAUDE_PROJECT_DIR/" 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: /mk:llms [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). Claude only reviews and improves the output.

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

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

Process

Run script — execute generate-llms-txt.py --source <path> --json to preview metadata
Review metadata — check project name, description, file categorization
Generate — run script again without --json to produce llms.txt
Review output — read generated llms.txt, improve descriptions if needed
Validate — check: H1 present, blockquote summary, valid link format, Optional section last
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 .claude/scripts/bin/setup-workflow once from the project root before invoking this skill. Re-run after upgrading the toolkit.