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

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, as agent skills (Cursor, Codex, and 20+ agents), and as a GitHub Action for repos with no agent at all.

Two things here you will not find elsewhere in the OKF ecosystem:

• v0.2. Provenance, trust tiers, staleness, attested computations — the validator checks them, the visualizer derives the ones the spec says to derive, and --migrate moves a v0.1 bundle over in one command. Every other tool in Google's community list still targeted v0.1 when we checked on 2026-07-27.
• A number. We ran the experiment — one repo with and without its bundle, twelve fresh agents, blind grading — and published the result: 85% of ground-truth claims answered with the bundle, 77% without — n=1 per cell, so the pattern is the signal, not the total: the wins sat exactly on the why questions whose answers live nowhere in the code. Published with it, the part that went against us: in one-question sessions it saved no tokens.

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:

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).

Does it actually help? We measured it

Twelve fresh agents, one repository in two states (with .okf/ and without), six questions, blind grading. Full method, data and limits: benchmark/.

Where the bundle helped is the answers — and the pattern, not the total, is the signal. At n=1 per cell, +8 points is held to the same standard as the token delta below: a hint, not a measurement. What the run does support is where the points moved: it won the two questions asking why — the reasons behind a decision, which lived in an ADR and nowhere else — and lost the one asking where to change code, where the concept was a summary that had dropped the detail the source had. That is the shape of the value: the bundle earns its keep exactly where the code cannot answer.

What it did not do is save tokens within a session — 5% more, which at n=1 per cell is no measurable difference in either direction: on a repo this small, reading everything is already cheap. And the token cost usually cited when adopting a bundle — re-deriving, or having a human re-explain, the same knowledge in every fresh session — accrues across sessions, where a one-question-per-agent design cannot see it, in either direction. That experiment is outlined but not yet run; until it runs, we claim no token number, favourable or unfavourable.

So the bar this sets for your own bundle: write down what the code cannot say. A concept restating a constant bought nothing. A concept recording why the constant is what it is answered a question the codebase could not.

What's inside

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

Both layouts coexist in this single repo: .claude-plugin/ makes it a plugin marketplace; skills/<name>/SKILL.md makes it skills.sh-discoverable. The scripts live inside their skills and are referenced via ${CLAUDE_SKILL_DIR}, so they work identically in either install path.

Requires uv for the scripts (or python3 + pyyaml).

Use it

Capture knowledge — ask Claude to "document the auth service in OKF", or run:

/okf:okf produce .okf

Validate before committing:

/okf:validate .okf --strict
# or directly:
uv run skills/validate/scripts/okf_validate.py .okf --strict
# a bundle with warnings you have not got to yet, still gated in CI:
uv run skills/validate/scripts/okf_validate.py .okf --max-warnings 5

Gate it in CI — the composite action works in any repo, with or without Claude Code:

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

Visualize the knowledge graph — a self-contained viz.html that opens in any browser (live example):

/okf:visualize .okf
# or directly, with a title and a back-link to your repo:
uv run skills/visualize/scripts/okf_visualize.py .okf \
  -o viz.html --title "My project" --link "https://github.com/me/project"

Every concept gets a shareable deep link — open viz.html#services/auth-api and the graph loads with that concept already selected. Each panel carries two derived badges: the §5.3 trust tier (unverified / machine-confirmed / human-reviewed) and staleness, once stale_after is past. OKF stores neither — a stored tier is a stored opinion, and it goes stale — so both are computed at render time.

Turn on automatic upkeep (soft mode). To have Claude consult .okf/ before tasks and write knowledge back after changes, paste templates/CLAUDE-okf.md into your project's CLAUDE.md (or ~/.claude/CLAUDE.md for all projects).

Enforced upkeep (opt-in). The plugin also ships a Stop hook, hooks/okf-stop-check.sh, but it is dormant by default — a single file read and an exit on every session, for every repo that doesn't ask for it. Activate it for a bundle by adding upkeep: enforced to .okf/index.md's frontmatter; once set, the hook blocks Stop when there are uncommitted changes but .okf/log.md was not touched, nudging the agent to update the matching concept and log the change before finishing. Force-disable it regardless of what any bundle declares by setting OKF_HOOK=off in your environment. See the dormant hooks decision for why it replaced the earlier zero-hooks stance.

How a bundle looks

.okf/
├── index.md                  # progressive disclosure (root carries okf_version)
├── log.md                    # ISO-dated change history, newest first
├── services/
│   ├── index.md
│   └── 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 only one thing to be conformant: YAML frontmatter with a non-empty type. Everything else is optional and tolerated when missing.

---
type: Service
title: Auth API
description: Issues and verifies short-lived access tokens.
resource: https://github.com/acme/auth
tags: [auth, platform]
status: stable
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
    title: Auth service README
---

# Endpoints
| Method | Path     | Description                |
|--------|----------|----------------------------|
| `POST` | `/token` | Exchange creds for a JWT.  |

Tokens live 15 minutes.[^auth-readme]

[^auth-readme]: Auth service README

What OKF v0.2 adds

v0.2 assumes a corpus that agents keep writing, so it makes four things answerable from frontmatter alone. All optional; a concept carrying only type is still fully conformant.

Two v0.1 constructs are superseded: timestamp → generated.at, and the body # Citations list → sources (with per-claim attribution via markdown footnotes keyed to a source's id).

Upgrading from v0.1? One command:

uv run skills/validate/scripts/okf_validate.py .okf --migrate --strict

Nothing breaks in the meantime. The validator and visualizer read both — a legacy timestamp is used as generated.at — and report the two superseded constructs as warnings naming their replacement, never errors. --strict does refuse an unmigrated bundle: that is the nudge, and --migrate is the door. The rewrite is textual (your comments, key order and quoting survive) and idempotent.

Two things it will not invent: generated.by for content written before the field existed — it records process:okf-migrate, leaving the concept correctly unverified rather than faking a human review — and per-claim [^id] attribution, which v0.1 never encoded.

Repository layout

okf-skills/
├── .claude-plugin/{plugin.json, marketplace.json}
├── skills/okf/{SKILL.md, reference/SPEC.md, templates/}
├── skills/validate/{SKILL.md, scripts/okf_validate.py}
├── skills/visualize/{SKILL.md, scripts/okf_visualize.py}
├── examples/sample-bundle/      # the live-demo bundle
├── docs/                        # GitHub Pages: the live interactive demo
├── templates/CLAUDE-okf.md
├── Makefile                     # make docs / test / validate — CI runs the same
└── .github/workflows/ci.yml

Contributing

Issues and PRs welcome — new templates, producers for more sources, validator and visualizer improvements. CI validates the plugin manifest and the example bundle on every push.

Credits & license

• The Open Knowledge Format specification is by the Google Cloud Data Cloud team, released under Apache-2.0. skills/okf/reference/SPEC.md is vendored verbatim from the reference repository with attribution.
• This plugin's own code and content: MIT © Marco Boffo (@scaccogatto).