nuxt-agent-md

nuxt-agent-md

Generate AGENTS.md and CLAUDE.md with Nuxt documentation for AI coding agents (Cursor, Copilot, Claude Code, etc.).

Gives your AI assistant instant access to accurate Nuxt API references, reducing hallucinations and improving code quality.

Usage

# Run directly with bunx
bunx nuxt-agent-md

# Or install globally
bun add -g nuxt-agent-md
nuxt-agent-md

What it does

1. Detects your Nuxt version from package.json
2. Downloads the corresponding @nuxt/docs documentation (~1.5 MB) to .nuxt-docs/
3. Generates a compact pipe-delimited index pointing to the downloaded docs
4. Creates/updates AGENTS.md with a directive instruction and the index
5. Creates CLAUDE.md that references @AGENTS.md

The generated AGENTS.md is intentionally minimal — a short directive telling the agent to read the docs, followed by a file index. No inline API summaries or pattern guides are included, so the agent is forced to consult the actual documentation files rather than relying on stale training data.

This follows Vercel's finding that passive context with retrieval-led reasoning outperforms both skills and inline knowledge.

Options

-d, --docs-dir <path>      Directory to store docs (default: .nuxt-docs)
-o, --output <path>        Output AGENTS.md path (default: AGENTS.md)
-v, --nuxt-version <ver>   Nuxt docs version (auto-detected from package.json)
    --minify               Generate minified index (default: true)
    --no-minify            Generate full index instead of minified
    --dry-run              Show what would be done without making changes
-h, --help                 Show this help message

Examples

# Auto-detect Nuxt version from package.json
nuxt-agent-md

# Use specific Nuxt version
nuxt-agent-md -v 4.0.0

# Generate full (non-minified) index
nuxt-agent-md --no-minify

# Custom output paths
nuxt-agent-md -d .docs -o CLAUDE.md

Output

The tool generates:

1. .nuxt-docs/ - Directory containing markdown documentation (auto-added to .gitignore)
2. AGENTS.md - File with documentation index (wrapped in <!-- BEGIN:nuxt-agent-rules --> markers)
3. CLAUDE.md - File that references @AGENTS.md for Claude Code/Cursor compatibility

How it works

The key insight from Vercel's research is that agents perform best when given a directive to read docs rather than inline knowledge they can use as a shortcut. The generated AGENTS.md contains:

# Nuxt: ALWAYS read docs before coding

This project uses Nuxt v4.x.x. Before any Nuxt work, find and read
the relevant doc in `.nuxt-docs/`. Your training data may be outdated
— the docs are the source of truth.

Followed by a compact index mapping categories to doc file paths. The agent sees the index, knows where to find specific docs, and reads the actual files when needed.

License

MIT