okf-skills makes a knowledge bundle something a validator can gate

Four install channels, and backfill works through only one of them

One repository ships four ways, and the table of channels is the fastest way to understand what it is.

The Claude Code plugin is installed with a marketplace add followed by a plugin install, and it is described as the full toolchain: skills, subagents, Stop hook and MCP server. Agent skills go through skills.sh with a single npx command and reach Claude Code, Cursor, Codex and twenty or more other agents.

npx skills add scaccogatto/okf-skills

The GitHub Action validates a bundle in CI with no agent involved, and the read-only MCP server runs anywhere.

uv run servers/okf_mcp.py .okf

There is also a local development route with claude pointed at the plugin directory, bypassing the marketplace entirely.

The limitation is stated plainly and it will bite you if you pick the wrong channel. The backfill skill dispatches the two subagents in agents/, and those live outside skills/, so backfill works from the plugin install only. Installing the skills and skipping the plugin gives you the other three capabilities and a backfill command that cannot do its job.

Two structural details explain how one repo serves both layouts. The .claude-plugin/ directory is what makes it a marketplace, skills/<name>/SKILL.md is what makes it skills.sh-discoverable, and the scripts resolve through ${CLAUDE_SKILL_DIR} so they run from either path.

The scripts need uv, or python3 with pyyaml. That is the entire runtime requirement.

OKF stores markdown with frontmatter, and v0.2 made staleness readable

The format underneath is worth understanding, because the toolkit only makes sense against it.

OKF, the Open Knowledge Format, is an open, vendor-neutral format from Google Cloud, announced in June 2026, that stores the knowledge around your systems as a directory of markdown files with YAML frontmatter. The description is blunt about what it does not have: no schema registry, no runtime, no SDK. cat reads it and git clone ships it.

That constraint is the feature. A bundle is a folder of files, so it diffs, reviews and merges like code, and an agent reads it with the file tools it already has.

Version 0.2 of the format adds trust, provenance and staleness signals to the frontmatter, with the stated purpose of letting an agent tell a verified fact from a stale guess. That is the addition that makes the format usable by an agent rather than only by a person.

One subtlety is easy to miss and shows up in the visualizer. The trust tier and staleness are derived badges computed at render time, not stored fields. OKF stores neither. A panel shows the section 5.3 trust tier, and shows staleness once a stale_after date has passed. Both are computed when the graph is rendered.

So the bundle records the inputs to a judgement rather than the judgement itself, which means a stale fact does not silently acquire a verified badge in the file, and a recomputation after an edit cannot contradict what was committed.

The validator is section 11 of the spec, and --migrate rewrites v0.1 files in place

The claim about the checker is specific: it is deterministic, section 11 of the spec, not an eyeball pass. That distinction is the whole point of shipping a validator.

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

Three routes to the same check: the slash command, the standalone script with no agent involved, and the relaxed form that tolerates up to five warnings. The standalone script also carries --json and --migrate.

--migrate is the one to understand before you run it. It rewrites v0.1 constructs in place, so it edits files in your repository. Running it on a bundle you have not committed means losing the diff between what the migration changed and what you wrote.

In CI, the action is declared like this.

- uses: scaccogatto/okf-skills@v1
  with:
    bundle: .okf
    strict: "true"

Two details in that snippet matter for a team. The @v1 ref tracks the latest release while the repository is pre-1.0, and the documentation tells you to pin to @okf--v<version> to freeze it, which means your validator's behaviour can change under you on an unmerged commit to a shared tag. And the step exposes the validator's JSON as a report output, so a job summary can show the findings rather than only failing.

The Makefile runs the same validator in strict mode against both examples/sample-bundle and the repository's own bundle, which is the cheapest possible dogfooding check.

The Stop hook blocks finishing when code changed and .okf/ did not

Keeping a bundle current is the failure mode every knowledge format has, and this one offers two opt-in answers.

The soft mode is a file you paste. Put templates/CLAUDE-okf.md into your CLAUDE.md and Claude consults the bundle before a task and writes back after. Nothing is enforced; it is an instruction in a file the agent already reads.

The enforced mode is a hook. Add upkeep: enforced to the frontmatter of .okf/index.md and the plugin's dormant Stop hook arms itself. From then on the hook blocks finishing a turn when tracked files changed but nothing under .okf/ did.

Read that condition carefully, because it is narrower than a general documentation requirement. It fires when code changed and the bundle did not. It is not asking the agent to document every edit; it is asking that a change to tracked files come with some corresponding write to the knowledge bundle. A refactor that genuinely needs no doc change still has to touch something under .okf/, which is friction by design and also the mechanism by which the check stays honest rather than becoming a rule agents learn to bypass by writing a token file.

There is an override. OKF_HOOK=off disables the hook for any bundle, which matters for scripted or batch runs where a blocking hook would deadlock the session.

The design detail that makes it tolerable is that the hook is dormant until you arm it. Nothing changes in a repository that has a bundle but no upkeep setting.

