Home /

docs

Agent Primitive

@farming-labs/docs gives you two page-level primitives for agent-facing documentation:

The same page model also powers the built-in machine-readable routes:

Same URL, different representation

/docs/installation stays the human HTML page by default. In Next.js, send Accept: text/markdown or Signature-Agent to that same URL when an agent or script wants the machine-readable version without appending .md. In the other adapters, use /docs/installation.md or the format=markdown API route.

These reads go through the existing shared /api/docs handler. You do not need another markdown-specific API wrapper, and adding one usually makes discovery, caching, and 404 recovery harder to keep aligned.

The markdown response varies by the relevant request headers, so CDNs do not mix the HTML and markdown representations for the same URL. A browser can keep receiving cached HTML while an agent receives cached markdown for /docs/installation.

Successful markdown responses include a canonical Link response header pointing to the normal docs page, so agents can read /docs/installation.md while still citing /docs/installation.

Missing markdown pages return a markdown 404 with recovery links to the agent discovery spec, search endpoint, and sitemap routes.

Use Agent when the human page is already mostly correct and just needs a little extra implementation context. Use agent.md when the entire machine-readable page should be more operational, more structured, or fully different from the visible UI page.

Built in by default

Agent is already part of the default MDX component map. You can write <Agent> directly in any docs page without adding it to docs.config.ts, mdx-components.tsx, or a custom components map. If you intentionally build your own MDX map from scratch, import it from @farming-labs/theme or @farming-labs/theme/mdx.

Use Agent For Additive Context

Agent is the lightweight option. It keeps the normal page clean while adding agent-only guidance to the .md route and MCP fallback for that page.

app/docs/installation/page.mdx
# Installation

Human-facing setup instructions.

<Agent>
You are an implementation agent.
Prefer the CLI path first unless the user explicitly wants manual setup.
Keep framework-specific package names exact.
</Agent>

That gives you:

Bootstrap Agents With The Spec

Use the docs landing page or another high-traffic route to tell implementation agents how to discover the machine-readable surface before they start reading individual pages. No setup is required first; the default runtime already understands the Agent primitive.

app/docs/page.mdx
# Documentation

Human-facing overview.

<Agent>
You are reading this docs site as an implementation agent.

Before implementing from these docs, fetch `/.well-known/agent.json` from the same origin. If that
is unavailable, fall back to `/.well-known/agent`. Use that JSON as the source of truth for the docs
entry path, markdown route pattern, search endpoint, MCP endpoints, `llms.txt` routes, skills install
command, `sitemap.xml` / `sitemap.md` routes, `robots.txt` route, `AGENTS.md` route, `skill.md` route, locale
handling, and feedback endpoints.

Recommended bootstrap flow:

1. Fetch `/.well-known/agent.json`, then fall back to `/.well-known/agent`.
2. Read `spec.skills.route` or `spec.skills.wellKnown` when you want the concise site skill.
3. Use `spec.markdown.pagePattern`, `spec.markdown.acceptHeader`, or `spec.markdown.signatureAgentHeader` to read relevant docs pages as markdown.
4. Use `spec.search.endpoint` when you need to find the right page first.
5. Use `spec.sitemap.markdown.route` for the semantic docs map and `spec.sitemap.xml.route` for canonical freshness when sitemap is enabled.
6. Fetch `spec.robots.route` when you need to confirm crawler and AI-agent access policy.
7. Use `spec.mcp.wellKnownEndpoint` or `spec.mcp.publicEndpoint` when available, otherwise `spec.mcp.endpoint`, when MCP is enabled and your environment supports MCP.
8. If `spec.feedback.enabled` is true, fetch `spec.feedback.schema` before submitting to `spec.feedback.submit`.

Do not scrape the HTML page when markdown, search, sitemap, robots, MCP, or `llms.txt` routes are
available in the spec.
</Agent>

This works well on /docs because many agents start there first. The instruction stays hidden from the human UI, but it appears when an agent reads /docs.md, requests /docs with Accept: text/markdown or Signature-Agent, or reads the page through MCP.

Use agent.md For A Full Override

When the machine-readable page should be completely different, add a sibling agent.md.

