Agent Primitive

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

• <Agent>...</Agent> inside page.mdx for additive machine-only context
• agent.md beside page.mdx for a full machine-readable override

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

• the shared docs API supports GET /api/docs?format=markdown&path=<slug>
• in Next.js, withDocs() also serves /docs/<slug>.md
• in Next.js, Accept: text/markdown on /docs/<slug> returns the same markdown
• agents can discover the configured contract with GET /.well-known/agent.json, fall back to GET /.well-known/agent, or use the canonical framework route at GET /api/docs/agent/spec

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.

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.

# 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:

• /docs/installation for the normal UI page
• /docs/installation.md for machine-readable markdown that includes the Agent block
• /docs/installation with Accept: text/markdown for the same machine-readable markdown
• MCP read_page("/docs/installation") with the same page-level machine context

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.

# 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 endpoint, `llms.txt` routes, skills install
command, locale handling, and feedback endpoints.

Recommended bootstrap flow:

1. Fetch `/.well-known/agent.json`, then fall back to `/.well-known/agent`.
2. Use `spec.markdown.pagePattern` or `spec.markdown.acceptHeader` to read relevant docs pages as markdown.
3. Use `spec.search.endpoint` when you need to find the right page first.
4. Use `spec.mcp.endpoint` and tools when MCP is enabled and your environment supports MCP.
5. If feedback is enabled, fetch `spec.feedback.schema` before submitting to `spec.feedback.submit`.

Do not scrape the HTML page when markdown, search, 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 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.

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

In that setup:

• /docs/customization/agent-primitive renders page.mdx
• /docs/customization/agent-primitive.md returns agent.md
• MCP read_page("/docs/customization/agent-primitive") also prefers agent.md

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

• exact file paths and command ordering
• implementation-only constraints
• testing or validation steps
• a shorter, more targeted page than the human docs should show

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.

If feedback.agent is enabled in docs.config, agents can read the schema first and then post structured feedback back into the shared docs API:

• schema: /api/docs/agent/feedback/schema
• submit: /api/docs/agent/feedback

Example additive block:

# 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:

• the feedback instruction belongs to one page or workflow
• you want the agent-facing .md route to carry the reporting contract
• the human page should stay uncluttered

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. In Next.js, all three return the same small JSON document generated from docs.config.

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

• which docs site and entry they are reading
• which locales are configured and which query parameter selects one
• which agent-facing capabilities are enabled
• where the shared docs API lives
• which agent discovery URL is the default and which public route to use as fallback
• where to search the docs with a query
• which markdown URL pattern to use for page reads
• where to fetch llms.txt and llms-full.txt content, including the default public URLs and the public /.well-known aliases when available
• how to install the published Skills pack and which skill is recommended first
• whether MCP is enabled, which endpoint to call, and which tools are available
• whether agent feedback is enabled, plus the schema and submit endpoints to use

For Next.js apps, withDocs() wires /.well-known/agent.json, /.well-known/agent, and /api/docs/agent/spec into the same shared /api/docs handler automatically. The generated spec also includes agentSpecDefault: "/.well-known/agent.json" and agentSpecFallback: "/.well-known/agent" so downstream integrations do not need to hard-code the preference themselves.

Choosing Between Them

• Use Agent when the normal page should stay the source of truth and you only need extra machine context
• Use agent.md when the machine-readable page should become its own focused document
• Use both patterns page-by-page; you do not need a global config flag to turn them on

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

• use Agent or agent.md to make one page more useful to agents
• use skills when the knowledge should be bundled as a reusable workflow outside a single page

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

npx skills add farming-labs/docs

Common choices include:

• getting-started for setup and installation
• cli for init, upgrade, and CLI flags
• configuration for docs.config options
• page-actions for Copy Markdown and Open in LLM behavior

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