Open Knowledge Format: Just Markdown Your Agent Can Read
Google's Open Knowledge Format is a tiny, vendor-neutral spec for the context an AI agent needs: a bundle of markdown files with YAML frontmatter, one required field per concept, no SDK and no lock-in. Here is what it is, why the permissive consumer contract is the clever part, and what I shipped on top of it: the okf skill, a bundle collection, and OKF Viewer, a desktop app that reads any bundle as a graph.
An AI agent is only as good as the context you hand it. The model is the easy part now. The hard part is everything it does not know about your systems: which table actually holds revenue, why that metric excludes bot traffic, what the runbook says when the pipeline fails at 3am. That knowledge exists. It just lives in a wiki nobody updates, a Slack thread from last quarter, or one senior engineer's head. So every agent session starts by re-deriving it, or guessing.
Google's Open Knowledge Format is a small, sharp answer to where that knowledge should live.1
What OKF actually is
OKF (Open Knowledge Format) is a vendor-neutral spec, currently v0.1, for the context an agent needs. The unit is a bundle: a directory of markdown files kept in version control, ideally right next to the code it describes. Each file is a concept: a table, a dataset, a metric, a runbook, an API, a join path, or any idea worth writing down once so an agent can read it instead of re-deriving it.2
That is the whole thing. Just markdown, just files, just YAML frontmatter. No SDK, no database, no proprietary account. If you can read a file you can read OKF. If you can clone a repo you can ship it.
One rule
OKF requires exactly one thing: every concept file carries YAML frontmatter with a non-empty type. That is the entire conformance bar. Everything else, a title, a description, a resource URL, tags, a timestamp, is recommended, not required.
A concept looks like this:
markdown
---
type: Metric
title: Weekly active users
description: Distinct users with a qualifying event in a trailing 7-day window.
tags:[engagement, growth]
timestamp:2026-06-18T09:00:00Z
---
# Definition
A user is active on a day if they emit a qualifying event in
[events](/tables/events.md). WAU on date D counts distinct user_id active on
The type is descriptive, not drawn from a registry. "Metric", "BigQuery Table", "Runbook", "Reference": all valid because they are self-explanatory, not because some authority blessed them.2
The clever part: producers are precise, consumers are forgiving
Here is the design decision that makes OKF more than a folder-naming convention. The consumer contract is deliberately permissive. A tool reading a bundle must not reject it over a missing optional field, an unknown type, an extra frontmatter key, a broken cross-link, or a missing index. A consumer that does not even understand the declared version should still attempt a best-effort read rather than refuse.2
Producers aim to be precise. Consumers aim to be forgiving. That asymmetry is what lets a bundle hand-written by a person, a bundle dumped from a metadata export, and a bundle synthesized by one model all be read by some other agent later, without anyone agreeing on a schema first.
The shape, briefly
A few conventions carry the format without weighing it down:
Concepts link to each other with ordinary markdown links. The link is the edge; the surrounding prose is the label ("joined with customers on customer_id"). The relationship graph crosses the folder hierarchy freely.
index.md is a curated listing of a directory, so an agent can decide where to descend without reading everything. A producer generates it; a consumer can synthesize one when it is missing.
log.md is a dated change history, newest first.
# Citations lists the sources behind a claim. An external page can even be pulled in as its own concept under references/, carrying its URL and the date it was fetched, so provenance stays explicit.
If that sounds like an Obsidian vault or a tidy docs folder, that is the point. Bundles compose with tools that already speak markdown plus frontmatter (Obsidian, Notion, MkDocs, Hugo), so you can browse or edit them with no custom UI.
Why a spec at all
The pattern, markdown plus frontmatter as an agent-readable knowledge base, is not new. What OKF adds is being specified: it pins down the small set of rules needed for interoperability and then stops. Three principles explain why it stays this small:
Minimally opinionated. One required field. Which types exist and how a body is organized is the producer's call.
Producer and consumer independence. Whoever writes the knowledge is cleanly separated from whoever reads it, and the tooling at each end is swappable.
Format, not platform. Never tied to a cloud, a database, a model provider, or an agent framework. Its value comes from adoption, not ownership.
Google ships proof rather than just a document: a producer (an enrichment agent that walks a BigQuery dataset and can crawl seed URLs into reference concepts), a single self-contained HTML consumer that renders any bundle as a force-directed graph, and three sample bundles you can clone.3
I built a skill for it
Reading the spec is one thing. Getting an agent to actually produce a conformant bundle, and keep it conformant as it grows, is another. So I packaged the whole workflow as an agent skill.
The okf skill teaches an agent to author, validate, and maintain OKF bundles. It exposes the commands the format implies (init, add, enrich, link, index, log, validate, export, consume) and, just as usefully, runs implicitly: ask the agent to document a table, write a runbook, or export a catalog for an agent to read, and it ships the result as a conformant bundle with a type per concept instead of ad-hoc prose. It carries the v0.1 spec, copy-paste templates, and a zero-dependency validator that fails on the one hard rule and warns on the soft guidance.
It works in any agent that speaks the skills.sh format (Claude Code, Cursor, Codex, Cline, Windsurf, OpenCode). Install it on its own:
bash
npx skills@latest add saschb2b/skills --skill okf
The full breakdown of what it does is on the okf skill page.
And a place to publish bundles
A format is only useful if knowledge actually ships in it. So I opened a section of this site for exactly that: OKF bundles, where I publish bundles you can read, clone, or point your own agent at. They live in their own repository as plain directories, so nothing here locks them in.
The first one is ticket-writing: the argument from a recent post on ticket smells, turned into agent-readable concepts (the smells, the techniques that cure them, the research behind each) so an agent refining your backlog can read the reasoning directly instead of being told to "write better tickets". More will follow.
And a desktop app to read them
The skill covers writing bundles and the site covers publishing them, which left the most human part uncovered: reading. A bundle is trivial to produce and miserable to experience. The relationship graph, the thing that makes a bundle more than a docs folder, lives implicitly in the links, and a file tree hides it completely. Agents traverse that structure fine. People were stuck grepping.
So I built OKF Viewer, a small, fast, offline desktop app for exactly that. Point it at a folder and it autodetects every bundle inside, then renders each one as an interactive concept graph beside a proper reading pane: every concept a node, every markdown link an edge, with search, backlinks, an outline, and live reload as the files change underneath. It reads ODSF bundles too, rendering design tokens as swatches and components as live HTML previews.
OKF Viewer reading its own product spec: the bundle's link structure as a graph, the selected concept beside it.
Two details tie it back to the spec. It is a consumer in exactly the sense the format prescribes, tolerant to the letter: a sloppy bundle is never refused, its issues are surfaced in a validation panel instead. And it dogfoods the format completely, because the app's own product spec is an OKF bundle that ships as the built-in sample. The viewer renders the documents that specify it.
It is free and open source, built with Tauri (a Rust core, a React frontend), with installers for Windows and Linux on the download page.
The bet
Tools change fast. The agent framework you wired your knowledge into this year may not be the one you reach for next year. OKF's quiet wager is that knowledge written as plain, linked, versioned files outlives the tool you wrote it for. Markdown has already outlived a dozen editors. Your team's hard-won context deserves the same shelf life.
If you have knowledge an agent keeps re-deriving, write it down once, give each piece a type, and commit it. That is the whole format.
