okf-skills: authoring and validating Open Knowledge Format bundles in Claude Code

The problem okf-skills addresses: knowledge that only humans read

Architecture notes, runbooks and decision records usually live as prose in a wiki or a docs folder. A person can read them; a coding agent cannot reliably query them, and nothing checks whether they are still true. OKF, announced by Google Cloud in June 2026, represents that kind of knowledge as a directory of markdown files with YAML frontmatter. The README's framing is deliberately plain: no schema registry, no runtime, no SDK, and if you can `cat` a file you can read it.

okf-skills is the Claude Code-native toolchain around that format. It targets two audiences. The first is a team running Claude Code that wants the agent to produce OKF-shaped bundles as part of normal work rather than ad hoc markdown. The second is a repository with no agent at all: the composite GitHub Action validates a bundle on push, so a project can adopt the format without adopting the plugin. The README is explicit that this repository implements OKF v0.2 throughout, which means trust signals, provenance and staleness, not the earlier shape of the format.

How the okf-skills toolchain is put together

The repository ships the same logic through four delivery paths, and the layout is the reason they can coexist. `.claude-plugin/` makes the repo a Claude Code plugin marketplace; `skills/<name>/SKILL.md` makes it discoverable through skills.sh. Scripts live inside their skills and are referenced with `${CLAUDE_SKILL_DIR}`, so a script resolves whether it was installed as a plugin or as a skill.

The verification path is a single Python program, `skills/validate/scripts/okf_validate.py`, described as a deterministic conformance checker. It emits a JSON report under `--json`, and the GitHub Action surfaces that report as a step output named `report` so a later step can post or parse it. Visualization is a second script, `skills/visualize/scripts/okf_visualize.py`, which writes a self-contained `viz.html` that opens in a browser with no backend.

Two design choices in the renderer are worth noting. Above 1000 concepts the default layout falls back to a linear one because the force layout freezes the page; `--layout cose` overrides that, and `--max-nodes N` refuses oversized bundles instead. Separately, the trust tier (unverified, machine-confirmed, human-reviewed) and staleness are computed at render time rather than stored. The README's reasoning is that a stored tier is a stored opinion and it goes stale. That is a defensible position, and it also means the badge you see depends on the frontmatter and the clock at the moment of rendering, not on anything recorded in the file.

Installing okf-skills and validating a first bundle

Inside Claude Code, the plugin install is two commands from the marketplace. The README gives them as slash commands, so they are typed into the Claude Code session rather than a shell.

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

For other agents, including Cursor and Codex, the README points at skills.sh and a single `npx` invocation that pulls the okf, validate and visualize skills. Local development skips the marketplace entirely: `claude --plugin-dir /path/to/okf-skills`.

The scripts need `uv`, or `python3` with `pyyaml`. With that in place, validating the example bundle is one command, and `--strict` turns warnings into a failure. You should see the validator print its findings and exit non-zero if the bundle does not conform.

uv run skills/validate/scripts/okf_validate.py examples/sample-bundle --strict

To gate a repository in CI without installing anything locally, the composite action takes a bundle path and a strict flag. The `@v1` ref tracks every release rather than a major line, which the README explains by noting the project is pre-1.0; pin an exact `@okf--v<version>` tag if you need the action frozen.

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

For a rendered graph, the visualize script writes a standalone HTML file. The `--link` flag adds a back-link to the repository, and `--title` sets the page heading.

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

Each concept gets a deep link of the form `viz.html#services/auth-api`, which opens the page with that concept selected.

The MCP server is honest about being redundant

The repository ships a read-only MCP server, `servers/okf_mcp.py`, exposing three tools: `search_concepts(query, limit)`, `read_concept(concept_id)` and `get_neighbors(concept_id)`. Search returns concept cards with `id`, `type`, `title`, `description`, `status` and `stale_after`, and metadata hits rank above body-only hits. Neighbours come from markdown links and bundle-internal `sources`; external URLs are not neighbours. Nothing writes, and no `concept_id` resolves outside the bundle root.

What makes this section unusual is the README's own assessment. It states plainly that for Claude Code the server duplicates Read and Grep, that it was declined on those grounds in July 2026, and that it ships for parity with a category that now expects one. `decisions/mcp-server.md` records the rejection. That candour is rare and it should shape your decision: if you are in Claude Code, the MCP path adds a process and a tool namespace (`mcp__plugin_okf_bundle__search_concepts` and friends) for capability you already have. It earns its place only in a host whose agents cannot reach the files, which is the case the README names. Standalone, the server reads a bundle path argument, then `$OKF_BUNDLE`, then `./.okf`.

