Google's Open Knowledge Format, and the Plugin I Built for It

On June 12, Google Cloud published a specification called the Open Knowledge Format. There was no keynote and no launch video — a blog post, a one-page spec on GitHub, and a handful of reference tools. For something that modest, it caught my eye. I already keep my documents in Markdown so the AI tools I work in can read them easily, and OKF looked like a small, sensible thing to layer on top of what I’m already doing — worth looking into.

I’ll cover what OKF is, then the part I can speak to first-hand: I read the spec, decided it was small enough to build against, and wrote a tool for it in a day. It’s the first skill I’ve made public.

What the Open Knowledge Format is

Strip away the framing and OKF is almost aggressively plain: a folder of Markdown files, each describing one thing, with a small structured header at the top. A “bundle” is just a directory, usually a git repo. Each Markdown file is a “concept” — a table, a metric, an API, a runbook, whatever unit of knowledge you’re writing down — and its identity is its file path. At the top of each file is a YAML frontmatter block: a small set of labeled key: value fields, set off by a pair of --- lines, that works like the header on a memo or a form — structured information a program can read at a glance. The only field the spec actually requires is type, a short string saying what kind of thing the file describes. Title, description, tags, a timestamp, a link to the underlying resource: all recommended, none mandatory.

Concretely, here’s what this very article would look like as an OKF concept — the header an agent reads first, then the Markdown you’re reading as the body:

---
type: Article
title: "Google's Open Knowledge Format, and the Plugin I Built for It"
description: What OKF is, and the Claude Code plugin I built to author, convert, and validate it.
resource: https://ap7i.com/posts/open-knowledge-format-okf-claude-code-plugin/
tags: [okf, claude-code, ai]
timestamp: 2026-06-21T16:33:40Z
---

Only type is required; the rest earn their place by helping a reader — human or agent — know what the file holds before reading the body.

Files link to each other with ordinary Markdown links, and the meaning of a link lives in the prose around it rather than in some typed-edge schema. Two filenames are reserved: index.md, a directory listing so an agent can survey a folder before reading everything in it, and log.md, a dated changelog that travels with the knowledge. A bundle “conforms” if every real file has parseable frontmatter with a non-empty type. Consumers are told to be forgiving — tolerate unknown types, unknown fields, broken links, missing pieces.

The spec’s own summary is the line that stuck with me: if you can cat a file, you can read OKF; if you can git clone a repo, you can ship it. No schema registry, no central authority, no required tooling, no SDK. And Google didn’t only publish the document — it shipped reference tools alongside it: an agent that drafts OKF docs from a BigQuery dataset, a single self-contained HTML viewer that renders a bundle as a browsable graph, a few sample bundles, and an update to its own data catalog so it reads the format natively.

Why a format instead of a product

Google’s argument for why this should exist is worth quoting, because it isn’t the usual platform pitch. The premise is what they call the context-assembly problem: as models improve, the thing that limits them is context, and an organization’s useful context — what a metric actually means, how two systems join, the runbook for an incident, why an API was deprecated — is scattered across catalogs with proprietary APIs, wikis, shared drives, code comments, and people’s heads. Every team building an agent reassembles it from scratch. Every catalog vendor reinvents the same models behind its own SDK.

Their conclusion: “The answer to this problem isn’t another knowledge service. You need a format” — one anyone can produce without an SDK, anyone can consume without an integration, that survives moving between systems, lives in version control next to the code it describes, and reads the same to a human and to an agent. They were also direct about why they’re giving it away: “We’re publishing it as an open standard because the value of a knowledge format comes from how many parties speak it, not from who owns it.” The format, they wrote, is the contribution.

The lineage is the “LLM-wiki” idea Andrej Karpathy floated earlier this year — that the tedious upkeep which makes humans abandon personal wikis, like updating cross-references or touching fifteen files to make one change, is exactly the bookkeeping a language model is happy to do. OKF is that idea written down as a spec. If you’ve ever looked at the older W3C knowledge formats, OWL and RDF, this is the opposite instinct: instead of a rich, formal model that needs ontology expertise and specialized tooling, OKF requires one field and fits on a page. It’s a bet that low-friction adoption of something simple beats high-friction adoption of something powerful. It also isn’t trying to replace retrieval or the Model Context Protocol; it’s the curated knowledge layer those things can point at.

