bundle

okf: the Open Knowledge Format toolkit for Claude Code

Teach your coding agent to author, maintain, validate and visualize portable knowledge bundles: markdown your team and your agents both read.

Open the live demo: a real bundle as an interactive graph. Click a node for the rendered concept, its derived trust tier and staleness, its sources and backlinks. Nothing leaves the page.

OKF is an open, vendor-neutral format from Google Cloud (announced June 2026) that stores the knowledge around your systems as a directory of markdown files with YAML frontmatter. No schema registry, no runtime, no SDK: cat reads it, git clone ships it. v0.2 adds trust, provenance and staleness signals to the frontmatter, so an agent can tell a verified fact from a stale guess.

This repo is the Claude Code-native toolchain for it. Claude learns to produce, maintain, consume, validate, visualize and backfill OKF bundles as part of how it already works, driven by the vendored spec and backed by a deterministic conformance checker. It ships four ways: a Claude Code plugin, agent skills for 20+ agents via skills.sh, a GitHub Action for repos with no agent, and a read-only MCP server for hosts whose agents cannot read files.

This repo documents itself in OKF: its architecture and decisions live in .okf/, rendered as a live self-graph and validated on every push.

Install

The scripts need uv (or python3 with pyyaml). One repo serves both layouts: .claude-plugin/ makes it a marketplace, skills/<name>/SKILL.md makes it skills.sh-discoverable, and scripts resolve through ${CLAUDE_SKILL_DIR} so they run from either path. The backfill skill dispatches the two subagents in agents/, which live outside skills/, so backfill works from the plugin install only.

Use it

Capture knowledge. Ask Claude to "document the auth service in OKF", or:

/okf:okf produce .okf

Backfill a repo that predates the bundle. Event-sources git history and Claude session transcripts into concepts, with a deterministic extractor and an auditable map/reduce over subagents:

/okf:backfill .

Validate before committing. The checker is deterministic, §11 of the spec, not an eyeball pass. --migrate rewrites v0.1 constructs in place:

/okf:validate .okf --strict
uv run skills/validate/scripts/okf_validate.py .okf --strict      # zero-config
uv run skills/validate/scripts/okf_validate.py .okf --max-warnings 5

Gate it in CI with the composite action. @v1 tracks the latest release while the repo is pre-1.0; pin @okf--v<version> to freeze it. The step exposes the validator's JSON as the report output.

- uses: scaccogatto/okf-skills@v1
  with:
    bundle: .okf
    strict: "true"      # or: max-warnings: "5"

Visualize the graph as a self-contained viz.html (live example). Every concept gets a deep link (viz.html#services/auth-api), and each panel shows two derived badges: the §5.3 trust tier and staleness once stale_after has passed. OKF stores neither, so both are computed at render time. Above 1000 concepts the layout falls back to linear; --layout cose overrides, --max-nodes N refuses.

/okf:visualize .okf
uv run skills/visualize/scripts/okf_visualize.py .okf -o viz.html \
  --title "My project" --link "https://github.com/me/project"

Read a bundle over MCP. Three read-only tools; nothing writes and no id resolves outside the bundle root. Inside Claude Code the server starts with the plugin on ./.okf and appears as mcp__plugin_okf_bundle__*. For Claude Code it duplicates Read and Grep, and the decision record says so; it ships for the hosts that have nothing else.

Any other host: run uv run servers/okf_mcp.py <bundle> as a stdio server (a bundle path, else $OKF_BUNDLE, else ./.okf).

Keep it up to date. Two opt-in modes. Soft: paste templates/CLAUDE-okf.md into your CLAUDE.md so Claude consults .okf/ before a task and writes back after. Enforced: add upkeep: enforced to .okf/index.md's frontmatter to arm the plugin's dormant Stop hook, which blocks finishing when tracked files changed but nothing under .okf/ did. If the bundle documents git repos checked out inside the project, add recursive: true (or a depth, recursive: 3) so the hook finds them and counts their uncommitted changes too. Depth is how many directory levels below the project root a repo's directory may sit (repos/app is 2); true means 6. OKF_HOOK=off overrides any bundle. Details: stop-hook concept.

What's inside

How a bundle looks

A concept's path is its id. The only hard rule is YAML frontmatter with a non-empty type; everything else is optional.

.okf/
├── index.md                  # progressive disclosure (root carries okf_version)
├── log.md                    # ISO-dated lifecycle events, newest first
├── services/auth-api.md      # one concept = one file
└── decisions/use-okf.md

---
type: Service
title: Auth API
description: Issues and verifies short-lived access tokens.
status: stable
stale_after: 2026-12-31T00:00:00Z
generated: { by: doc_agent/1.0, at: 2026-06-14T10:00:00Z }
verified: { by: human:dana, at: 2026-06-20T09:00:00Z }
sources:
  - id: auth-readme
    resource: https://github.com/acme/auth#readme
    last_modified: 2026-06-12T00:00:00Z
---

# Endpoints
Tokens live 15 minutes.[^auth-readme]

[^auth-readme]: Auth service README

What v0.2 adds, all optional, all in frontmatter. Normative detail in SPEC.md.

Upgrading from v0.1: the tools read both, flag the old forms as warnings, and okf_validate.py --migrate rewrites them in place.

What has been measured

Three experiments in benchmark/, each published with its protocol, runs and the defects it exposed. None of them estimates what OKF is worth in a real repository, where prose and history already carry recency.

• Trust metadata (results, pre-registered): with v0.2 lifecycle fields present the consumer never asserted a superseded fact, and read the fields unprompted. The primary contrast is invalid under the protocol's own rule, because the control refused to answer rather than answering wrong.
• Write-side gate (results, pre-registered): a process gate and an expired stale_after each reduced stale answers, and the two are not distinguishable on 20 items. Ungated writers left docs untouched 57% of the time, which is where the metadata acts.
• Backfill map tier (results, engineering A/B, one run per arm): batching small events eight per call cut the map phase by a third; the cheap tier matched sonnet on commits once two instructions were made explicit.

A third party measures a different claim, sufficiency: aws-samples/sample-okf-llm-wiki scores EX 74.0 on BIRD mini_dev (500 text-to-SQL questions) from the bundle alone.

Contributing

Issues and PRs welcome. CI validates the manifests, both bundles, the action, the docs regeneration and the test suites on every push. Releases are automatic: bump version in .claude-plugin/plugin.json, add a ## [<version>] section to CHANGELOG.md, and merging to main tags okf--v<version>. A PR touching the shipped surface (.claude-plugin/, skills/, agents/, hooks/, servers/, templates/, action.yml, .mcp.json) fails CI without both; one touching skills/*/scripts/, agents/ or hooks/ must also update .okf/. The skip-version-check label bypasses all three. This repo's bundle sets upkeep: enforced, so the Stop hook blocks finishing until the concept describing your change is updated; OKF_HOOK=off opts out. The details, and the local commands that mirror CI, are in CONTRIBUTING.md.