# OKF for Claude Code: structured, portable memory your agent (and team) can read > Source: > Published: 2026-06-28 12:44:50+00:00 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](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) 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 --- # Endpoints | 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](https://scaccogatto.github.io/okf-skills/) 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](https://docs.astral.sh/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.