Behind the Docs Designing Documentation for Agents, Not Just Users - Dachary Carey of MongoDB and Agent-Friendly Docs Expert
Mar 24, 2026
Dachary Carey, a technical writer and documentation strategist at MongoDB who created the Agent-Friendly Documentation Spec, discusses how AI agents struggle to read docs. She highlights surprising agent failure modes, the importance of formats like llms.txt, serving markdown, and making docs discoverable to machines. Practical steps and tools like afdocs are covered.
AI Snips
Chapters
Transcript
Episode notes
Agents Are Tool-Wielding LLM Harnesses
- Agents are harnesses around LLMs that call tools like file reads, web fetches, and code execution to perform tasks on users' behalf.
- Dachary Carey discovered agents (starting with Claude Code) differ by platform and need explicit workflows and indexes like llms.txt to find docs reliably.
Weekend Audit Revealed Widespread Agent Failures
- Dachary audited 673 Anthropic-style skills over a weekend to validate patterns and watched Claude Code fail at reading docs in many ways.
- She wrote tooling, validated ~600 patterns with citations, and kept a running file of failure modes to investigate later.
llms.txt Became An Agent Discovery Shortcut
- The llms.txt (or llm-specific index) proposal wasn't widely adopted for its intended training use but is highly useful as an agent-facing index.
- Dachary found explicitly pointing agents to llms.txt unlocked reliable discovery of markdown content for many agents.