When Google Cloud announced the Open Knowledge Format (OKF) in June, I was mid-project on the problem it addresses. My personal knowledge base already consisted of Markdown files with YAML frontmatter, a metadata block at the start of each file. I had built it up over months across close to twenty repositories. A bundle, in OKF's vocabulary, is a directory of those files. I wanted to adopt the format while keeping the knowledge, metadata and navigation I had already put into them.
Sam McVeety and Amir Hormati, tech leads in data analytics and BigQuery respectively, introduced OKF on June 12. I read the specification that week. It was satisfying to see a working pattern I knew described precisely enough for other people to implement: readable by an agent that can cat a file, shareable by someone who can git clone a repository. The v0.1 specification's section 10 explicitly connects the format to the LLM-wiki pattern.
Give the checker a versioned contract
So I converted my repositories. I also wanted a standalone check I could point at a bundle after conversion.
In the Google reference repository, the snapshot inspected for July 21 shows that the declared Python commands were enrich and visualize. Its internal OKFDocument.validate() method and document tests already performed validation. The declared command interface did not expose a standalone bundle-check command.
An issue opened June 15 proposed valid and invalid example bundles plus a test runner. It also distinguished the specification's minimal requirements from the reference producer's stronger expectations. The reference producer required title, description and timestamp as well as type, while spec-minimal concepts did not need those optional fields.
Kiso, an open-source publishing engine for OKF bundles, added check in its July 5 v0.1.3 release. Its validation runner routes the command through encoding and frontmatter checks. The frontmatter rule also checks a timestamp when present and rejects frontmatter on non-concept files. Compare that source-defined behavior with the version and publishing requirements you intend to enforce.
For my own pipeline, I wanted to separate OKF conformance from editorial preferences. Conformance means satisfying the format's requirements for the declared version. A publishing workflow can also require useful descriptions, a house vocabulary or working navigation. Those additional requirements need their own name and tests.
Three categories, including the reserved-file rules
OKF v0.1 section 9 defines three conformance categories:
| Category | What to inspect |
|---|---|
| Concept frontmatter | Every non-reserved Markdown file has a parseable YAML frontmatter block. |
| Required type | Each concept's metadata includes a nonempty type. An unfamiliar type name is permitted. |
| Reserved files | When index.md or log.md is present, it follows the structure defined for that filename. |
Section 6 describes an index with headings that group linked entries. Section 7 requires ISO date headings such as 2026-07-21 in the change log. An index normally has no frontmatter; section 11 permits okf_version: "0.1" in the bundle-root index.
The specification also tells consumers what to tolerate: missing optional fields, unknown types, additional metadata keys, broken cross-links and absent index files. That permissiveness is deliberate, and it's the right call for a format meant to formalize something people were already doing informally. A concept containing only a valid type can meet the format's metadata requirement. If a publishing check requires a description too, report that as the publishing check's requirement. Otherwise a reader cannot tell whether to repair an invalid bundle or improve an already valid one.
Update — October 1, 2026: The workbook below examines a preserved v0.1 implementation and adds a conversion exercise.
Automation helps once a corpus is large enough that repeated manual inspection becomes unreliable. The downloadable v0.1 workbook compares the specification with that checker, including invalid inputs its success message can miss:
| Example input | v0.1 expectation | Observed checker result |
|---|---|---|
A concept with an unfamiliar type and no optional fields | Accept | No errors; three warnings about recommended fields |
A concept missing type | Reject | One error |
| Unparseable frontmatter | Reject | One error |
A log headed ## 07/21/2026 | Reject | No errors; one warning |
| An index containing an ungrouped paragraph, with no headings or entries | Reject | No errors or warnings |
| A concept with malformed UTF-8 bytes | Invalid input | An uncaught decoding exception |
The log and index cases expose a gap between the specification and the checker's success message. A successful exit from this source does not establish complete v0.1 conformance. The workbook keeps that source unchanged so the discrepancy remains reproducible. It also includes positive cases for valid reserved files, the root version exception, unknown metadata keys and broken links. Testing only malformed concepts would miss the reserved-file gaps.
Preserve the knowledge while adding structure
For conversion, I wanted existing metadata and body text to survive. That requires checking the proposed output, including files a converter regenerates or renames.
Some of my runbooks were thin pointers to an installed skill: a title and an npx command, with no explanatory paragraph. Extracting a description from that body produces a description of a shell command. I curated descriptions by hand where the extractor did not have enough information to produce a reliable summary.
The source inspected for this revision can reserialize existing frontmatter when adding fields, regenerate index content, and remove a README on its apply path. Preserving existing metadata values would not, by itself, preserve YAML comments, formatting or unique README guidance. Before applying a conversion, I would review all of those changes against the original files.
The directory that had no concepts of its own
The bug I found while converting a larger repository involved a directory that held only subdirectories. It had no Markdown concept directly inside it.
My converter initially decided which folders needed a navigation index.md by looking at each concept file's direct parent. The container directory never triggered that check. Its parent's generated index linked to it anyway, leaving a link to a missing target.
Here is a constructed version of that shape:
bundle/
├── README.md
├── notes/
│ └── topic.md
└── teams/
└── payments/
└── runbooks/
├── release.md
└── skill-pointer.md
Looking only at the files' immediate parents finds the bundle root, notes and teams/payments/runbooks. It misses teams and teams/payments. The complete set for generated navigation is:
.
notes
teams
teams/payments
teams/payments/runbooks
The traversal must walk every ancestor up to the bundle root. That gives the root a link to teams/index.md, that index a link to payments/index.md, and the next one a link to runbooks/index.md. The fix in my converter followed that rule. I found the bug by converting a repository with a different structure from my first test repositories; repeating the same earlier conversions would not have exercised it.
Missing index files are permitted by the format. Generating a navigation link and omitting its target still defeats the navigation I am trying to provide. A format check and a conversion acceptance check answer different questions here.
Review a complete proposal before applying anything
The workbook's second exercise builds the fictional tree above in memory as a conversion proposal. It includes every original file alongside its proposed contents, so a reviewer can inspect the whole result.
The release runbook already has a quoted title, a description, a custom owner field and a YAML comment. The proposal preserves those bytes and its complete body, inserting only the separately supplied tags field. The skill pointer has no frontmatter; its proposed type and title come from the exercise's explicit field choices. Its description remains marked for human curation. No timestamp or approval is invented.
The README contains unique guidance about release approval. In this exercise it is already a typed concept, so the proposal keeps it intact and creates a separate index.md. README.md is not an OKF reserved filename. A README without frontmatter would therefore need an explicit treatment as a concept or a reviewed redistribution of its contents. Renaming it and retaining only its opening paragraph could lose the instructions further down.
After extracting the download, the README provides four commands: inspect rule observations, print the conversion proposal, run the literal contract tests, and run deliberately faulty copies. The nine tests include all 16 rule cases and the complete expected proposal. The six faulty copies omit ancestor directories, overwrite existing metadata, drop a body, lose the README, remove the editorial hold or break navigation. Each must fail the unchanged tests for the expected reason.
This is a preview exercise for the included files. It neither applies changes nor merges existing index or log files, and its tests do not certify a general migration tool. For an actual corpus, the acceptance conditions need to include its own filenames, metadata conventions, valuable README sections and directory shapes.
Keep the format version and the client behavior visible
I packaged my validator, converter and conversion procedure as the public synthesis-okf skill in Synthesis Skills. They reflect the practice I have been building around AI coding agents: conventions, verification and tooling that remain useful across sessions.
Update — October 1, 2026: The client guidance below reflects current documentation. OKF v0.2 was released after this July v0.1 account.
The shared Agent Skills format packages instructions and supporting files. Current Codex documentation describes discovery through .agents/skills, while Claude Code documentation describes .claude/skills locations and additional invocation features. A shared SKILL.md does not establish identical installation, available tools or execution across clients.
The newer specification snapshot is v0.2. Its change notes move provenance into frontmatter sources and supersede timestamp with generated.at, among other changes. Keep that migration decision separate from checking the v0.1 bundle in this article.
Sam and Amir, I'd be interested to hear whether you had the ancestor-only directory case in mind. For another converter, I would include that shape in its test bundle.
If you already keep your knowledge in Markdown, the gap to an OKF bundle is smaller than it looks. The format gives familiar files a shared structure for exchange while leaving you room to organize the knowledge for your work. Choose a branch of the directory tree that contains hand-written metadata, a thin runbook and a directory with no direct concepts. Compare the proposed files and navigation with that original material before converting the rest.