page folder
app/docs/customization/agent-primitive/
  page.mdx
  agent.md

In that setup:

This is the stronger option. Use it when agents need:

Generate agent.md From The CLI

You do not have to hand-write every override. docs agent compact can take the resolved machine-readable page for one or more routes and write a sibling agent.md automatically.

It uses the same resolution order as the runtime:

That makes it a good fit when you want to start with additive <Agent> context and later freeze a shorter, more operational machine page.

terminal
pnpm exec docs agent compact customization/agent-primitive
pnpm exec docs agent compact --all

Once the file is written:

The visible UI page still renders page.mdx. Only the machine-readable surface changes.

Audit The Agent Surface

After you add <Agent> blocks, agent.md, AGENTS.md, skill.md, or discovery endpoints, use the Doctor section of the CLI docs to audit whether the machine-facing layer is actually wired and visible the way you expect.

That is the quickest follow-up after authoring page-level primitives. If you add an Agent block or sibling agent.md, the doctor output should reflect stronger explicit agent-friendly page coverage instead of only looking correct in the UI.

Point Agents At Feedback Endpoints

Page primitives are also a good place to tell agents how to report whether the docs were enough to complete a task.

Agent feedback is enabled by default unless the site opts out. Agents can read the schema first and then post structured feedback back into the shared docs API:

Example additive block:

app/docs/installation/page.mdx
# Installation

Human-facing setup instructions.

<Agent>
If this page was enough to complete the task, or if something was missing, fetch the feedback
schema from `/api/docs/agent/feedback/schema` first. Use the returned schema as the source of truth
for the request body, then submit structured feedback to `/api/docs/agent/feedback`.

For the default schema, the body looks like:
{
  "context": { "page": "/docs/installation", "source": "md-route" },
  "payload": { "task": "install docs", "outcome": "implemented" }
}
</Agent>

That works especially well when:

Agent Discovery

GET /.well-known/agent.json is the preferred public discovery URL. GET /.well-known/agent is the public fallback, and GET /api/docs/agent/spec is the canonical framework route. Next.js wires these with withDocs(). TanStack Start, SvelteKit, Astro, and Nuxt scaffold one public forwarder each, so the well-known aliases share the same docs server handler.

Agents should fetch it before choosing a transport. It tells them:

The generated spec includes agentSpecDefault: "/.well-known/agent.json" and agentSpecFallback: "/.well-known/agent" so downstream integrations do not need to hard-code the preference themselves. It also includes robots.route so agents can find the static crawl policy without guessing.

The skill document is available at GET /skill.md, with GET /.well-known/skill.md as the well-known alias and GET /api/docs?format=skill as the shared API format. Put a skill.md file at the project root, beside docs.config.ts, when you want custom site-specific instructions. If that file is missing, the framework generates a short fallback from config that points agents to markdown, search, MCP, llms.txt, sitemap routes, robots.txt, feedback, and the reusable Skills CLI install command.

AGENTS.md is available at GET /AGENTS.md, with GET /.well-known/AGENTS.md as the well-known alias and GET /api/docs?format=agents as the shared API format. It is generated by default as a coding-agent operating guide that points to markdown routes, llms.txt, sitemap routes, robots.txt, OpenAPI, MCP, feedback, and upgrade guidance. Put AGENTS.md at the project root when you want fully custom instructions; that root file overrides both dynamic endpoints. AGENT.md is also accepted as a compatibility alias.

Choosing Between Them

Page Primitives Vs Skills

Agent and agent.md are page-scoped primitives. They are the right fit when the machine context belongs to a single docs route.

Use /AGENTS.md when a coding agent needs site-level operating instructions for this repo or docs deployment. Use /skill.md when an agent needs a concise installable-skill style guide for this hosted docs site. Use an installable skill when the guidance should be reusable across many pages or workflows, such as setup, CLI usage, theme creation, page actions, or deeper configuration tasks.

In practice, the two features work well together:

This repo already publishes skills under skills/farming-labs/. Install them with:

terminal
npx skills add farming-labs/docs

Common choices include:

Use page primitives for route-level context. Use skills for repeatable product knowledge that should travel across tasks.