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:
slugandcanonicalUrlfor identity.statusto prevent drafts from leaking.revisionfor content freshness.publishedAtandupdatedAtfor temporal context.topics,tags, andrelatedfor navigation.bodyfor 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
- Repository source:
docs/contracts/public-content.md. - Next.js Route Handlers
- Next.js metadata and sitemap
- Cloudflare support for llms.txt
Agent access
Choose a representation.
Both machine-readable links refer to this same published item and preserve its identity, relationships, freshness, and body.