{ "mcpServers": { "okf": { "command": "uv",
    "args": ["run", "/path/to/okf-skills/servers/okf_mcp.py", "/path/to/.okf"] } } }

In a project with no bundle the server still connects and reports the absence on the first call, which is a reasonable failure mode: you get a message rather than a silent empty result.

Where okf-skills is the wrong tool

The format's own constraint is the first limit. OKF is markdown with YAML frontmatter. If your knowledge needs typed relations, a query language or transactional updates, a directory of files is the wrong substrate, and no amount of validation changes that. The validator checks conformance to the spec; it does not tell you whether a concept is correct.

The second limit is scale, and the repository documents it rather than hiding it. The renderer falls back to a linear layout above 1000 concepts because the force layout freezes the page. You can override with `--layout cose` or cap with `--max-nodes N`, but both are acknowledgements that the default viewer has a ceiling. A bundle in the tens of thousands of concepts is outside what this visualization path was built for.

The third limit is the pre-1.0 status. `@v1` tracks the latest release rather than a stable major line, which the README states outright. Pinning an exact `@okf--v<version>` tag is the only way to freeze the action, and that means tracking release notes yourself. The release cadence is brisk: v0.9.2, v0.9.3 and v0.9.4 all landed between 2026-09-01 and 2026-09-05. Frequent releases are not a defect, but they do mean the action's behaviour can shift under a moving ref.

How okf-skills differs from plain markdown linting

The obvious alternative is a markdown linter plus a frontmatter schema check, for example markdownlint with a YAML schema validator bolted on. The difference is what gets checked. A linter enforces style and structure on individual files; it has no notion of a bundle, so it cannot check that a link points at a concept that exists, that `sources` resolve inside the bundle, or that a `stale_after` date has passed. Those are cross-file properties, and they are exactly what `okf_validate.py` exists to test.

The second alternative is a knowledge graph database, or a wiki with a structured query layer. Those give you typed relations and real queries. They also give you a service to run, a schema to migrate and a copy of your knowledge that is not readable with `cat`. The README's contrast is that OKF has no runtime and no SDK, and that `git clone` is enough to ship a bundle. That is the trade: you give up query power and get a format that survives tool churn, lives in the same repository as the code, and diffs in a pull request.

The third point of comparison is the agent integration itself. A generic documentation generator can produce markdown from a prompt. okf-skills constrains the agent to a specific format and then verifies the output against the spec, which is the part a prompt alone cannot guarantee.

Maintenance, licensing and what the repository does not document

The last push to the default branch was on 2026-09-05, and the repository is not archived. The most recent release, okf v0.9.4, carries the same timestamp. The project is therefore current, but the version numbering tells you it has not reached 1.0, and the README's own note about `@v1` following every release is the practical consequence.

Licensing is MIT, with a `NOTICE` file at the top level alongside `LICENSE`. That is permissive and compatible with commercial use; it also means no warranty, and the README makes no security or stability claims. If you vendor the validator into a compliance pipeline, the MIT terms are the ones that travel with it. This is not legal advice, and if the bundle you validate contains third-party material, the licence of that material is a separate question the repository does not address.

On upgrade cost, the repository does more than most. The `Makefile` pins the exact `okf_visualize.py` invocations used to regenerate the GitHub Pages demos, and the comment above them explains why: the pages had shipped for weeks without a DOMPurify sanitize fix that had already landed in the generator, because the invocation lived nowhere. Diffing the generated output in CI is what the Makefile comment says stops that recurring. The `make test` target runs the validator, MCP and benchmark test suites, and `make validate` runs the strict check against both `examples/sample-bundle` and the repository's own `.okf` bundle. What the README does not document is a rollback procedure if a new release changes validator behaviour on a bundle that previously passed, so pinning a tag before upgrading is the only recourse the README supports.

Editorial conclusion

Adopt okf-skills if your team already writes architecture notes in markdown and wants a deterministic check before those notes are committed, or if you are running Claude Code and want an agent that produces OKF-shaped output instead of free-form prose. Skip it if you have no bundle to validate and no agent in the loop; the MCP server in particular duplicates Read and Grep inside Claude Code and the repository's own decision record says it was declined on those grounds. Before committing, run `uv run skills/validate/scripts/okf_validate.py .okf --strict` on your own bundle and read the JSON report, because the examples in the repository are the project's own and will not tell you how your frontmatter fares.

Frequently asked questions

Official sources

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