/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), as a GitHub Action for repos with no agent at all, and as a read-only MCP server for hosts whose agents cannot reach the files. This one is v0.2 throughout: trust signals, provenance and staleness, validated by skills/validate/scripts/okf_validate.py.

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

Install

As a Claude Code plugin:

/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            # the okf, validate & visualize skills

Local development (no marketplace): claude --plugin-dir /path/to/okf-skills.

Both layouts coexist in this one repo: .claude-plugin/ makes it a plugin marketplace, skills/<name>/SKILL.md makes it skills.sh-discoverable. Scripts live inside their skills and are referenced via ${CLAUDE_SKILL_DIR}, so they work in either path. The scripts need uv (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, zero-config:
uv run skills/validate/scripts/okf_validate.py .okf --strict
# gate in CI while some warnings are still outstanding:
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"

@v1 follows every release (the repo is pre-1.0, so it tracks the latest one rather than a major line). Pin an exact @okf--v<version> tag instead if you want the action frozen.

The step also exposes a report output: the validator's JSON report (--json), for a later step to post or parse via ${{ steps.<id>.outputs.report }}.

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"

Above 1000 concepts the default layout falls back to a linear one (force layout freezes the page); override with --layout cose, or refuse oversized bundles with --max-nodes N.

Every concept gets a shareable deep link (viz.html#services/auth-api opens with that concept 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.

Read a bundle over MCP. A read-only server exposes any bundle to a host that speaks MCP, for agents that have no file tools of their own:

Nothing writes, and no concept_id resolves outside the bundle root.

It ships with the plugin and starts with it, reading ./.okf, so inside Claude Code there is nothing to configure: the tools appear as mcp__plugin_okf_bundle__search_concepts and friends. In a project with no bundle the server still connects and says so on the first call.

Standalone, or for any other MCP host:

uv run servers/okf_mcp.py .okf           # stdio; a bundle path, else $OKF_BUNDLE, else ./.okf

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

Worth saying plainly: for Claude Code this duplicates Read and Grep, and it was declined on those grounds in July 2026. It ships for parity with a category that now expects one, and decisions/mcp-server.md records that as the reason instead of inventing a user need.

Keep it up to date. Two opt-in ways to make upkeep automatic:

• Soft mode: paste templates/CLAUDE-okf.md into your project's CLAUDE.md (or ~/.claude/CLAUDE.md) to have Claude consult .okf/ before tasks and write knowledge back after changes.
• Enforced mode: add upkeep: enforced to .okf/index.md's frontmatter to arm the plugin's dormant Stop hook, which then blocks finishing when tracked files changed but .okf/log.md wasn't updated. Off by default; a user overrides any bundle with OKF_HOOK=off. Full gate sequence: stop-hook concept.

What's inside

How a bundle looks

A bundle is a directory of markdown files; a concept's path is its ID. The only rule for conformance is YAML frontmatter with a non-empty type; everything else is optional.

.okf/
├── index.md                  # progressive disclosure (root carries okf_version)
├── log.md                    # ISO-dated change history, newest first
├── services/auth-api.md      # one concept = one file; path is its ID
├── decisions/use-okf.md
└── metrics/checkout-conversion.md

---
type: Service
title: Auth API
description: Issues and verifies short-lived access tokens.
resource: https://github.com/acme/auth
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
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. Full normative detail is in SPEC.md.

Upgrading from v0.1? --migrate rewrites the two superseded constructs (timestamp → generated.at, body # Citations → sources) in place, textually and idempotently. The tools read both meanwhile and flag the old forms as warnings, never errors; --strict is the nudge, --migrate is the door:

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

What has actually been measured

Two experiments live in benchmark/, both pre-registered and tagged before their measurement run, both published with their transcripts and with the defects the runs exposed. Read the results files rather than these two lines; the headline numbers are smaller than they look.

Neither experiment estimates what OKF is worth in a real repository, where prose, filenames and history already carry recency; both say so in their own headlines. A third-party benchmark measures a different v0.2 claim — sufficiency — and measures it well: aws-samples/sample-okf-llm-wiki scores EX 74.0 on BIRD mini_dev with 500 independent agents.

Repository layout

okf-skills/
├── .claude-plugin/{plugin.json, marketplace.json}
├── skills/{okf, validate, visualize}/{SKILL.md, scripts/}
├── hooks/                         # the dormant Stop hook
├── servers/okf_mcp.py             # the read-only MCP server (.mcp.json wires it)
├── benchmark/{trust,gate}/        # the two experiments, protocols and published runs
├── examples/sample-bundle/        # the live-demo bundle
├── docs/                          # GitHub Pages: the live interactive demo
├── templates/CLAUDE-okf.md
├── action.yml                     # the CI-gating GitHub Action
├── Makefile                       # make docs / test / validate; CI runs `make docs`
└── .github/workflows/{ci,release}.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. Releases are automatic: bump version in .claude-plugin/plugin.json and merging to main tags and publishes okf--v<version> on its own. That bump is required, not optional: a PR touching the shipped surface (skills/, hooks/, templates/, action.yml, .claude-plugin/) fails CI until the version is raised. A bump must also add a ## [<version>] section to CHANGELOG.md; CI refuses the PR otherwise. Docs and tests are exempt. A PR touching skills/*/scripts/ or hooks/ must additionally update .okf/, and the skip-version-check label bypasses all three checks.

This repo's own bundle sets upkeep: enforced, so the plugin's Stop hook blocks finishing until .okf/log.md records your change. Set OKF_HOOK=off to opt out.

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