/okf-open-knowledge-format

name: okf-open-knowledge-format
description: >
  Create, validate, and enrich Open Knowledge Format (OKF) bundles — the open
  spec for representing organizational knowledge as markdown files with YAML
  frontmatter. Use when the user mentions 'OKF', 'Open Knowledge Format',
  'knowledge bundle', 'OKF bundle', 'create a knowledge base for agents',
  'validate OKF', 'convert to OKF', 'enrich knowledge docs', 'agent-readable
  knowledge', 'LLM wiki', 'knowledge catalog', 'kcmd', or wants to structure
  knowledge as markdown files for AI agent consumption. Also use when the user
  has a directory of markdown files and wants to make them interoperable or
  conformant with the OKF standard. Even for simple requests like 'make this
  folder OKF conformant' — the skill has critical structural rules the agent
  needs.
metadata:
  author: ft.ia.br
  version: "2.0"
  date: 2026-08-25
  repository: https://github.com/fabricioctelles/skills
  license: Apache-2.0
  category: library-and-api-reference
  upstream: https://github.com/GoogleCloudPlatform/open-knowledge-format

Open Knowledge Format (OKF)

OKF is a vendor-neutral, open spec (v0.2, released by 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](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)) into an interoperable format: wikis written by different producers can be consumed by different agents without translation.

**v0.2 adds:** provenance tracking (`sources`), trust signals (`generated`, `verified`), lifecycle management (`status`, `stale_after`), and **Attested Computations** — a new concept type for sanctioned, verifiable calculations.

For the full spec, see:

• [references/spec-v02.md](references/spec-v02.md) — Current version (v0.2)
• [references/spec-v01.md](references/spec-v01.md) — Legacy version (v0.1)

Design Principles

1. **Minimally opinionated** — Only `type` is required. The spec defines interoperability surface, not content model. 2. **Producer/consumer independence** — Who writes and who reads are decoupled. Human-authored bundles feed agents; LLM-generated bundles are browsed by humans. 3. **Format, not platform** — No cloud, SDK, or vendor dependency. Value comes from how many parties speak it. 4. **Trust is first-class** — v0.2 makes provenance, verification, and freshness queryable from frontmatter.

---

Key Terminology

| Term | Definition | |------|------------| | **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. | | **Source** | A material a concept derives from, recorded in the `sources` frontmatter field. | | **Provenance** | The set of sources a concept derives from. | | **Actor** | Identity string: `<producer>/<version>` for agents, `human:<id>` for people, `process:<id>` for automation. | | **Trust tier** | Level derived from `verified`: unverified, machine-confirmed, or human-reviewed. | | **Attested Computation** | A concept (`type: Attested Computation`) carrying a sanctioned way to compute a value. |

---

Quick Reference — Frontmatter Fields

Core Fields (all concepts)

| Field | Required? | Description | |-------|-----------|-------------| | `type` | **YES** | Kind of concept (free-form string, e.g. `BigQuery Table`, `Metric`, `Playbook`, `Attested Computation`) | | `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 |

Trust & Lifecycle Fields (v0.2)

| Field | Description | |-------|-------------| | `generated` | `{ by: <actor>, at: <ISO8601> }` — Who/what created this content and when | | `verified` | List of `{ by: <actor>, at: <ISO8601> }` — Who confirmed correctness | | `status` | `draft` \| `stable` \| `deprecated` — Default: `stable` | | `stale_after` | ISO 8601 datetime — Content is stale on/after this instant |

Provenance Fields (v0.2)

| Field | Description | |-------|-------------| | `sources` | List of source entries (see below) | | `usage_window` | `{ from, to }` — Time range for `usage_count` signals |

Each `sources` entry:

• `resource` (REQUIRED): URL, bundle-relative path, or scope descriptor
• `id`: Stable key for footnote attribution
• `title`: Human-readable label
• `author`: Actor who produced the source
• `usage_count`: How often exercised (liveness signal)
• `last_modified`: When the source last changed

Attested Computation Fields (v0.2)

For concepts with `type: Attested Computation`:

| Field | Description | |-------|-------------| | `runtime` | REQUIRED. How to run it: `bigquery`, `postgres`, `dbt`, `python`, `Looker` | | `parameters` | List of `{ name, type, required }` — Typed holes the agent fills | | `computation` | Path to computation file (if not inline in body) | | `executor` | `{ resource, receipt: [...] }` — How to run and what evidence to capture | | `attester` | `{ resource }` — Deterministic code that verifies the receipt |

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.2"`.

Conventional Body Headings