Open Knowledge Format

---

OKF is an open, vendor-neutral format (announced by Google Cloud, June 2026) that represents knowledge — the context and curated insight around your systems — as a directory of markdown files with YAML frontmatter. No schema registry. No runtime. No SDK. If you can cat a file you can read it; if you can git clone a repo you can ship it.

This is the Claude Code-native OKF toolchain. It teaches Claude to produce, maintain, consume, validate, and visualize OKF bundles as a normal part of how it already works — driven by the verbatim spec, backed by a deterministic conformance checker, with a self-contained graph renderer. Ships as a Claude Code plugin and as agent skills (Cursor, Codex, and 20+ agents).

Why knowledge-as-code (and where OKF fits)

Project knowledge lives scattered across wikis, code comments, and people's heads; agents re-discover it from scratch every session. OKF gives it one durable, diffable, portable home — versioned next to the code it describes. It is complementary to the rest of your context stack, not a replacement:

	OKF bundle (this)	CLAUDE.md	Claude auto-memory	Wiki / Notion
Purpose	curated knowledge	standing instructions	implicit notes	human docs
Portable across agents/tools	✅ plain md + yaml	⚠️ Claude-specific	❌ per-agent store	⚠️ export needed
Versioned with code in git	✅	✅	❌	❌
Typed & queryable	✅ frontmatter	❌ prose	❌	⚠️
Graph of linked concepts	✅	❌	❌	⚠️
Curated & reviewed in PRs	✅	✅	❌ implicit	⚠️
Scales past the context window	✅ progressive disclosure	❌ loaded wholesale	⚠️	n/a

Use CLAUDE.md for how to behave, auto-memory for what the agent picked up, and an OKF bundle for what the team knows — shared, structured, and shippable.

🪞 This repo documents itself in OKF. The architecture, skills, and decisions behind okf-skills live in .okf/ — explore them as a live self-graph. CI validates that bundle on every push (dogfooding the conformance checker).

What's inside

Component	What it does
/okf:okf skill	Produce / maintain / consume bundles, applying the spec and templates. Auto-triggers when a repo has an OKF bundle.
/okf:validate skill	Deterministic §9 conformance check (not an eyeball pass).
/okf:visualize skill	Render a bundle to a self-contained interactive HTML graph (viz.html).
skills/validate/scripts/okf_validate.py	Standalone, zero-config validator (uv run, PyYAML via PEP 723).
skills/visualize/scripts/okf_visualize.py	Standalone bundle→viz.html renderer (Cytoscape + marked via CDN).
skills/okf/reference/SPEC.md	The OKF v0.1 spec, vendored verbatim — the source of truth.
templates/CLAUDE-okf.md	Snippet that turns on automatic consume/maintain in your project.
examples/sample-bundle/	The conformant bundle behind the live demo — code, data, decisions, runbooks, metrics.

Install

As a Claude Code plugin (one-plugin marketplace):

/plugin marketplace add scaccogatto/okf-skills
/plugin install okf@scaccogatto

As agent skills via skills.sh (Claude Code, Cursor, Codex, and 20+ agents):

npx skills add scaccogatto/okf-skills            # installs the okf, validate & visualize skills

Local development (no marketplace):

claude --plugin-dir /path/to/okf-skills