Open Knowledge Format: Just Markdown Your Agent Can Read

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.¹

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.²

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.

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
any day in the window [D-6, D].

# Citations

[1] [Engagement metric definitions](https://wiki.example.com/metrics)

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.²

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.²

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.

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.

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.³

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.

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.

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.

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.

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.

• Open Knowledge Format v0.1 specification

  The normative spec: conformance, frontmatter fields, cross-linking, index.md and log.md, versioning, and the design principles behind keeping it this small.

• How the Open Knowledge Format can improve data sharing (Google Cloud)

  Google's announcement, framing OKF as portable, vendor-neutral context for AI agents and the motivation behind it.

• GoogleCloudPlatform/knowledge-catalog

  The reference producer (a BigQuery enrichment agent), the single-file HTML consumer that graphs any bundle, and three browsable sample bundles.