How to write an OKF bundle: one directory, three rules, one minimal example

The first time I read the OKF spec, I was surprised how small it is. It is not a database, an SDK, or a query language — it is a directory of markdown files plus a few conventions. This piece walks you straight through writing a minimal, runnable bundle.

Three rules are the whole format

The format comes down to three rules: one index, one truth — every bundle has an index.md listing its contents; typed frontmatter — every file declares a type, so agents route without guessing; and git-native — you can diff, review, and roll back like code, with no proprietary format.

The smallest bundle looks like this

my-knowledge-bundle/
├── index.md            # manifest: lists all contents
├── weekly-active-users.md
└── user-events.md

index.md: the entry point for the whole bundle

index.md uses frontmatter to define the bundle identity: a title, a version, and entries (the files it contains). An agent enters here and reads further once it sees the concept it needs.

---
title: My Knowledge Bundle
version: 0.1.0
entries:
  - weekly-active-users.md
  - user-events.md
---

# My Knowledge Bundle

A knowledge base for agents. Read the relevant node first;
update the matching node after any change.

Each concept file: declare a type, write links

Every non-reserved markdown file needs parseable frontmatter and a non-empty type. The type can be concept, howto, reference, decision, metric, and so on. Fields such as title and description are recommendations, not requirements. Concepts connect through ordinary markdown links — those links are the knowledge graph.

---
type: metric
title: Weekly Active Users
description: Unique users who open the product at least once a week
---

# Definition

Unique users who produced at least one valid event in the last seven days.

# Related

- [User events table](user-events.md)

How an agent uses it

The key is type and links. An agent enters through index.md, uses type to tell whether a file is a concept, a how-to, or a decision — no keyword guessing — and traverses markdown links to related nodes when it needs more context. The whole thing is traversal, not search, which is the biggest difference from vector retrieval.

A few trade-offs I hit myself

I built a real bundle for this site’s repo, in /knowledge: one node each for architecture, decisions, and traps, so Claude and Codex do not re-crawl the whole repo every time. A few trade-offs became clear while I was doing it.

Keep nodes small, ideally one concept per file. Rather than one big file, split the knowledge into small linked nodes so an agent reads only the relevant one. Do not store stale trivia (a commit hash, a temporary TODO); that is what git is for. The bundle should hold the stabler stuff: architecture, decisions, conventions, and traps. Most important, a bundle alone does nothing. Put "read before you work, update after" into the entry files the agent loads, or the bundle will not stay alive.

You need no new database, query language, or SDK. One directory and three rules are enough for a knowledge base that a human can read, an agent can traverse, and Git can version.