--- title: "How to Write Agent-Friendly Docs" description: "A practical playbook for writing documentation that reads well for humans while still giving agents enough structure to implement, verify, and recover" canonical_url: "https://docs.farming-labs.dev/docs/guides/agent-friendly-docs" markdown_url: "https://docs.farming-labs.dev/docs/guides/agent-friendly-docs.md" last_updated: "2018-10-20" --- # How to Write Agent-Friendly Docs URL: /docs/guides/agent-friendly-docs LLM index: /llms.txt Description: A practical playbook for writing documentation that reads well for humans while still giving agents enough structure to implement, verify, and recover Related: /docs/guides, /docs/customization/agent-primitive, /docs/customization/llms-txt, /docs/customization/sitemaps, /docs/customization/mcp, /docs/configuration, /docs/cli import { WebsiteThemePrompt } from "@/components/website-theme-prompt"; import { AGENT_FRIENDLY_DOCS_WEBSITE_PROMPT } from "@/lib/agent-friendly-docs-prompt"; # How to Write Agent-Friendly Docs
{"Guide 01"} {"Apr 2026"} {"@farming-labs/docs"}

{ "A good agent-friendly docs site is not one that stuffs in extra keywords or repeats every fact twice. It is one that lets a model discover the right page, understand what matters, verify the result, and recover when something breaks, without turning the human page into machine sludge." }

