# Write Agent-Facing Docs Assuming the Agent Won't Fetch the Reference ## Claim When writing documentation an AI agent is meant to consume mid-task, I put the critical instruction inline at the point of use rather than trusting the agent to follow a link out to a separate reference file. <!-- atomicity: 1 idea ✓ --> ## Scope & conditions - Holds for skill files, CLAUDE.md-style instructions, and any agent-facing runbook where a specific step is high-stakes (security, data loss, correctness-critical). - Breaks down for genuinely large reference material (full API docs) that can't reasonably be inlined — there, the fallback is inlining the two or three highest-risk gotchas and linking the rest, not inlining everything. - Doesn't mean skip reference files entirely; it means don't rely on a link alone to deliver anything the agent must not miss. ## Evidence Supabase's own agent-skill design bundles a security checklist (RLS, auth, key exposure) directly inside `skill.md` rather than pointing to external docs, because — per the source's cited internal data — agents given MCP tool access alone succeed on tasks like correct RLS policy generation only around 60% of the time, rising substantially once the skill's inline checklist is added. The stated mechanism: agents default to (possibly stale) training data even when a docs-search MCP tool is available, so an external reference link goes unused unless the agent has a strong reason to follow it. ## Links - [[AI & the Future of Knowledge Work MOC]] — documentation written for a machine reader that may never follow the reference - [[AI Agent Safety MOC]] — a documentation practice that prevents an agent acting without the constraint it needed - [[3. Resources/Permanent Notes/Context Not Constraints Is What Unhobbles an Agent]] — because extends; missing context (not missing capability) is the general failure mode, and "agent won't fetch the reference" is a specific mechanism by which context goes missing even when it's technically available. - [[3. Resources/Permanent Notes/Harness Design Can Matter More Than Model Choice for Agent Performance]] — because applies-in; where critical instructions live in the harness is itself a harness-design decision. - [[3. Resources/Permanent Notes/Intent Written on the Outside Compounds While Re-Derived Intent Is Debt]] — because contrasts; that note is about externalizing intent for humans to compound over time, this one is about externalizing it for an agent that won't reliably go looking for it — the delivery mechanism differs even though both argue for writing intent down explicitly. - [[3. Resources/MOCs/Documentation & Technical Writing MOC]] — applies-in: the docs discipline map, "docs that agents read" cluster - [[3. Resources/Permanent Notes/A Docs Page Must State Its Purpose in the Title and Opening Because Agents Lose Navigation]] — applied in: context that lives only in the sidebar is lost when an agent receives a chunk (Washington). ## Tests / falsifiers - Find a skill/instruction file where moving critical content from an inline position to a linked reference file measurably increased agent error rate on the guarded task — supports the claim. - Find a case where inlining everything (no reference files at all) degraded performance by bloating context past the point of useful attention — would bound the claim's scope rather than falsify it outright. - If a future agent generation reliably follows reference links without prompting, this claim's premise (agents are lazy about fetching) stops holding and the practice should be revisited. ## Maintenance - Last tended: 2026-08-16 - Next review: 2026-11-16 ## Source - [[3. Resources/Readwise/Articles/Don't Use Next.js Without These 7 Skills]] — reports Supabase's inline-checklist skill design and the cited ~60%-vs-higher MCP-only success-rate figure (vendor-reported, sponsored segment, unverified independently).