The MCP server is read-only and admits it duplicates Read and Grep

The MCP server exists for hosts whose agents cannot read files, and the documentation does not oversell it.

Inside Claude Code the server starts with the plugin on ./.okf and its tools appear under the mcp__plugin_okf_bundle__ prefix. For Claude Code it duplicates the built-in Read and Grep, and a decision record inside the bundle itself says so. It ships for the hosts that have nothing else.

Having that admission in a decision record rather than only in prose is the notable part, and it fits the repository's habit of documenting itself in the format it implements.

There are three tools, all read-only. Nothing writes, and no id resolves outside the bundle root.

search_concepts takes a query and a limit and returns concept cards carrying id, type, title, description, status and stale_after, with metadata hits ranking above body hits. read_concept takes a concept id and returns one concept verbatim including frontmatter, and the id is the bundle path without the .md extension. get_neighbors takes a concept id and returns outgoing and incoming cards derived from markdown links and bundle-internal sources.

That last one is what makes the format a graph rather than a folder. Backlinks are computed from links that already exist in the files, so there is no separate index to keep in sync and no way for the graph to disagree with the prose.

For any other host the server runs as a stdio server, taking a bundle path as an argument, falling back to $OKF_BUNDLE and then to ./.okf.

Backfill maps events cheaply and lets one agent be the only writer

Backfilling a repository that predates the bundle is the capability that would otherwise be weeks of reading.

It event-sources git history and Claude session transcripts into concepts, with a deterministic extractor and an auditable map and reduce over subagents. The slash command is short.

/okf:backfill .

The shape of the two subagents explains why the map and reduce split exists. agents/ contains event-analyzer, which is described as the map stage on a cheap tier, and bundle-weaver, which is the reduce stage and the only writer.

Only one component writes. The map stage reads history and emits candidate events, capped diffs, deterministically; the reduce stage is the single place where concepts are created or changed. That is the standard way to keep a generated artefact reviewable, because it gives you one place to look when the output is wrong and one place to fix.

Two consequences follow. The extraction is deterministic, so running backfill twice on the same history should not produce a different bundle, which is what makes the output auditable rather than a model improvisation. And the cheap tier matters at volume: a repository with years of history is a lot of events to read, and putting that on the cheaper model while keeping the expensive one for the single writing pass is the difference between a backfill that costs a few cents and one that does not.

The extract script is named in the component table as skills/backfill/scripts/okf_backfill_events.py, and the validator, the visualizer and the initializer are siblings under skills/validate, skills/visualize and skills/okf, with okf_init.py scaffolding a starter bundle.

The Pages demos drifted because the generator command lived nowhere

The Makefile contains the best comment in the repository, and it explains a security fix that went unapplied for weeks.

The GitHub Pages demos are generator output committed to the repo. The exact invocation used to live nowhere, so they drifted: both pages shipped for weeks without the DOMPurify sanitize fix that had already landed in the generator. Pinning the command in the Makefile, and diffing it in CI, is what stops that recurring.

Parse that again, because it is a concrete failure rather than a hypothetical. The visualiser renders concept text into HTML, the generator gained a sanitisation fix, the committed pages did not get it, and nobody noticed for weeks. Committed generated output plus an unpinned invocation equals a window where the published artefact is behind the tool that produced it, and the artefact is the one serving traffic.

The fix is small and worth copying: pin the command in one place, regenerate both pages from it, and let CI diff the result. The docs target runs the visualiser twice, once over examples/sample-bundle into docs/index.html and once over the repository's own .okf into docs/self.html, each with a title, a link, an Open Graph image and a breadthfirst layout.

That self-graph is worth opening regardless. The repository documents its own architecture and decisions in .okf/, validates it on every push, and renders it as an interactive graph, so you can read what the project thinks it is doing from the format the project is about.

The test target runs nine entry points, covering the validator, the MCP server including an end-to-end test, the backfill extractor, the Stop hook, and four additional suites under benchmark/trust and benchmark/gate are covered too. A NOTICE file sits alongside the MIT licence, and the releases came in a cluster: v0.9.5 and v0.9.6 on 2026-09-21, then v0.10.0 on 2026-09-28, the same day as the last push.

Editorial conclusion

Adopt okf-skills if your team wants knowledge about its systems to be reviewable files that a program can check, because a deterministic validator in CI and a Stop hook that notices an undocumented change are worth more than another prompt telling the agent to document things. Install the plugin rather than the skills alone, because backfill needs the subagents that live outside the skills directory and only the plugin ships them. Verify three things first: that your repository's knowledge belongs in a bundle at all, since this is a tool for documenting systems rather than a general notes format, whether your CI should pin the action to a release tag while the project is pre-1.0, and that the visualizer output you commit is generated, since the project's own Pages pages once shipped without a sanitisation fix that had already landed in the generator. The licence is MIT and the last push was on 2026-09-28.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. scaccogatto/okf-skills on GitHub