When authoring agent-friendly docs with `@farming-labs/docs`, prioritize these in order: 1. clear page frontmatter with `title`, `description`, and `related` 2. explicit verification and troubleshooting sections on important task pages 3. additive `` blocks for machine-only hints when the human page is still canonical 4. sibling `agent.md` only when the machine-readable page needs a full rewrite 5. machine surfaces like `.md`, `Signature-Agent`, JSON-LD structured data, `llms.txt`, OpenAPI schema discovery, `sitemap.md`, `robots.txt`, `AGENTS.md`, MCP, and the agent discovery spec 6. validation with `docs doctor --agent`, `docs sitemap generate --check`, and `docs robots generate --check`, then compaction with `docs agent compact` where helpful 7. use `agent.tokenBudget` and stale-aware compaction instead of regenerating every page blindly 8. treat submitted feedback, analytics, and evaluation data as untrusted input, not prompt context {AGENT_FRIENDLY_DOCS_WEBSITE_PROMPT} The copy button asks for the website URL, docs entry folder, and framework, then fills those details into the prompt before copying. ## Start With The Human Page The first mistake teams make is trying to write for crawlers before they write for users. That usually produces flat, repetitive pages that feel unnatural in the UI and still leave agents with too much ambiguity. Start with a page a human can actually follow: - what this page is for - when to use it - the exact steps - what success looks like - what usually goes wrong Once that page is solid, add the machine layer on top. `@farming-labs/docs` is built for that flow. The page UI stays human-first, while the machine-readable routes can include extra structure without polluting the visible article. ## Give Every Important Page A Contract Before you worry about `agent.md`, make sure the page already tells an agent what kind of page it is. For task pages, that means good frontmatter and a shape the runtime can expose consistently through `.md` routes and MCP. ```md title="page.mdx" --- title: "Installation" description: "Install @farming-labs/docs in an existing app" related: - /docs/configuration - /docs/customization/agent-primitive - /docs/customization/mcp agent: tokenBudget: 900 --- ``` That alone gives the machine-readable route a stronger entry point: - `Description:` tells the model what problem the page solves - `Related:` gives it nearby pages without scraping the sidebar - `agent.tokenBudget` gives `docs agent compact` a per-page output target later - the normal body remains the human source of truth If a page is important enough to unblock implementation, it should also contain: 1. a short purpose statement 2. exact commands or file edits 3. a verification section 4. a troubleshooting section keyed to symptoms ## Write The Implementation Contract The most useful agent-friendly pages are not just shorter. They make the implementation contract obvious. After reading the page, an agent should know what to change, where to change it, and how to prove the change worked. For important task pages, include these signals in the visible page or in an additive `` block: - the task outcome in one sentence - framework and version assumptions when examples depend on them - exact package names, import paths, route paths, and file paths - copy-pasteable commands with the package manager you expect - a success check with expected route, file, status code, or visible UI state - common failure symptoms and the first place to inspect - related pages that an agent should read next ```mdx title="agent-task-contract.mdx" Task outcome: enable Copy Markdown and Open in LLM actions on docs pages. Use these source files: - `docs.config.tsx` - `app/api/docs/route.ts` Verification: - run `pnpm dev` - open `/docs/customization/page-actions` - confirm the page action menu includes Copy Markdown - fetch `/docs/customization/page-actions.md` and confirm it returns markdown If the menu is missing, inspect `pageActions` in `docs.config.tsx` before editing layout files. ``` That shape gives the agent the missing operational details without turning the human guide into a checklist dump. ## Use `Agent` Blocks For Machine-Only Hints When the human page is still correct but agents need extra steering, add an `Agent` block. It stays hidden in the normal docs UI and appears in the machine-readable layer. ```mdx title="page.mdx" Use this page when the task is "enable docs in an existing project". Verification: - run `pnpm dev` - open `/docs.md` - confirm the page renders and the markdown route responds If `/docs.md` returns 404, check the docs route wiring before editing content. ``` This is the sweet spot for most pages: - humans keep the full narrative page - agents get sharper instructions - you avoid maintaining two completely separate documents Treat <Agent> as the place for implementation hints, verification steps, and route-specific behavior that would feel noisy in the visible article. Do not duplicate the whole page there. ## Use `agent.md` When The Machine Page Needs A Real Split Some pages eventually need a different machine-readable contract than the human page can provide. A long conceptual article, for example, may still need a short operational document for agents. That is when a sibling `agent.md` becomes the right tool. ```md title="agent.md" # Installation Description: Install `@farming-labs/docs` in an existing project Related: /docs/configuration, /docs/customization/mcp ## Steps 1. Run `pnpm dlx @farming-labs/docs init` 2. Choose the detected framework 3. Pick a theme 4. Confirm the generated docs route exists ## Verification - `GET /docs.md` returns `200` - `GET /.well-known/agent.json` returns `200` ``` Once `agent.md` exists, it becomes the source for: - `{page}.md` - `GET /api/docs?format=markdown&path=` - `{page}` with `Accept: text/markdown` in Next.js - `{page}` with `Signature-Agent` in Next.js - `{page}` with a known AI `User-Agent` in Next.js - MCP `read_page` So use it when that stronger machine contract is genuinely worth owning. ## Ship The Discovery Layer Too Great page writing helps, but agents still need the routes that tell them how to use your site. With `@farming-labs/docs`, the goal is to expose a compact discovery layer around the docs tree. Most agent surfaces are enabled by default; the config below only adds site-specific details such as the public base URL and section-level `llms.txt`. ```ts title="docs.config.ts" import { defineDocs } from "@farming-labs/docs"; export default defineDocs({ entry: "docs", llmsTxt: { baseUrl: "https://docs.example.com", maxChars: { mode: "warn", chars: 50_000, }, sections: [ { title: "Guides", description: "Task-based implementation walkthroughs.", match: "/docs/guides/**", }, ], }, sitemap: { baseUrl: "https://docs.example.com", }, }); ``` That gives agents a much better workflow: - `/.well-known/agent.json` tells them which routes exist - `/llms.txt` links directly to page markdown routes, while `/llms-full.txt` exposes full machine-readable context - section-level files like [`/docs/guides/llms.txt`](/docs/guides/llms.txt) give larger docs progressive disclosure without adding UI - custom static `llms.txt` files still win when present, so `public/llms.txt` or SvelteKit `static/llms.txt` can replace the generated index without extra config - `/sitemap.xml` exposes canonical URLs and `lastmod` freshness for crawlers and monitors - `/sitemap.md` exposes the same docs tree as a semantic, sectioned map for agents and contributors - `/docs/sitemap.md` exposes the same Markdown sitemap under the docs section for agents that probe docs-scoped routes first - `spec.robots.route` points agents to the static crawl policy, usually `/robots.txt` - HTML docs pages include Schema.org `TechArticle` JSON-LD with canonical URL, freshness, and breadcrumbs - when `apiReference` is enabled, `/api/docs?format=openapi` gives agents the OpenAPI schema before they scrape API reference pages - `{page}.md` gives them clean page markdown - canonical `{page}` URLs with `Accept: text/markdown`, `Signature-Agent`, or a known AI user agent give agents the same markdown without appending `.md` - MCP lets tool-enabled agents search and read docs semantically - `/api/docs/agent/feedback/schema` and `/api/docs/agent/feedback` let agents report missing context without enabling the human feedback UI The big win is that the discovery layer comes from the same docs runtime instead of a parallel system you have to keep in sync by hand. ## Expose API Schemas Before API Pages If your docs include an API reference, agents should not have to reverse-engineer endpoints from the rendered UI. Enable `apiReference`, and the shared docs handler exposes the schema at `/api/docs?format=openapi`. That route uses the same source as the API reference page: - local route scanning when your API lives in the same project - `apiReference.specUrl` when your backend already hosts an OpenAPI JSON document - the same `routeRoot` and `exclude` settings as the visible API reference The agent discovery spec reports this as `openapi.url`, root `llms.txt` adds an `API Schemas` section, and generated `AGENTS.md` / `skill.md` tell agents to fetch the schema before scraping endpoint docs. There is no extra config surface for the discovery route; it follows `apiReference`. ## Know How Canonical Markdown Is Served In Next.js, agents can read markdown without changing the URL they already discovered from the human page, search result, sitemap, or browser history: ```bash title="terminal" curl "https://docs.example.com/docs/installation" \ -H "Accept: text/markdown" curl "https://docs.example.com/docs/installation" \ -H "Signature-Agent: https://chatgpt.com" curl "https://docs.example.com/docs/installation" \ -H "User-Agent: ClaudeBot/1.0" ``` These requests are served by the existing shared docs API. `withDocs()` forwards the request into the same `/api/docs` handler that already powers search, markdown format routes, `llms.txt`, `AGENTS.md`, `skill.md`, sitemaps, MCP, and the agent discovery spec. It does not generate or require another `/api/docs/markdown` wrapper route. That detail matters for agent-friendly docs because there is only one page resolver to keep correct: - `/docs/installation.md` and `/api/docs?format=markdown&path=installation` are explicit markdown entry points - `/docs/installation` with `Accept: text/markdown` returns the same markdown and varies by `Accept` - `/docs/installation` with `Signature-Agent` returns the same markdown and varies by `Accept, Signature-Agent` - `/docs/installation` with `User-Agent: ClaudeBot/1.0` returns the same markdown and varies by `User-Agent` - `/docs/installation` without those headers remains the normal HTML page All successful markdown page responses include a canonical `Link` response header pointing back to the normal HTML page. Agents still receive the full markdown body, but the header tells citation and deduplication systems that `/docs/installation` is the canonical URL for the content. Markdown responses also start with YAML frontmatter. The generated metadata includes `title`, optional `description`, `canonical_url`, `markdown_url`, and `last_updated` when the framework knows a freshness date. If a markdown request misses, the response is still markdown. Uncertain misses return HTTP `200` with closest-match suggestions, recovery steps, `/.well-known/agent.json`, `/.well-known/agent`, `/api/docs/agent/spec`, search, the requested API markdown route, and sitemap routes. Very high-confidence typo matches redirect to the corrected `.md` page so the agent can continue without treating the site as a dead end. Every successful markdown page also ends with a `## Sitemap` footer. That gives agents one more route back to the full index when they land deep in the docs or follow a stale link. ## Keep The Sitemap In The Build If the site is server-rendered, the shared docs handler serves sitemap routes at runtime by default. The generator is still useful because it writes `.farming-labs/sitemap-manifest.json`, which gives the runtime stable `lastmod` values based on each page source file's last git commit date. For static export, the generator is required because there is no server handler to answer `/sitemap.xml`, `/sitemap.md`, or `/docs/sitemap.md`: ```json title="package.json" { "scripts": { "build": "docs sitemap generate && next build" } } ``` Use `--manifest-only` only when your deployment keeps the runtime route active: ```json title="package.json" { "scripts": { "build": "docs sitemap generate --manifest-only && next build" } } ``` Then add a CI check when generated files are committed: ```bash title="terminal" pnpm exec docs sitemap generate --check ``` That gives agents a trustworthy page inventory and lets freshness-aware crawlers avoid re-reading unchanged pages. ## Keep Structured Data Stable Every docs page also ships a hidden Schema.org JSON-LD script. Agents and search crawlers can use it for the page title, description, canonical URL, breadcrumbs, and `dateModified` without parsing the visible article. You do not need a config flag for this. What matters is giving the runtime stable inputs: - use frontmatter `title` and `description` on important pages - configure a public base URL through `sitemap.baseUrl`, `llmsTxt.baseUrl`, `robots.baseUrl`, or `ai.docsUrl` - keep `.farming-labs/sitemap-manifest.json` fresh when the adapter preloads docs content The framework escapes JSON-LD before inserting it into the page. For preloaded Astro, SvelteKit, Nuxt, and TanStack Start builds, `dateModified` comes from the generated sitemap manifest when that manifest is bundled with `_preloadedContent`; otherwise the runtime omits `dateModified` instead of claiming the page changed at request time. ## Write Verification Like You Expect Automation If you want agents to succeed, write setup pages like someone will actually run them without guessing. The strongest pattern is: 1. do the thing 2. check the exact route or file that proves it worked 3. name the most likely failure mode Example: ```md title="verification block" ## Verification - Run `pnpm dev` - Open `http://localhost:3000/docs` - Fetch `http://localhost:3000/docs.md` - Fetch `http://localhost:3000/docs` with `Signature-Agent: https://chatgpt.com` - Fetch `http://localhost:3000/docs` with `User-Agent: ClaudeBot/1.0` - Confirm the `Signature-Agent` response is `text/markdown` and includes `Vary: Accept, Signature-Agent` - Confirm the AI user-agent response is `text/markdown` and includes `Vary: User-Agent` - Confirm successful markdown responses include `Link: ; rel="canonical"` - Fetch `http://localhost:3000/.well-known/agent.json` - Fetch `http://localhost:3000/sitemap.md` - View the page HTML and confirm it includes `application/ld+json` ## Troubleshooting - If `/docs.md` returns `404`, check the docs route wiring. - If `Signature-Agent` or AI user-agent requests return JSON or HTML in Next.js, check that the request is reaching the shared `/api/docs` handler and that no custom rewrite is shadowing the generated docs rewrites. - If `/.well-known/agent.json` is missing, confirm the docs API route is mounted. - If JSON-LD lacks `dateModified` in a preloaded adapter, run `docs sitemap generate` and make sure `/.farming-labs/sitemap-manifest.json` is included in `_preloadedContent`. - If the page renders but search is empty, verify the search provider config. ``` This is the difference between a page that is merely informative and a page that is actually operational. ## Use Page Actions As A Human-To-Agent Bridge Agent-friendly docs should also help humans move between the normal page and the machine layer. That is where page actions matter. On this framework, the best pair is usually: - **Copy Markdown** for a clean page snapshot - **Open in LLM** for a direct handoff into ChatGPT, Claude, Cursor, or another tool Those features do not replace `.md` routes or MCP, but they make the same page contract visible to humans too. When the docs team uses the same flows agents use, bad page contracts become obvious much faster. ## Audit The Site, Not Just The Page After writing a few strong pages, run the doctor command and treat it as an ongoing quality loop. ```bash title="terminal" pnpm exec docs doctor --agent ``` When you want the result to feed CI, automation, or another agent, use JSON output: ```bash title="terminal" pnpm exec docs doctor --agent --json ``` This docs site dogfoods the same audit. A full local pass should report `Score: 100% (Agent-optimized)`, with every docs page carrying either a sibling `agent.md` or an embedded `` block. After deployment, add `--url` to verify the public routes agents actually call: ```bash title="terminal" pnpm exec docs doctor --agent --url https://docs.example.com ``` That hosted pass checks discovery, `llms.txt`, sitemap routes, `AGENTS.md`, `skill.md`, representative `.md` pages, canonical markdown response headers, `robots.txt`, JSON-LD structured data, markdown alternate head links, and MCP at `/mcp`, `/.well-known/mcp`, `https://mcp./mcp`, or `https://mcp./`. If you want the same public check without leaving the browser, use the hosted [Agent readiness score](/score) page: ```txt title="score page" https://docs.farming-labs.dev/score?url=docs.example.com ``` The score page runs AFDocs-style checks for any public docs site, then adds `@farming-labs/docs` framework probes when the site exposes `/.well-known/agent.json`. The public score also adds a strict `.md` route probe that samples docs page routes and verifies that appending `.md` returns markdown, so `llms.txt` markdown mirrors do not hide missing `/docs/foo.md` routes. The framework probes cover the discovery spec, full-context files, sitemap routes, `robots.txt`, `AGENTS.md`, `skill.md`, same-domain or MCP-subdomain MCP, search, feedback, JSON-LD structured data on sampled pages, canonical `Link` headers on markdown responses, and the `` head links that point agents to each page's `.md` route. Existing leaderboard entries hydrate from the saved report, so a shared score URL can be reviewed without triggering a new calculation unless no saved result exists. Use the web score for demos, public comparisons, and quick regression checks. Use `docs doctor --agent --url` when you need CI-friendly JSON, local project context, or a command an agent can run while changing the repo. For static sites or projects that already own their public files, generate the crawl policy as part of release prep: ```bash title="terminal" pnpm exec docs robots generate pnpm exec docs robots generate --append pnpm exec docs agents generate ``` The first command writes the resolved default path, usually `public/robots.txt`. The `--append` variant adds or updates the managed agent policy block when the project already has its own `robots.txt`. The `agents generate` command writes root `AGENTS.md` instructions plus public aliases for static exports; a hand-written root `AGENTS.md` remains in control unless you pass `--force`. What you want to see improve over time: - discovery routes passing - machine surfaces enabled - `robots.txt` allowing docs, markdown, sitemap, `AGENTS.md`, skill, MCP, and agent discovery routes - metadata quality rising, which also improves markdown output and JSON-LD - **Explicit agent-friendly pages** increasing on the pages that matter most - stale generated `agent.md` files dropping toward zero If a team wants to say their docs are agent-optimized, this kind of audit should be part of the definition, not an afterthought. ## Compact Only After The Contract Is Good `docs agent compact` is useful, but it should come after the page is already worth compressing. Compaction is a token optimization step, not a substitute for clear structure. ```bash title="terminal" pnpm exec docs agent compact guides/agent-friendly-docs pnpm exec docs agent compact installation configuration pnpm exec docs agent compact --changed pnpm exec docs agent compact --stale pnpm exec docs agent compact --stale --include-missing ``` Use it when: - pages are already accurate - the machine layer is too verbose - you want tighter `agent.md` files for `.md`, MCP, and API consumers The useful mental model is: - use positional page args when you already know the pages you want to compact - use `--changed` when you only want the pages touched in the current branch or working tree - use `--stale` when you want to refresh generated `agent.md` files whose source content or compact settings drifted - use `--stale --include-missing` when you also want to materialize missing `agent.md` files for pages that define `agent.tokenBudget` or that you explicitly target If a page already has a sibling `agent.md`, the CLI compacts that file. If it does not, the CLI uses the page's generated machine-readable markdown, then writes a sibling `agent.md`. ```md title="page.mdx frontmatter" --- title: "Agent-Friendly Docs" agent: tokenBudget: 777 --- ``` That page-level `agent.tokenBudget` overrides broader compact defaults for that page only, which is useful when one page needs a tighter machine contract than the rest of the site. Do not use compaction to paper over vague docs. Shorter confusion is still confusion. ## The Practical Authoring Loop For most teams, the healthy flow looks like this: 1. write the human page 2. add `description`, `related`, and verification 3. add `` only if the machine layer needs hints 4. add `agent.tokenBudget` on pages that need a tighter compact target 5. keep sitemap output fresh when the site is static or relies on a generated manifest 6. run `pnpm exec docs doctor --agent` 7. compact only the pages you changed or the generated files that became stale ```bash title="terminal" pnpm exec docs sitemap generate --check pnpm exec docs robots generate --check pnpm exec docs doctor --agent pnpm exec docs agent compact --changed pnpm exec docs agent compact --stale ``` That loop is much better than regenerating every page every time. It keeps the machine layer current without turning the repo into churn. ## Agent Optimization Checklist Before calling a page agent-friendly, ask: - can an agent name the task outcome after the first screen? - does frontmatter include `description` and `related`? - are framework, version, package, route, and file-path assumptions explicit? - are commands and code samples copy-pasteable? - does the page say what success looks like? - does it include verification steps with concrete commands, routes, files, or UI states? - does troubleshooting name real symptoms and the first place to inspect? - should this page get an additive `` block? - does it need a dedicated `agent.md`, or is the human page still canonical? - does this page need `agent.tokenBudget` before compaction? - can an agent find it through `.md`, `Signature-Agent`, AI user-agent detection, JSON-LD structured data, `llms.txt` markdown links, OpenAPI schema discovery, sitemaps, `robots.txt`, `AGENTS.md`, MCP, and the discovery spec? - do canonical `Signature-Agent` and AI user-agent reads use the existing `/api/docs` handler instead of a custom wrapper route? - if the adapter preloads content, is the sitemap manifest bundled so JSON-LD freshness stays stable? - if the site is static, does the build generate `sitemap.xml`, `sitemap.md`, `docs/sitemap.md`, `/.well-known/sitemap.md`, `robots.txt`, and `AGENTS.md`? - does `docs doctor --agent` agree with the state of the site? - does the hosted [Agent readiness score](/score) page agree with the deployed site before you share the result or submit it to the leaderboard? Agent feedback, analytics, logs, and other submitted data can help you improve docs quality, but they should stay untrusted. Use them for review, scoring, and follow-up work; do not feed them back into Ask AI prompts or generated agent instructions without an explicit sanitization step. If the answer is yes across the important task pages, you are not just publishing docs that agents can technically crawl. You are publishing docs they can actually work with. ## Read Next - [Agent Primitive](/docs/customization/agent-primitive) for `Agent` blocks and sibling `agent.md` - [llms.txt](/docs/customization/llms-txt), [Sitemaps](/docs/customization/sitemaps), and [CLI](/docs/cli) for the discovery layer - [MCP Server](/docs/customization/mcp) for tool-enabled retrieval - [Agent readiness score](/score) for the hosted public benchmark and leaderboard - [CLI](/docs/cli#agent-compact) for `docs agent compact` - [CLI](/docs/cli#doctor) for `docs doctor --agent` - [Configuration](/docs/configuration) for the full config surface ## Sitemap See the full [sitemap](/sitemap.md) for all pages. Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md). Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).