page.mdx

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
related	/docs/guides /docs/customization/agent-primitive /docs/customization/llms-txt /docs/customization/sitemaps /docs/customization/mcp /docs/configuration /docs/cli
order	1

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 <Agent> 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, 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

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.

---
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 <Agent> 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

<Agent>
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.
</Agent>

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.

<Agent>
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.
</Agent>

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.

# 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=<slug>
• {page} with Accept: text/markdown in Next.js
• {page} with Signature-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.

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 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
• 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 Signature-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 skill.md tells 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:

curl "https://docs.example.com/docs/installation" \
  -H "Accept: text/markdown"

curl "https://docs.example.com/docs/installation" \
  -H "Signature-Agent: https://chatgpt.com"

Both 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, 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 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.

If a markdown request misses, the response is still markdown. The 404 points the agent to /.well-known/agent.json, /.well-known/agent, /api/docs/agent/spec, search, the requested API markdown route, and sitemap routes so the agent can recover instead of treating the site as a dead end.

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 or /sitemap.md:

{
  "scripts": {
    "build": "docs sitemap generate && next build"
  }
}

Use --manifest-only only when your deployment keeps the runtime route active:

{
  "scripts": {
    "build": "docs sitemap generate --manifest-only && next build"
  }
}

Then add a CI check when generated files are committed:

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:

## 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`
- Confirm the `Signature-Agent` response is `text/markdown` and includes `Vary: Accept, Signature-Agent`
- Confirm successful markdown responses include `Link: <http://localhost:3000/docs>; 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` returns 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.

pnpm exec docs doctor --agent

When you want the result to feed CI, automation, or another agent, use JSON output:

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 <Agent> block.

After deployment, add --url to verify the public routes agents actually call:

pnpm exec docs doctor --agent --url https://docs.example.com

That hosted pass checks discovery, llms.txt, sitemap routes, 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, mcp.<your-domain>/mcp, or mcp.<your-domain>/.

If you want the same public check without leaving the browser, use the hosted Agent readiness 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, 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 <link rel="alternate" type="text/markdown"> 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:

pnpm exec docs robots generate
pnpm exec docs robots generate --append

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.

What you want to see improve over time:

• discovery routes passing
• machine surfaces enabled
• robots.txt allowing docs, markdown, sitemap, 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.

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.

---
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 <Agent> 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

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 <Agent> 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, JSON-LD structured data, llms.txt markdown links, OpenAPI schema discovery, sitemaps, robots.txt, MCP, and the discovery spec?
• do canonical Signature-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, /.well-known/sitemap.md, and robots.txt?
• does docs doctor --agent agree with the state of the site?
• does the hosted Agent readiness 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 for Agent blocks and sibling agent.md
• llms.txt, Sitemaps, and CLI for the discovery layer
• MCP Server for tool-enabled retrieval
• Agent readiness score for the hosted public benchmark and leaderboard
• CLI for docs agent compact
• CLI for docs doctor --agent
• Configuration for the full config surface