Where I think it lands

In my world — Healthcare IT — we struggle with a familiar trap: institutional knowledge that lives only in people’s heads. The meaning of a field, the reason a process exists, the workaround everyone “just knows.” For that reason, I’ve spent this year documenting everything in Markdown, where the AI tools I work in can read it without a translation layer. OKF takes my existing repositories a step further, giving those files a light, shared shape. And because a bundle is just files in a folder, adopting it doesn’t lock you into anything.

I won’t oversell it. OKF is v0.1, which Google says plainly — a starting point, not a finished standard. Its whole value depends on adoption, and the open question the early coverage keeps circling is whether anyone outside Google ends up speaking it: other catalog vendors, other agent frameworks. A one-page spec is hard to find excuses not to support, which helps. There’s also a real onboarding cost for the non-technical teams who hold much of an organization’s institutional knowledge but don’t live in Markdown and git — they’ll likely keep their wikis, with something like OKF as a back end. But the design is honest about all of that, and trying it asks very little of you. That’s rare enough to take seriously.

The plugin I built for it

Reading the spec, the thing that jumped out was that I could actually implement it. A one-page format with a single required field is something a person can build a real tool around in an afternoon. So I did.

It’s called okf-author, and it does three things. It can author new OKF, starting a bundle from scratch with sensible frontmatter defaults. It can convert existing Markdown into OKF — point it at a folder of notes or docs and it adds the frontmatter, infers a type for each file, and, if you want, generates the index.md and log.md files. And it can validate a bundle against the v0.1 conformance rules and tell you, with a clean exit code, whether it passes.

I was careful with the convert path, because it touches files you already have. It won’t quietly rewrite anything: it edits in place only when the folder is a clean git checkout, so every change is one git revert away, and otherwise it writes a separate copy and says so. It works in stages — add the frontmatter first, which is all conformance actually needs, and build out the index and log files only if you ask. The validator is plain Python with no dependencies, and it carries a byte-for-byte copy of Google’s spec, attributed and pinned to a commit hash, so it checks against the real document rather than my memory of it.

Two things make this one different from the email client I built the weekend before. First, it’s the first skill I’ve made public. Second, it’s packaged three ways from one codebase: as a skill for Claude Code, a skill for Codex, and — new for me — a proper Claude Code plugin, distributed through its own marketplace.

Installing it

If you use Claude Code, the plugin is the easy path. Run these two commands, one at a time:

/plugin marketplace add parkscloud/okf-author
/plugin install okf-author@okf-author

Then run /reload-plugins. You can also open the /plugin interface directly, find okf-author in the list, and install it there by highlighting it and pressing i — and that same screen is where you switch on auto-update, so the plugin refreshes itself at the start of each session.

If you’re on Codex, or you’d rather skip the plugin, clone the repo and run the installer — standard-library Python, no pip:

python3 install.py --all

The source is at github.com/parkscloud/okf-author.

What it taught me, and what I did with it

Packaging it as a plugin is where I learned something new. I’d never set up auto-updates for anything like this, and building it as a plugin with its own marketplace is what made that possible — Claude walked me through wiring it up so that when I publish a new version, the people who installed it get it automatically at their next session. I describe what I want; it knows the machinery I don’t.

Then I did the obvious thing and used the plugin on my own material. I’ve converted several of my documentation repositories to OKF, adding just enough structure that an agent can read them without me re-explaining the layout every time. That’s the test that matters to me: not whether a format is elegant in the abstract, but whether I’ll reach for it on a Tuesday. So far, I am.

That’s the throughline across both of these projects. The format is Google’s; the plugin is mine; the part that still surprises me is how little distance there is now between “I wish this existed” and “it exists.” OKF is a bet that the simplest possible shape — files in a folder — is enough. I think it’s a good bet, and it cost me a day to find out.