{"id":34,"type":"blog","title":"Building an Agent-Readable Knowledge Site","slug":"building-agent-readable-knowledge-site","canonicalUrl":"https://docs.phatysd.me/content/building-agent-readable-knowledge-site","status":"published","revision":2,"publishedAt":"2026-09-19T16:34:11.292Z","updatedAt":"2026-09-19T16:34:11.292Z","hierarchyPath":"Web Blog > Engineering Journal > Content systems","topics":["AI agents","Content architecture","JSON","Markdown"],"tags":["agents","llms","content-api","markdown","json","nextjs"],"related":[{"slug":"public-content-contract-v1","title":"Public Content Contract v1","type":"docs","canonicalUrl":"https://docs.phatysd.me/content/public-content-contract-v1"},{"slug":"web-blog-agent-handbook","title":"Web Blog Agent Handbook","type":"docs","canonicalUrl":"https://docs.phatysd.me/content/web-blog-agent-handbook"}],"body":"# Building an Agent-Readable Knowledge Site\n\nA 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.\n\n## Three representations, one identity\n\nEach published item has one canonical slug and three useful views:\n\n```text\nHuman page: /content/:slug\nMarkdown:   /content/:slug/markdown\nJSON:       /content/:slug/json\n```\n\nThe 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.\n\nThese are not three independent documents. They are three representations of one published row and one revision state.\n\n## Discovery before retrieval\n\nAn 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.\n\nThe 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.\n\n## Identity and freshness\n\nThe public contract includes:\n\n- `slug` and `canonicalUrl` for identity.\n- `status` to prevent drafts from leaking.\n- `revision` for content freshness.\n- `publishedAt` and `updatedAt` for temporal context.\n- `topics`, `tags`, and `related` for navigation.\n- `body` for the authored content.\n\nAn agent should not infer “latest” from URL order or page layout. It should use explicit revision and timestamp fields.\n\n## Why this is a database problem too\n\nThe 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.\n\n## What agents need from documentation\n\nEvery 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.\n\n## Takeaway\n\nAgent-readable content is not “Markdown somewhere on the server.” It is a versioned public contract with discovery, canonical identity, multiple representations, and explicit freshness.\n\n## References\n\n- Repository source: `docs/contracts/public-content.md`.\n- [Next.js Route Handlers](https://nextjs.org/docs/app/building-your-application/routing/route-handlers)\n- [Next.js metadata and sitemap](https://nextjs.org/docs/app/api-reference/file-conventions/metadata)\n- [Cloudflare support for llms.txt](https://developers.cloudflare.com/support/llms-full.txt)\n"}