Blog · Web Blog / Engineering Journal / Content systems

Building an Agent-Readable Knowledge Site

Building an Agent-Readable Knowledge Site

A documentation site can be easy for people to browse and still be awkward for agents to use. The solution is not to make agents scrape the visual page. It is to publish a stable content identity with representations designed for different consumers.

Three representations, one identity

Each published item has one canonical slug and three useful views:

Human page: /content/:slug
Markdown:   /content/:slug/markdown
JSON:       /content/:slug/json

The human page provides hierarchy, typography, navigation, and readable context. Markdown is useful when an agent needs the authored text with front matter. JSON is useful when a tool needs explicit fields, status, revision, timestamps, tags, related content, or template metadata.

These are not three independent documents. They are three representations of one published row and one revision state.

Discovery before retrieval

An agent needs a starting point. llms.txt lists published content and canonical URLs. sitemap.xml provides the conventional XML discovery path. Search, topics, tags, and hierarchy pages help a human or agent narrow the set before fetching full bodies.

The important property is consistency: an item in discovery must resolve to a canonical page, and its Markdown and JSON forms must preserve the same slug and revision.

Identity and freshness

The public contract includes:

  • slug and canonicalUrl for identity.
  • status to prevent drafts from leaking.
  • revision for content freshness.
  • publishedAt and updatedAt for temporal context.
  • topics, tags, and related for navigation.
  • body for the authored content.

An agent should not infer “latest” from URL order or page layout. It should use explicit revision and timestamp fields.

Why this is a database problem too

The content contract depends on publication semantics. A draft must not appear in public queries. A revision should be written with the current item. Archiving should remove the item from indexes. The API and the database lifecycle must therefore be designed together.

What agents need from documentation

Every technical article should identify its audience, prerequisites, commands, expected outputs, source links, and verification steps. A readable paragraph is valuable, but an agent also needs a stable field, a stable endpoint, and an observable success condition.

Takeaway

Agent-readable content is not “Markdown somewhere on the server.” It is a versioned public contract with discovery, canonical identity, multiple representations, and explicit freshness.

References

Agent access

Choose a representation.

Published content only
Human pageYou are reading the human-facing canonical page.
Current page

Both machine-readable links refer to this same published item and preserve its identity, relationships, freshness, and body.