sniperunder123/okf-knowledge

---

⚠️ Disclaimer — this is vibe‑coded. Built fast, for fun, by one person with an AI pair‑programmer. It’s tested and it works, but it’s an unofficial indie project (not affiliated with Google or Anthropic), shipped as‑is with zero guarantees — use at your own risk. Spot a bug? Issues and PRs welcome. 🌊

TL;DR — Knowledge ends up trapped in wikis, Notion, 3,000‑line READMEs, and people’s heads — where AI agents can’t use it well. OKF represents knowledge as a directory of small Markdown files: each file is one concept (a table, an endpoint, a metric, a runbook…), with a tiny YAML header, linked to other concepts like wiki pages. The result is a navigable knowledge graph that agents read natively, that you version in git, and that no vendor owns. This repo is a /okf command that builds and maintains those bundles for you.

---
type: BigQuery Table          # the only required field
title: Orders
description: One row per completed customer order.
resource: bigquery://acme/sales/orders
tags: [sales, orders]
generated: { by: human:maintainer, at: 2026-05-28T00:00:00Z }   # optional, OKF v0.2
---

# Orders

Part of the [sales dataset](/datasets/sales.md). Feeds [gross revenue](/metrics/gross-revenue.md).

---

🤔 The problem OKF solves

Your organization’s knowledge is real but unusable by machines:

• 📚 Scattered across Confluence, Notion, Google Docs, READMEs, Slack threads, and people’s memory.
• 🔒 Locked in proprietary tools that need accounts, APIs, and scraping to read.
• 🧱 Monolithic — the one big doc that’s either loaded whole (expensive, slow) or ignored.
• 🪦 Rotting — nobody edits a 3,000‑line doc, so it silently drifts from reality.
• 🤖 Hostile to agents — an LLM either drowns in irrelevant context or hallucinates the gap.

AI agents are great at reading Markdown and following links. So the fix isn’t another platform — it’s a format: small, linked Markdown files an agent can traverse, a human can read, and git can version.

That format is OKF (Open Knowledge Format), a vendor‑neutral spec from Google Cloud — now at v0.2, in its own dedicated repo, GoogleCloudPlatform/open-knowledge-format. This repo makes an agent fluent in it.

---

✨ Why it works

---

🆚 How OKF compares

OKF doesn’t replace RAG — it feeds it. A curated OKF bundle is a great, structured corpus to embed: you keep an inspectable, versioned source of truth, and let retrieval sit on top.

---

🚀 Quick start

# 1. Get it
git clone https://github.com/sniperunder123/okf-knowledge.git
cd okf-knowledge

# 2. One dependency (for the validator)
pip install -r requirements.txt

# 3. Install the skill — /okf works immediately, in every project
cp -r okf ~/.claude/skills/                              # macOS / Linux
# Windows (PowerShell): Copy-Item -Recurse okf "$env:USERPROFILE\.claude\skills\"

# 4. Try it
python okf/scripts/validate.py okf/resources/example-bundle
# → 10 file(s), 0 error(s)

The skill is named okf, so the command is /okf out of the box — no alias, no config (just like /graphify).

---

🎛️ Usage — the /okf command

okf-knowledge is command‑driven — run it whenever you want a bundle built or brought back in sync:

/okf                      # smart default: sync the okf/ bundle if it exists, else init one
/okf init [path]          # build a new bundle from this project's code + docs
/okf update [path]        # sync the bundle with what changed; fix links, append log.md, validate
/okf query ""   # answer by navigating the bundle, index-first (no full-file dumps)
/okf validate [path]      # run conformance + lint checks
/okf viz [path]           # (re)generate viz.html + graph.mmd
/okf add ""        # add one concept and wire its links

Keep docs in sync while you build. Add to your project’s CLAUDE.md: “After any change to code or docs, run /okf update.” Your agent then refreshes the bundle as part of every task, and validate.py keeps it honest in CI.

---

📦 What’s an OKF bundle?

A bundle is a directory tree of Markdown files. Each non‑reserved file is one concept with a YAML frontmatter block whose only required field is type. Two filenames are reserved at every level: index.md (navigation) and log.md (change history).

example-bundle/
├── index.md                      # the map — start here (declares okf_version: "0.2")
├── log.md                        # chronological change history
├── datasets/
│   └── sales.md                  # type: BigQuery Dataset
├── tables/
│   ├── orders.md                 # type: BigQuery Table
│   └── customers.md              # type: BigQuery Table
├── metrics/
│   └── gross-revenue.md          # type: Metric  (sources + verified + stale_after)
├── computations/
│   └── gross-revenue-computation.md  # type: Attested Computation (OKF v0.2)
├── playbooks/
│   └── revenue-reconciliation.md # type: Playbook
└── references/
    ├── revenue-policy.md         # type: Reference
    ├── skills/run-on-bq.md       # type: Reference (Attested Computation executor)
    └── attesters/sql_equality.py # deterministic attester code (not an OKF concept)

…and the links between those concepts form a graph (/okf viz renders this interactively):

graph LR
    idx[index.md]:::r --> orders & customers & rev & comp & recon & ref
    orders[orders] --> sales[sales] & customers[customers] & rev[gross-revenue]
    customers --> sales
    rev[gross-revenue] --> comp[gross-revenue-computation] & orders & recon[revenue-reconciliation]
    recon --> orders & customers & rev
    classDef r fill:#4285F4,color:#fff,stroke:#2a5bd7;

🐶 We dogfood. This repo describes itself as an OKF bundle at okf/resources/self-bundle/ — the /okf command, the validator, the rules, and the design decisions, all as linked concepts. Run /okf viz okf/resources/self-bundle to explore the graph.

Frontmatter fields

