Open Knowledge Format (OKF)

OKF is a vendor-neutral, open spec (v0.1, announced June 12, 2026 by Sam McVeety & Amir Hormati at Google Cloud) for representing knowledge as a directory of markdown files with YAML frontmatter. No SDK required — if you can

cat

a file, you can read OKF.

It formalizes the "LLM Wiki" pattern (Karpathy's gist) into an interoperable format: wikis written by different producers can be consumed by different agents without translation.

For the full spec, see references/spec-v01.md.

Design Principles

Minimally opinionated — Only
```
type
```
is required. The spec defines interoperability surface, not content model.
Producer/consumer independence — Who writes and who reads are decoupled. Human-authored bundles feed agents; LLM-generated bundles are browsed by humans.
Format, not platform — No cloud, SDK, or vendor dependency. Value comes from how many parties speak it.

Key Terminology

Bundle — A directory tree of
```
.md
```
files. The unit of distribution (git repo, tarball, or subdirectory).
Concept — One markdown file = one unit of knowledge (table, metric, playbook, API, etc.)
Concept ID — File path within the bundle, minus
```
.md
```
suffix. Example:
```
tables/users.md
```
→ ID
```
tables/users
```
Frontmatter — YAML block between
```
---
```
delimiters at file top.
Body — Everything after the frontmatter. Standard markdown.
Link — Standard markdown link expressing a relationship between concepts.
Citation — Link to an external source backing a claim in the body.

Quick Reference — Frontmatter Fields

Field	Required?	Description
`type`	YES	Kind of concept (free-form string, e.g. `BigQuery Table` , `Metric` , `Playbook` , `API Endpoint` )
`title`	Recommended	Human-readable display name
`description`	Recommended	One-sentence summary
`resource`	Recommended	URI identifying the underlying asset (omit for abstract concepts)
`tags`	Optional	YAML list for cross-cutting categorization
`timestamp`	Optional	ISO 8601 datetime of last meaningful change

Additional producer-defined keys are allowed. Never reject unknown fields.

Reserved Filenames

File	Purpose	Has frontmatter?
`index.md`	Directory listing for progressive disclosure	NO*
`log.md`	Change history, newest first	NO

*Exception: bundle-root

index.md

MAY have frontmatter with

okf_version: "0.1"

to declare spec version.

Conventional Body Headings

Heading	When to use
`# Schema`	Data assets — describe columns/fields
`# Examples`	Show concrete usage (code blocks, queries)
`# Citations`	List external sources backing claims (numbered)

Create a Bundle

When the user wants to create an OKF bundle from scratch:

1. Determine scope and structure

Ask: What knowledge are we capturing? (tables, metrics, APIs, playbooks, etc.) Organize into a directory tree that makes sense for the domain.

2. Create concept documents

Each concept = one

.md

file. Minimal conformant example:

markdown

---
type: Metric
title: Monthly Recurring Revenue
description: Sum of all active subscription revenue normalized to monthly.
tags: [revenue, saas]
timestamp: 2026-06-13T10:00:00Z
---

# Monthly Recurring Revenue (MRR)

## Definition

Sum of all active subscriptions normalized to a monthly amount.
Excludes one-time fees and overages.

## Formula

`MRR = Σ(active_subscription_monthly_value)`

## Related

- [Churn Rate](./churn.md) uses MRR as denominator
- [ARR](./arr.md) = MRR × 12

For more examples across domains, see references/examples.md.

3. Cross-link concepts

Use standard markdown links. Two forms:

Absolute (bundle-relative, starts with
```
/
```
):
```
[customers](/tables/customers.md)
```
— preferred (stable when files move)
Relative:
```
[churn](./churn.md)
```

Links assert relationships. The kind of relationship is conveyed by surrounding prose, not by the link syntax. Broken links are explicitly permitted — they represent knowledge not yet written.

4. Generate index.md

Place in any directory for progressive disclosure. No frontmatter. Format:

markdown

# Metrics

- [MRR](./mrr.md) - Monthly recurring revenue
- [Churn](./churn.md) - Monthly churn rate
- [NPS](./nps.md) - Net Promoter Score

Entries should include the description from the linked concept's frontmatter.

5. Generate log.md (optional)

Chronological change history, newest first, ISO 8601 date headings:

markdown

# Update Log

## 2026-06-13
- **Creation**: Added MRR, Churn, and NPS metrics.
- **Creation**: Established directory structure.

## 2026-06-10
- **Initialization**: Bundle created.

The bold leading word (

**Update**

**Creation**

**Deprecation**

) is convention, not requirement.

6. Declare version (optional)

Bundle-root

index.md

may include frontmatter declaring the spec version:

markdown

---
okf_version: "0.1"
---

# My Knowledge Bundle

- [Tables](./tables/) - Database tables
- [Metrics](./metrics/) - Business KPIs

This is the only place frontmatter is permitted in an

index.md

7. Distribution

A bundle can be distributed as:

A git repository (recommended — history, attribution, diffs)
A tarball or zip archive
A subdirectory within a larger repository

8. Verify conformance

Three rules — all must pass:

Every non-reserved
```
.md
```
file has parseable YAML frontmatter
Every frontmatter has a non-empty
```
type
```
field
Reserved files (
```
index.md
```
,
```
log.md
```
) follow their defined structure when present

Validate a Bundle

Preferred: okflint (when available)

okflint is a dedicated Python linter for OKF bundles with 18 rules across 3 tiers (OKF core, profile, hygiene). If installed, always prefer it over the built-in bash script.

Agent behavior: Before validating, check if okflint is installed (

command -v okflint

). If NOT installed, ask the user:

"okflint (linter dedicado para OKF com 18 regras, profiles via manifesto e suporte a wikilinks) não está instalado. Quer que eu instale? Opções:
uv tool install okflint
(recomendado, isolado)
pip install okflint
Seguir sem ele (validação básica com o script bash embutido)"

If the user agrees to install:

bash

# Option 1: uv (recommended — installs isolated, no venv needed)
uv tool install okflint

# Option 2: pip (installs in current environment)
pip install okflint

# Verify installation
okflint --version

After installation (or if already available):

bash

# Full validation with manifest (if okf-base.yaml exists)
if [ -f okf-base.yaml ]; then
  okflint validate --manifest okf-base.yaml ./bundle/
else
  # Core OKF validation only (no manifest needed)
  okflint validate ./bundle/
fi

okflint advantages over the built-in script:

Manifest-driven profiles (enforce custom required fields, status vocabularies, per-type constraints)
Wikilink resolution against full Obsidian vault
JSON output (
```
--json
```
) for CI pipeline parsing
Detects broken markdown links and ambiguous wikilinks
Exit codes:
```
0
```
= pass,
```
1
```
= conformance failure,
```
2
```
= bad manifest

Fallback: built-in bash script

When okflint is not installed, use scripts/validate.sh which checks the 3 core conformance rules.

When asked to validate, check the 3 conformance rules. Report:

✅ PASS: 12/12 concept files have valid frontmatter with type field
✅ PASS: index.md follows list structure (no frontmatter)
✅ PASS: log.md uses ISO 8601 date headings, newest first

⚠  WARNING: 3 files missing 'description' field (recommended)
⚠  WARNING: 2 broken cross-links (permitted but worth noting)

For a script-based check, see scripts/validate.sh.

Errors (conformance failures)

```
E1
```
: File
```
{path}
```
has no YAML frontmatter
```
E2
```
: File
```
{path}
```
has frontmatter but no
```
type
```
field (or empty)
```
E3
```
: Reserved file
```
{path}
```
has unexpected structure

Warnings (non-blocking, spec allows these)

```
W1
```
: Missing recommended field
```
title
```
or
```
description
```
```
W2
```
: Broken cross-link
```
{link}
```
in
```
{file}
```
```
W3
```
: No
```
timestamp
```
field
```
W4
```
: No
```
index.md
```
in directory
```
{dir}
```
```
W5
```
:
```
log.md
```
dates not in ISO 8601 format

Consumers MUST NOT reject a bundle because of: missing optional fields, unknown type values, unknown frontmatter keys, broken links, or missing index files.

Enrich Concepts

When the user has existing OKF concepts that need enrichment:

Add schema section

For data assets, add

# Schema

with a columns table:

markdown

# Schema

| Column | Type | Description |
|--------|------|-------------|
| `order_id` | STRING | Unique identifier |
| `customer_id` | STRING | FK to [customers](/tables/customers.md) |

Add examples section

For APIs, queries, or tools, add

# Examples

with fenced code blocks showing usage.

Add citations

When claims reference external sources, add

# Citations

at the bottom, numbered:

markdown

# Citations

[1] [Official docs](https://example.com/docs)
[2] [Internal runbook](https://wiki.internal/quality)

Citations may be absolute URLs, bundle-relative paths, or paths into a

references/

subdirectory.

Add cross-links

Weave links into natural prose. Don't create a standalone "links" section — express relationships in context where they're meaningful.

Fill recommended fields

title

description

tags

, or

timestamp

are missing, add them. Derive values from body content when possible.

Enrichment workflow reference

The official enrichment agent follows this pattern — apply the same logic manually:

Start with metadata-only docs (just frontmatter + minimal body)
Add schema/structure from source system
Add citations from authoritative documentation
Weave cross-links based on discovered relationships (FKs, shared tags, join paths)
Generate
```
index.md
```
files for progressive disclosure

Convert Sources to OKF

For detailed conversion guides, see references/conversion.md.

Quick rules

Notion export: Properties → frontmatter. Remove UUID suffixes from filenames. Convert Notion links → relative markdown links.

Obsidian vault: Convert

[[wikilinks]]

→

[title](./file.md)

. Ensure

type

field exists. Move inline

#tags

to frontmatter.

CSV/spreadsheet: Each row = one concept. Map columns to frontmatter fields. First column = filename.

Guardrails

NEVER invent data. If you don't know the correct
```
type
```
, ask. If you don't have schema info, leave it out. No fabricated URLs or column names.
Preserve unknown fields. OKF explicitly allows extension. Don't delete fields you don't recognize.
Don't impose taxonomy. Type values are free-form strings. Suggest descriptive values but never reject a bundle for having unexpected types.
Broken links are OK. The spec explicitly permits them — they represent not-yet-written knowledge.
Minimal by default. Generate only
```
type
```
(required) + recommended fields that are warranted. Don't pad with empty values.
Ask before assuming. If the domain is unclear, ask what types and structure make sense.

Serve via Google Cloud Knowledge Catalog

Google Cloud's Knowledge Catalog natively ingests OKF bundles and serves them to agents. This is the enterprise path — optional but powerful.

kcmd CLI (Metadata as Code)

kcmd

is a bidirectional sync tool between OKF-like local metadata and Knowledge Catalog. Think "git for metadata."

bash

# Initialize from BigQuery dataset
kcmd init --bigquery-dataset <project>.<dataset>

# Pull current state from catalog
kcmd pull

# Push local changes
kcmd push --dry-run
kcmd push

Also ships as an MCP server for agent integration:

json

{
  "mcpServers": {
    "kc-mac": {
      "command": "kcmd",
      "args": ["mcp", "--path", "/path/to/root"]
    }
  }
}

MCP tools:

pull

push

list-entries

lookup-entry

modify-entry

Reference Enrichment Agent

The official enrichment agent (Python, ADK, Gemini) auto-generates OKF bundles from BigQuery metadata. Two-pass architecture:

BQ pass — one OKF doc per table/view from metadata
Web pass — LLM crawls seed URLs and for each page decides to:
- (a) Enrich existing concepts with citations/schemas
- (b) Mint a new
```
references/<slug>
```
  doc
- (c) Skip irrelevant content

Controls:

--web-seed-file

--web-max-pages

--web-allowed-host

--no-web

When to mention this to users: If they're enriching BigQuery datasets, point them to the reference agent. If they want enterprise catalog integration, point to kcmd and the ingest demo.

Output Format

When creating a bundle, present results as:

Directory tree showing the full structure
Each file's content in fenced code blocks
Conformance check confirming the bundle passes the 3 rules

saas-metrics/
├── index.md
├── log.md
├── mrr.md
├── churn.md
└── nps.md

Then show each file, then confirm: "Bundle is OKF v0.1 conformant ✅"

okf-open-knowledge-format

NPX Install

Tags

SKILL.md Content

Open Knowledge Format (OKF)

Design Principles

Key Terminology

Quick Reference — Frontmatter Fields

Reserved Filenames

Conventional Body Headings

Create a Bundle

1. Determine scope and structure

2. Create concept documents

3. Cross-link concepts

4. Generate index.md

5. Generate log.md (optional)

6. Declare version (optional)

7. Distribution

8. Verify conformance

Validate a Bundle

Preferred: okflint (when available)

Fallback: built-in bash script

Errors (conformance failures)

Warnings (non-blocking, spec allows these)

Enrich Concepts

Add schema section

Add examples section

Add citations

Add cross-links

Fill recommended fields

Enrichment workflow reference

Convert Sources to OKF

Quick rules

Guardrails

Serve via Google Cloud Knowledge Catalog

kcmd CLI (Metadata as Code)

Reference Enrichment Agent

Output Format