Publish your whole knowledge base as an Open Knowledge Format bundle — a tree of Markdown concept files with typed front matter — so an agent can ingest the entire corpus in one fetch instead of scraping page by page.
What it is #
The Open Knowledge Format (OKF) is a convention for packaging a body of knowledge as a tree of Markdown files an agent can consume directly. Each file is a concept: a YAML front-matter block followed by Markdown prose. The only hard requirement is a non-empty type
field; the format leans on a small set of recommended fields (title
, description
, resource
, tags
, timestamp
) and lets producers add their own keys, which consumers must preserve rather than reject.
A bundle is otherwise plain files and folders. index.md
files give progressive disclosure — a reader can list a directory without parsing every concept. A root log.md
records change history newest-first. A references/
directory mirrors external standards as first-class concepts so a check can cite them with a bundle-relative link. There is no manifest, no schema server, and no runtime: a bundle is the directory itself.
Why it matters #
One ingest, not N scrapes. An agent that wants your whole corpus gets it in a single download instead of crawling every HTML page and stripping navigation.Typed, predictable structure. Every concept declares what it is. Front matter carries the metadata an agent would otherwise have to infer.Graceful for consumers. Conformance is deliberately loose — unknown types, extra keys, and missing optional fields must not cause rejection — so a bundle stays usable as it grows.
OKF deliberately leaves serving and discovery out of scope. A bundle on its own is undiscoverable; pair it with a discovery surface — an AI Catalog entry and an llms.txt pointer — so agents can find it.
How to implement #
Generate the bundle from your existing source of truth; do not hand-maintain a second copy. For each item, emit <path>.md
with a type
and the recommended fields, reusing the same Markdown body you already serve. Emit an index.md
per directory (no front matter, except the bundle root, which may carry okf_version
). Add a log.md
from your change history. Mirror each cited standard once under references/
and link checks to it. Offer the tree browsably and, optionally, as a single archive for “take everything” consumers. Then advertise it.
This site ships it: the bundle is generated from the same content collection as every other surface and served browsable at /okf/, with the whole tree packaged as
. Each check carries its
/okf.tar.gz
status
as an RFC 2119 conformance
keyword and links to the standard it derives from; every cited source is mirrored under . The bundle is advertised in our
/okf/references/
[AI Catalog](/spec/agent-readiness/agentic-resource-discovery/)and in
[. Its](/llms.txt)
/llms.txt
mediaType
is interim and unregistered (application/okf-bundle+gzip
) pending a blessed OKF media type.## Common mistakes
- Hand-authoring the bundle so it drifts from the source. Generate it.
- Putting front matter in
index.md
files — only the bundle-rootindex.md
may carry it. - Shipping the bundle with no way to find it. OKF solves packaging, not discovery; advertise it separately.
- Claiming a registered media type the artefact does not have. Until OKF has one, declare an honest interim type.
Verification #
- Every non-index, non-log
.md
parses as YAML front matter with a non-emptytype
. index.md
files carry no front matter (except the root’sokf_version
).- Concept count matches your source corpus; the tree round-trips cleanly from the archive.
- The bundle is reachable from at least one discovery surface (AI Catalog entry,
llms.txt
, or aLink
header).
Related topics #
Sources & further reading #
Open Knowledge Format (OKF) specification— Google - Open Knowledge Format — reference implementation and samples— Google - Agentic Resource Discovery (ARD) specification— ARD Project (Linux Foundation)