OKF v0.2 additions (all optional — see the full spec for field shapes):

timestamp and a body # Citations list still validate (v0.2 falls back to them) — they’re just superseded.

---

🧠 How an agent actually uses a bundle

The whole point is cheaper, sharper agent reasoning. Ask “how is gross revenue computed and what do I watch at month‑end?”

1. read  index.md                        (~300 tokens)  → find the relevant concepts
2. read  metrics/gross-revenue.md        (~500 tokens)  → the definition + SQL
3. follow → tables/orders.md             (~500 tokens)  → the source columns
4. follow → playbooks/revenue-reconciliation.md (~400 tokens) → the caveats
→ answer.

Versus dumping a monolithic doc into context on every question. On a real migration we ran, a 2,762‑line doc (~40k tokens) became 83 linked concepts — and a typical question now touches ~3 small files (~1.5k tokens). That’s the difference between paying for the whole library every time and walking straight to the right shelf: less context, lower cost, fewer hallucinations.

---

🧩 Concept types cheat‑sheet

type is free‑form — pick descriptive values. Common ones:

Consumers must tolerate unknown types — so you can invent what fits your domain.

---

✅ The validator

okf/scripts/validate.py enforces the three hard OKF conformance rules (unchanged since v0.1) and, with --strict, runs producer lints on your graph — including nudges for the optional OKF v0.2 families.

python okf/scripts/validate.py             # conformance only (CI gate)
python okf/scripts/validate.py  --strict   # + producer lint warnings

Conformance errors are spec violations — a bundle that fails any of the three is not a valid OKF bundle. Producer lints (warnings) flag quality issues in the tool generating the bundle — including “this still looks like v0.1” nudges; they are not spec violations and consumers must tolerate bundles that have them.

resources/example-bundle keeps datasets/sales.md, tables/customers.md, and playbooks/revenue-reconciliation.md on the legacy timestamp field on purpose, so --strict reports 3 migration-nudge lints there by design — everything else in the bundle is fully v0.2 and lint‑clean.

Exit codes: 0 conformant · 1 errors (or warnings under --strict) · 2 bad invocation / PyYAML missing.

🔎 Why a real YAML parser? It uses PyYAML so its verdict matches every other OKF consumer’s. It refuses to guess: if PyYAML is missing it exits with a clear message instead of silently passing a malformed bundle.

🧱 One parser, tested. validate.py and visualize.py share a single okf_common.py module (PyYAML parsing + code‑aware link extraction that ignores links inside code blocks), so the graph the visualizer draws matches exactly what the validator checks. A pytest suite in okf/scripts/tests/ covers the rules and guards against regressions — run pytest.

---

🗺️ When to use OKF — and when not

Great fit

• A large, sprawling system whose knowledge lives in one giant doc (or nowhere).
• AI‑heavy development where agents need to understand the system cheaply.
• Knowledge you want versioned, reviewed, and portable across tools.
• Cross‑cutting links: a metric → its table → its endpoint → its runbook.

Probably overkill

• A tiny project a strong model fully reads in one shot.
• A pure code question where the code itself is the source of truth (OKF shines for the why, the cross‑cutting, the tribal knowledge — not for restating a function).
• Knowledge nobody will maintain — a stale bundle is worse than none. Pair it with /okf update + a CI validate gate.

Being honest beats hype: OKF is leverage when knowledge is big, linked, and agent‑consumed; it’s ceremony when it isn’t.

---

📁 What’s in the repo

okf-knowledge/
├── README.md · LICENSE · requirements.txt
└── okf/                          # ← the skill (copy this folder into ~/.claude/skills/)
    ├── SKILL.md                  # the /okf operating manual
    ├── scripts/
    │   ├── validate.py           # conformance + producer-lint checker
    │   ├── visualize.py          # self-contained graph → viz.html + graph.mmd
    │   ├── okf_common.py         # shared parser + link extraction (used by both)
    │   └── tests/                # pytest suite (run `pytest`)
    └── resources/
        ├── example-bundle/       # a minimal reference bundle (OKF v0.2)
        └── self-bundle/          # this project, documented in its own format (dogfood)

Need the pre-v0.2 skill? Check out the tag/commit before the v0.2 migration in git history — it’s not kept as a separate folder in the published tree.

---

🛠 Requirements

• Python 3.7+ and PyYAML (pip install pyyaml) — required by both validate.py and visualize.py.
• That’s the entire footprint. The skill content (SKILL.md, the example bundle) is just Markdown — it needs nothing.

---

❓ FAQ

---

🗓 Roadmap / not yet

Things that are planned but not yet implemented — contributions welcome:

• Pluggable source connectors for /okf init — bulk generation from a source of truth (e.g. BigQuery schema, dbt manifest, OpenAPI spec) without manual LLM-driven inventory. The spec supports it; the skill doesn’t automate it yet.
• Anti-regression lint for /okf update — detect when an /okf update run silently drops concepts or breaks links that were clean before, and surface them as lint errors rather than letting the bundle silently regress.

---

🤝 Contributing

PRs and issues welcome! Good first contributions: more example bundles (an API or service catalog), additional type recipes, or new validator lints. Before opening a PR, run the validator on the example bundle and the test suite:

python okf/scripts/validate.py okf/resources/example-bundle --strict   # 3 expected lints, see note above
pytest

---

📄 License

MIT © okf-knowledge contributors.

Provided as‑is, with no warranty of any kind (see LICENSE). This is an unofficial, vibe‑coded community project — not affiliated with, endorsed by, or supported by Google or Anthropic. Use at your own risk.

Open Knowledge Format itself is published by Google Cloud under Apache‑2.0 — see the official spec (the earlier copy under knowledge-catalog/okf/ is a frozen, no-longer-maintained snapshot).