Agent Docs

persona: name: "Don Knuth" title: "The Documentation Master - Literate Programming Pioneer" expertise: ['Technical Writing', 'Documentation Systems', 'Literate Programming', 'Knowledge Management'] philosophy: "Code should be written for humans to read, and only incidentally for machines to execute." credentials: ["Author of 'The Art of Computer Programming'", 'Created TeX typesetting system', 'Turing Award winner'] principles: ['Document as you code', 'Write for your future self', 'Examples over abstractions', 'Maintainability first']

Agent Docs

Overview

Write documentation that AI agents can efficiently consume. Based on Vercel benchmarks and industry standards (AGENTS.md, llms.txt, CLAUDE.md).

Anti-Rationalization Table

When to Use

Trigger phrases:

• "agent docs"

• "Writing SKILL"

• "Creating README files for agent consumption"

• "Building API documentation"

• Writing SKILL.md files that will be loaded by agents

• Creating README files for agent consumption

• Building API documentation

• Any documentation that will be read by LLMs in context windows

When NOT to Use

• Writing human-only documentation without agent context
• Creating content that won't be read by AI agents

The Hybrid Context Hierarchy

Three-layer architecture for optimal agent performance:

Layer 1: Constitution (Inline)

Always in context. 2,000–4,000 tokens max.

# AGENTS.md
> Context: Next.js 16 | Tailwind | Supabase

## 🚨 CRITICAL
- NO SECRETS in output
- Use `app/` directory ONLY

## 📚 DOCS INDEX (use read_file)
- Auth: `docs/auth/llms.txt`
- DB: `docs/db/schema.md`

Include:

Quick Reference

• Use markdown formatting for RAG retrieval
• Keep token count low for context efficiency
• Structure content in layers: Constitution → Reference → Detail
• Include code examples inline

Common Mistakes

• Putting too much detail in context (exceeds token limits)
• Not structuring content for RAG retrieval
• Missing critical information in first 2000 tokens
• Using prose instead of scannable lists
• Security rules, architecture constraints
• Build/test/lint commands (top for primacy bias)
• Documentation map (where to find more)

Layer 2: Reference Library (Local Retrieval)

Fetched on demand. 1K–5K token chunks.

• Framework-specific guides
• Detailed style guides
• API schemas

Layer 3: Research Assistant (External)

Gated by allow-lists. Edge cases only.

• Latest library updates
• Stack Overflow for obscure errors
• Third-party llms.txt

Why This Works

Vercel Benchmark (2026):

Root cause: Meta-cognitive failure. Agents don't know what they don't know—they assume training data is sufficient. Inline docs bypass this entirely.

Core Principles

This section covers core principles for the agent-docs skill. Key operations include input validation, core processing, and output verification. Refer to the skill overview for detailed usage instructions.

1. Compressed Index > Full Docs

An 8KB compressed index outperforms a 40KB full dump.

Compress to:

• File paths (where code lives)
• Function signatures (names + types only)
• Negative constraints ("Do NOT use X")

2. Structure for Chunking

RAG systems split at headers. Each section must be self-contained:

## Database Setup          ← Chunk boundary

Prerequisites: PostgreSQL 14+

1. Create database...

Rules:

• Front-load key info (chunkers truncate)
• Descriptive headers (agents search by header text)

3. Inline Over Links

Agents can't autonomously browse. Each link = tool call + latency + potential failure.

4. The "Lost in the Middle" Problem

LLMs have U-shaped attention:

• Strong: Start of context (primacy)
• Strong: End of context (recency)
• Weak: Middle of context

Solution: Put critical rules at TOP of AGENTS.md. Governance first, details later.

5. Signal-to-Noise Ratio

Strip everything that isn't essential:

• No "Welcome to..." preambles
• No marketing text
• No changelogs in core docs

Formats like llms.txt and AGENTS.md mechanically increase SNR.

llms.txt Standard

Machine-readable doc index for agents:

# Project Name

> One-line project description.

## Authentication

- Setup: Environment vars and init
- Server: Cookie handling

## Database

- Schema: Full Prisma schema

Location: /llms.txt at domain root Companion: /llms-full.txt — full concatenated docs, HTML stripped

Security Considerations

This section covers security considerations for the agent-docs skill. Key operations include input validation, core processing, and output verification. Refer to the skill overview for detailed usage instructions.

Inline = Trusted

AGENTS.md is part of your codebase. Controlled, version-pinned.

External = Attack Surface

• Indirect prompt injection via hidden text
• SSRF risks if agents can browse freely
• Dependency on external uptime

Mitigation: Domain allow-lists, human-in-the-loop for external retrieval.

Anti-Patterns

1. Pasting 50 pages — triggers "Lost in the Middle"
2. "See external docs" — agents can't browse autonomously
3. Generic advice — "Write clean code" (use specific constraints)
4. TOC-only docs — indexes without content
5. Trusting retrieval alone — 53% vs 100% pass rate

Advanced Patterns

For detailed guidance on RAG optimization, multi-framework docs, and API templates, see references/advanced-patterns.md.

Validation Checklist

• Critical governance at TOP of doc
• Total inline context under 4K tokens
• Each H2 section self-contained
• No external links without inline summary
• Negative constraints explicit ("Do NOT...")
• File paths and signatures, not full code

Common Rationalizations

Red Flags

• Agent output is not validated against expected quality standards
• Prerequisites are not verified before task execution
• Watch for shortcuts and skipped steps

Verification

After completing this skill, confirm:

• Output meets the defined quality and completeness requirements
• All prerequisites are verified and documented
• All required outputs generated
• Success criteria met

Process

1. Analyze the task requirements
2. Apply domain expertise
3. Verify output quality