If you pair with a coding agent, you have lived this: a new session starts and the context is gone. The agent re-discovers your auth flow, re-guesses why a decision was made, re-reads the same files to rebuild a mental model you already explained yesterday. Project knowledge — the why behind your systems, the runbooks, the "don't touch this, here's the reason" — lives scattered across wikis, code comments, and people's heads. None of it travels with the code, and none of it survives a fresh context window.
CLAUDE.md
helps, but it's for standing instructions, and it gets loaded wholesale into every prompt. Auto-memory captures what an agent picked up, but it's implicit, per-agent, and not reviewed. A wiki is for humans and needs exporting. There's a gap: curated team knowledge that's structured, versioned with the code, and readable by any agent or person.
Open Knowledge Format is an open, vendor-neutral format (announced by the Google Cloud Data Cloud team in June 2026, Apache-2.0) that represents knowledge as
cat
a file you can read it; if you can git clone
a repo you can ship it.A bundle looks like this:
.okf/
├── index.md # progressive disclosure (root carries okf_version)
├── log.md # ISO-dated change history, newest first
├── services/auth-api.md # one concept = one file; path is its ID
├── datasets/orders-db.md
├── decisions/use-okf.md
├── runbooks/payment-failures.md
└── metrics/checkout-conversion.md
Each concept needs exactly one thing to be conformant: YAML frontmatter with a non-empty type
. Everything else is optional.
---
type: Service
title: "Auth API"
description: "Issues and verifies short-lived access tokens."
resource: https://github.com/acme/auth
tags: [auth, platform]
timestamp: 2026-06-14T10:00:00Z
---
| Method | Path | Description |
|--------|----------|---------------------------|
| `POST` | `/token` | Exchange creds for a JWT. |
Concepts link to each other with plain markdown links, which makes the bundle a graph of typed, cross-referenced knowledge — diffable, reviewable in PRs, and portable across tools because it's just text.
OKF is the format. ** okf-skills** is the Claude Code-native toolchain that teaches your agent to actually use it, driven by the verbatim v0.1 spec. It ships as a Claude Code plugin and as agent skills (installable on Cursor, Codex, and 20+ agents via skills.sh). Three pieces:
| Skill | What it does |
|---|---|
/okf:okf |
|
| Produce, maintain, and consume bundles, applying the spec and templates. Auto-triggers when a repo already has an OKF bundle. | |
/okf:validate |
|
| Deterministic §9 conformance check — a real Python checker, not an eyeball pass. | |
/okf:visualize |
|
| Render a bundle to a self-contained interactive HTML graph. |
The validator and visualizer are standalone scripts too (uv run
, PyYAML via PEP 723), so they work the same whether installed as a plugin or as skills. The visualizer output is a single viz.html
— concepts as nodes, links as edges, a wiki-style detail panel with rendered markdown and "Links to / Cited by" backlinks. No backend; nothing leaves the page. There's a live demo of a real bundle, and the repo
A few things worth being straight about:
CLAUDE.md
for As a Claude Code plugin:
/plugin marketplace add scaccogatto/okf-skills
/plugin install okf@scaccogatto
As agent skills (Claude Code, Cursor, Codex, 20+ agents):
npx skills add scaccogatto/okf-skills
Then capture, validate, and visualize:
/okf:okf produce .okf # or just ask: "document the auth service in OKF"
/okf:validate .okf --strict
/okf:visualize .okf # opens a shareable viz.html
Every concept gets a deep link — viz.html#services/auth-api
loads the graph with that concept already selected.
To turn on automatic upkeep (consult .okf/
before tasks, write knowledge back after changes), paste templates/CLAUDE-okf.md
into your project's CLAUDE.md
. It's soft mode and entirely opt-in. The scripts need uv (or
python3
pyyaml
).The pitch is small and concrete: give your project's knowledge one durable, diffable, portable home, versioned next to the code it describes — instead of re-explaining it to a fresh agent every morning. It's plain markdown, so worst case you've written some good docs your team can read. Best case your agent stops forgetting.
Repo, demo, and spec: ** github.com/scaccogatto/okf-skills**. Issues and PRs welcome.