okf · diff
git:20260720.d4629b8 to git:20260726.da2bab6
192 added, 63 removed. Audit A to A.
---
name: okf
- description: Read, author, and validate Open Knowledge Format (OKF) bundles — knowledge represented as a directory of markdown files with YAML frontmatter. Use when a repo contains an OKF bundle (concept docs with a `type` field, an `index.md`/`log.md`), when the user mentions OKF or the Open Knowledge Format, or when asked to author, validate, convert to, or keep an OKF knowledge base current.
+ description: Read, author, maintain, and validate Open Knowledge Format (OKF v0.2) bundles — knowledge as a directory of markdown files with YAML frontmatter, carrying provenance, trust, lifecycle, and attested computations. Use when a repo holds an OKF bundle (concept docs with a `type` field, an `index.md`/`log.md`), when the user mentions OKF or the Open Knowledge Format, or when asked to author, validate, convert to, or keep an OKF knowledge base current.
user-invocable: true
---
- # Open Knowledge Format (OKF)
+ # Open Knowledge Format (OKF) v0.2
- OKF is an open spec (Google Cloud, v0.1) for representing knowledge as a plain
- **directory of markdown files with YAML frontmatter** — no database, SDK, or
- runtime. If you can `cat` a file, you can read OKF. This skill carries the whole
- mental model inline so it works offline; consult the spec only for edge cases.
+ OKF represents knowledge as a plain **directory of markdown files with YAML
+ frontmatter** — no database, SDK, or runtime. If you can `cat` a file, you can
+ read OKF; if you can `git clone` a repo, you can ship it.
- Spec: <https://okf.md/spec/> · Overview: <https://okf.md/>
+ The one authoritative spec is `SPEC.md` in the Google Cloud knowledge-catalog
+ repository:
+ <https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md>.
+ Treat any other site or summary as hearsay. This skill carries the working model
+ inline so it functions offline; read the spec itself for edge cases.
- ## The model (all of it)
+ The point of v0.2 is that a corpus is now mostly **written and maintained by
+ agents**, so a reader needs frontmatter answers to: what was this made from
+ (provenance), how much should I trust it (trust), is it still true (freshness),
+ and was this number computed the sanctioned way (attestation).
+ ## The model
+
- **Bundle** — a directory tree of markdown; the unit of distribution. There is
- **no required root marker file** and no mandated directory name, so a bundle is
- simply a directory someone declares to be OKF (often `.okf/`, `okf/`, or
- `knowledge/`, but that is convention, not spec).
+ **no root marker file and no mandated directory name**: a bundle is whatever
+ directory someone declares to be one (`knowledge/`, `okf/`, `.okf/` are
+ conventions, not spec). Never guess — take the location from the user or from
+ `AGENTS.md`.
- **Concept** — one `.md` file = one unit of knowledge: a table, an API, a
metric, a process, an idea.
- - **Concept-id** — the file path within the bundle minus `.md`
+ - **Concept ID** — the file path within the bundle minus `.md`
(`tables/users.md` → `tables/users`).
- - **Links** — plain markdown links between concepts turn the tree into a graph.
- Prefer bundle-absolute paths starting with `/` (`[users](/tables/users)`).
- - **Reserved files** (both optional):
+ - **Links** — ordinary markdown links between concepts make the tree a graph.
+ Prefer bundle-absolute paths starting with `/` (`[users](/tables/users.md)`);
+ relative paths are also valid. A link asserts an untyped relationship; the
+ prose around it says what kind.
+ - **Reserved files** (both optional, at any directory level, never concepts):
- `index.md` — a directory listing for **progressive disclosure**: read it
- first to see what a bundle holds without opening every file.
- - `log.md` — a chronological changelog, newest-relevant, dated ISO 8601.
+ first to see what a bundle holds without opening every file. No frontmatter,
+ except that the bundle-root `index.md` may carry `okf_version: "0.2"`.
+ - `log.md` — dated change history, newest first, `## YYYY-MM-DD` headings.
## Frontmatter
- Every concept file has YAML frontmatter. Only one field is **required**:
+ Only `type` is required. A concept carrying nothing but `type` is fully
+ conformant.
- - `type` (required) — a short producer-chosen string, e.g. `BigQuery Table`,
- `Metric`, `Playbook`. Values are not centrally registered.
+ | Field | Status | Notes |
+ |---|---|---|
+ | `type` | **required** | Producer-chosen string: `Metric`, `BigQuery Table`, `Playbook`, `Attested Computation`. Not centrally registered. |
+ | `title` | recommended | Display name; consumers may fall back to the filename. |
+ | `description` | recommended | One sentence; feeds `index.md` entries and search snippets. |
+ | `resource` | recommended | URI of the underlying asset. Absent for abstract concepts. |
+ | `tags` | recommended | List of short strings. |
- Recommended optional fields: `title`, `description` (one sentence), `resource`
- (a URI for the underlying asset), `tags` (list), `timestamp` (ISO 8601 of last
- significant change). Producers may add more keys; **consumers must preserve
- unknown keys** and must not choke on them.
+ Producers may add any other key. As a consumer, **preserve unknown keys** when
+ round-tripping and never reject a document for carrying them.
+ Bodies are plain markdown; prefer headings, lists, tables, and fenced code over
+ freeform prose. `# Schema`, `# Examples`, and `# Computation` are conventional
+ headings — use them when they apply.
+
```markdown
---
type: Module
title: tuika
description: Standalone terminal-UI toolkit powering the --fullscreen renderer.
resource: file:///crates/tuika
- tags: [ui, ratatui, terminal]
- timestamp: 2026-07-19T10:30:00Z
+ tags: [ui, terminal]
+ status: stable
+ generated: { by: human:mchaliy, at: 2026-07-19T10:30:00Z }
---
# tuika
- Layout, overlays, focus, and components over ratatui.
+ Layout, overlays, focus, and components for terminal UIs.
- ## Relationships
- - Consumed by the [yolop host](/modules/yolop-yep)
+ # Relationships
+
+ Consumed by the [yolop host](/modules/yolop-yep.md).
```
- ## Conformance (the only hard rules)
+ ## Provenance, trust, lifecycle
- A bundle conforms to OKF v0.1 if:
+ All optional — but their **absence carries meaning**, so populate them for
+ anything an agent generated. Never reject a concept for lacking them.
- 1. Every non-reserved `.md` file has parseable YAML frontmatter.
- 2. Every such frontmatter has a non-empty `type` field.
- 3. Reserved files (`index.md`, `log.md`) follow their structure.
+ **`sources`** — the materials a concept derives from:
- Everything else is **soft guidance**. Do not reject a bundle for missing
- optional fields, unknown `type` values, broken links, or an absent `index.md` —
- the format is deliberately permissive. Validate with `scripts/validate_okf.py`
- under `${SKILL_DIR}` (no dependencies): `python3 ${SKILL_DIR}/scripts/validate_okf.py <bundle-dir>`.
+ ```yaml
+ sources:
+ - id: ga4-schema # stable key for per-claim attribution
+ resource: https://developers.google.com/analytics/bigquery/export-schema
+ title: GA4 BigQuery Export schema # required within an entry: resource
+ author: team:ga4-docs # credibility signal: authority
+ usage_count: 5000 # credibility signal: adoption/liveness
+ last_modified: 2026-05-30 # credibility signal: recency of the source
+ usage_window: { from: 2026-06-01, to: 2026-06-30 } # frames every usage_count
+ ```
- ## Consuming a bundle
+ `resource` may name a followable artifact (URL, bundle path, `references/` file)
+ or a scope descriptor it cannot follow (`all queries in project X`). OKF stores
+ objective **signals**, never a credibility score — infer, do not persist a
+ verdict. Read `usage_count` as liveness and trend, not a precise ranking.
+ Lineage is expressed by linking: when a `resource` points at another concept,
+ recurse into its own `sources`.
- When a repo contains an OKF bundle, treat it as curated, high-signal context:
+ Attribute a specific claim with a markdown footnote whose label **is** a
+ `sources[].id` — keyed, so reordering the list cannot misattribute:
- 1. Read `index.md` at the bundle root first — it maps the territory cheaply.
- 2. Open only the concept docs relevant to the task; follow links to related
- concepts instead of grepping blindly.
- 3. Check `log.md` when recency matters.
+ ```markdown
+ The `events_` table is sharded daily as `events_YYYYMMDD`.[^ga4-schema]
- ## Authoring a concept
+ [^ga4-schema]: GA4 BigQuery Export schema
+ ```
- 1. Pick a stable concept-id (its path); group related concepts in subdirectories.
- 2. Write frontmatter — always `type`; add `title`/`description`/`timestamp` for
- anything others will read.
- 3. Write the body as normal markdown; link related concepts with `/`-absolute
- paths so links survive moves.
- 4. Keep `index.md` and `log.md` current when you add or change concepts.
+ **`generated` and `verified`** — who wrote it versus who confirmed it, kept
+ deliberately separate:
- ## Producing / maintaining a bundle in this repo
+ ```yaml
+ generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }
+ verified:
+ - { by: human:ahormati, at: 2026-06-25T09:00:00Z }
+ - { by: process:finance-nightly, at: 2026-06-26T02:00:00Z }
+ ```
- If this repo asks yolop to keep a knowledge bundle current (e.g. an `.okf/`
- directory referenced from `AGENTS.md`), after a change that alters durable facts
- about the codebase:
+ `generated.by` is required within `generated`; `generated.at` marks the last
+ meaningful content change. A bare `verified: { by, at }` mapping **must** be
+ read as a one-element list. Actors follow one convention: `<producer>/<version>`
+ for agents, `human:<id>` for people, `process:<id>` for automated processes. The
+ `human:` prefix is load-bearing — trust tiers key off it:
- - Add or update the affected concept file(s), bumping their `timestamp`.
- - Update `index.md` if the set of concepts changed.
- - Append a dated entry to `log.md`.
+ - no `verified` ⇒ **unverified**
+ - `verified` by non-`human:` actors only ⇒ **machine-confirmed**
+ - any `human:<id>` verifier ⇒ **human-reviewed**
- Write down only durable, reusable knowledge — architecture, contracts,
- invariants, processes — not transient task notes. A bundle that rots into stale
- docs is worse than none; keep it accurate or leave it out.
+ **Lifecycle** — `status: draft | stable | deprecated` (absent ⇒ `stable`) and
+ `stale_after: YYYY-MM-DD`, an absolute date; a concept is stale when
+ `today >= stale_after`.
+ ## Attested computations
+
+ A sanctioned computation is its own concept, `type: Attested Computation`, that
+ value-consuming concepts (a `Metric`, a table) link to. Provenance answers
+ "where did this claim come from"; attestation answers "was this number produced
+ the way we said it must be".
+
+ ```yaml
+ runtime: bigquery # REQUIRED for this type; defines what parameters mean
+ parameters:
+ - { name: year, type: integer, required: true }
+ computation: references/computations/revenue.sql # or omit and inline under `# Computation`
+ executor:
+ resource: references/skills/run-on-bq.md # run instructions/code
+ receipt: [job_id, executed_sql, result] # evidence a run must return
+ attester:
+ resource: references/attesters/sql-equality.py # deterministic, no-LLM check
+ ```
+
+ Rules that matter when you are the agent in the loop:
+
+ - You may supply **values** for declared `parameters` only. You **must not**
+ author or edit the computation — rewriting it is exactly what attestation
+ detects.
+ - Discover → load contract → parameterize → execute (executor returns a receipt)
+ → attest (deterministic code compares the expanded artifact against the
+ sanctioned one) → gate. Refuse to present a failing attestation; warn when
+ `today >= stale_after`. Receipts and verdicts are runtime artifacts — never
+ write them into the bundle.
+ - `verified` and attestation are both needed: `verified` says the *definition*
+ still matches policy, attestation says a *single run* was honest.
+
+ Each computation carries its own trust state, so revenue can be fresh while
+ profit is stale. One figure, one concept.
+
+ ## Conformance
+
+ A bundle conforms if, and only if:
+
+ 1. Every non-reserved `.md` file has a parseable YAML frontmatter block.
+ 2. Every such frontmatter has a non-empty `type`.
+ 3. Present `index.md`/`log.md` files follow their structures.
+
+ Everything else is soft guidance. Do **not** reject a bundle for missing
+ optional fields, unknown `type` values, unknown frontmatter keys, broken links
+ (they may be not-yet-written knowledge), or an absent `index.md`. Unrecognized
+ `okf_version` ⇒ best-effort consumption, not refusal.
+
+ Check with the bundled zero-dependency validator:
+
+ ```bash
+ python3 ${SKILL_DIR}/scripts/validate_okf.py <bundle-dir> # the 3 rules
+ python3 ${SKILL_DIR}/scripts/validate_okf.py <bundle-dir> --strict --check-links
+ ```
+
+ `--strict` adds producer-side lint (`title`, `description`, `generated`,
+ `runtime` on attested computations, `status`/date shapes, legacy `timestamp`);
+ `--check-links` resolves intra-bundle link targets. Both go beyond conformance —
+ their findings are reasons to improve a bundle you own, never to reject one you
+ are merely reading.
+
+ ## Consuming a bundle
+
+ Treat it as curated, high-signal context that beats grepping:
+
+ 1. Read the bundle-root `index.md` first — it maps the territory cheaply.
+ 2. Open only the concepts the task touches, then follow their links.
+ 3. Weigh before relying: `status: deprecated` or `today >= stale_after` means
+ verify against the real system before acting; an unverified, agent-generated
+ concept is a lead, a human-reviewed one is a fact.
+ 4. Read `log.md` when recency or "what changed" matters.
+
+ ## Authoring and maintaining
+
+ 1. Pick a stable concept ID (its path); group related concepts into
+ subdirectories with their own `index.md`.
+ 2. Write frontmatter: always `type`; add `title`/`description` for anything
+ others read; set `generated: { by, at }` with the correct actor — use
+ `human:<id>` only for genuinely human-authored content.
+ 3. Write a structured body; link related concepts with `/`-absolute paths so
+ links survive moves. Cite claims with footnotes keyed to `sources[].id`.
+ 4. Keep `index.md` (when the concept set changes) and `log.md` (a dated entry)
+ current in the same change.
+
+ When a repo asks yolop to keep its bundle current, update the affected concepts
+ after any change to durable facts, refresh `generated.at`, and record it in
+ `log.md`. Write down only durable, reusable knowledge — architecture, contracts,
+ invariants, processes — never transient task notes. A bundle that rots into
+ stale docs is worse than none.
+
## Converting into OKF
From a wiki, Notion export, Obsidian vault, or CSV: one source page/row → one
- concept file; choose a `type`; carry titles/descriptions into frontmatter;
- rewrite internal links as `/`-absolute concept links; add an `index.md`.
+ concept file; pick a descriptive `type`; carry titles and summaries into
+ `title`/`description`; rewrite internal links as `/`-absolute concept links;
+ record where each concept came from in `sources` and stamp `generated`; add an
+ `index.md`. Migrating a v0.1 bundle: `timestamp` → `generated: { by, at }`, and
+ a body `# Citations` list → frontmatter `sources`. Everything else carries over
+ unchanged.