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

Channel	Command	Notes
Claude Code plugin	/plugin marketplace add scaccogatto/okf-skills then /plugin install okf@scaccogatto	Skills, subagents, Stop hook and MCP server. The full toolchain.
Agent skills (skills.sh)	npx skills add scaccogatto/okf-skills	Claude Code, Cursor, Codex and 20+ agents. Installs the okf, validate, visualize and backfill skills; backfill needs the plugin's subagents, see below.
GitHub Action	uses: scaccogatto/okf-skills@v1	Validates a bundle in CI, no agent needed.
MCP server	uv run servers/okf_mcp.py .okf	Any MCP host. Bundled with the plugin, nothing to configure there.
Local development	claude --plugin-dir /path/to/okf-skills	No marketplace.

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.

Tool	Returns
search_concepts(query, limit)	Concept cards (id, type, title, description, status, stale_after); metadata hits rank above body hits.
read_concept(concept_id)	One concept verbatim, frontmatter included. The id is the bundle path without .md.
get_neighbors(concept_id)	outgoing and incoming cards from markdown links and bundle-internal sources.

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. OKF_HOOK=off overrides any bundle. Details: stop-hook concept.

What's inside

| Component | What