okf-open-knowledge-format

Files (6)

• SKILL.md
• conversion.md · references/
• examples.md · references/
• spec-v01.md · references/
• spec-v02.md · references/
• validate.sh · scripts/

SKILL.md (first lines)

# 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

| Heading | When to use |
|---------|-------------|
| `# Schema` | Data assets — describe columns/fields |
| `# Examples` | Show concrete usage (code blocks, queries) |
| `# Computation` | Attested Computation — the sanctioned code/query |

---

## Actor Convention

Fields that record identity (`generated.by`, `verified[].by`, `sources[].author`) use:

- `<producer>/<version>` for agents: `reference_agent/gemini-2.5-pro`
- `human:<id>` for people: `human:ahormati`
- `process:<id>` for automation: `process:finance-nightly`

Trust tiers are derived from the `human:` prefix — human-verified > machine-confirmed > unverified.

---

## Trust Tiers

From fabricioctelles/skills, Apache-2.0.

More from fabricioctelles/skills