okf

name

okf

description

Create, inspect, author, revise, enrich, audit, repair, research, migrate, validate, and maintain knowledge for AI agents as conformant Open Knowledge Format (OKF) bundles. Use for /okf commands; work on an existing OKF bundle; documentation of tables, datasets, views, metrics, runbooks, playbooks, APIs, schemas, or join paths; exports from catalogs, metadata, websites, URLs, or source code; and any knowledge an agent will read later. Apply implicitly when editing an OKF bundle so conformance, timestamps, log.md, indexes, citations, and cross-links remain current.

Open Knowledge Format (OKF)

OKF is Google's open, vendor-neutral spec (v0.1) for the context an AI agent needs, represented as a bundle. A bundle is a directory of markdown files, each a concept (a table, dataset, metric, runbook, playbook, API, join path), kept in version control next to the code it describes. Just markdown, just files, just YAML frontmatter. The format is the contract, so any producer can write a bundle and any consumer (an agent, a viewer, a search index) can read it with no SDK and no lock-in.

Use this skill two ways. Run a command on demand, or apply it implicitly whenever you shape knowledge an agent will read. The deep normative spec lives in spec.md; per-command steps in commands.md; copy-paste starting points in templates.md.

Choose the OKF method

For every OKF request, select the narrowest method that fits the user's intended outcome. In OKF Studio generic chat, call okf_capability_catalog to inspect the active versioned catalog and okf_capability_resource to load the selected method. Outside Studio, read the matching capability file directly. State the selected capability in the first progress update. Do not claim to have used a method until its resource was loaded.

User intent	Method to load
Answer a bounded bundle question or trace known links	okf-inspect
Select evidence, inspect the route, or diagnose a retrieval miss	okf-retrieve
Plan a new bundle whose destination or concept map is unresolved	okf-create
Add facts, citations, or relationships to existing knowledge	okf-enrich
Review conformance or knowledge health without changing files	okf-audit
Fix a reproducible validation or health defect	okf-repair
Reconcile bundle claims with bounded external evidence	okf-research
Find direct and downstream effects before a change	okf-change-impact
Plan a versioned schema, convention, layout, or identity change	okf-migrate
Turn accepted evidence and known destinations into new concepts	okf-author, then writing
Improve existing prose without changing meaning	okf-revise, then writing

All methods stay discoverable, but their detailed instructions are loaded on demand. Loading every method at once wastes context and combines incompatible boundaries. For example, inspect is read-only, revise forbids knowledge changes, enrich permits sourced additions, and repair requires a reproducible defect. If one request spans several phases, run the methods in order and preserve each method's stop conditions and artifact contract.

The one rule

A bundle is conformant when every concept document carries YAML frontmatter with a non-empty type field. That is the only hard requirement. Everything else is recommended structure whose absence a consumer must tolerate. Hold this line and a bundle anyone produced stays readable by anyone's agent. The full conformance criteria and the consumer's tolerance contract are in spec.md.

Commands

Invoke as /okf <command> [target]. Each is detailed in commands.md.

Command	What it does
init	Create a bundle. Make the directory, a root index.md declaring okf_version, and the first concept folders.
add	Write one concept document. Pick a descriptive type, fill the recommended frontmatter, body it with # Schema, # Examples, # Citations.
enrich	Turn a source (a BigQuery dataset, an OpenAPI spec, a wiki, a website, docstrings) into concepts by first enumerating its full surface into an inventory, then a pass that crawls authoritative docs to add schemas, join paths, and citations, then an entity pass that gives every load-bearing name the source mentions but never explains its own linked concept.
link	Connect concepts with bundle-absolute markdown links and name the relationship in the surrounding prose.
index	Generate or refresh index.md listings so an agent can navigate by progressive disclosure.
log	Append a dated log.md entry (Creation, Update, Deprecation), newest first.
validate	Run the conformance check. node okf-validate.mjs <bundle>, or the manual checklist in commands.md.
retrieve	Select coherent evidence for a question and retain route, omission, provider, fingerprint, and abstention decisions.
export	Convert an existing source into a conformant bundle: a catalog, a metadata dump, a schema export, a docs site, or a website or external URL (/okf export <url>). Map the whole surface, cover every section, give every named entity its own concept, then pass the creation gate — not a snapshot of the front page. The producer role.
consume	Read a bundle to answer a question. Start at index.md, follow links, tolerate anything missing.

Implicit mode

Apply OKF without being asked whenever knowledge is being shaped for an agent to read later:

• You are documenting a data asset (table, view, dataset, metric, dimension) or a process (runbook, playbook, incident guide) an agent will consult. Write it as a concept with a type, not loose prose.
• You are exporting or transforming metadata, a catalog, schemas, or docstrings for agent consumption. Emit a bundle, not a JSON blob or a wiki dump.
• You write a deprecation notice, a join path, or a business-meaning definition an agent needs. That is a concept. Give it a file and a type.
• You are editing an existing OKF bundle. Keep it conformant as you go: refresh the concept's timestamp, append a log.md entry, regenerate the affected index.md, and add a link whenever you create a relationship. This is the "knowledge is touched and transformed" case, and it is where bundles silently rot if you skip the bookkeeping.

Guard. OKF is for knowledge an agent reads, not human-only prose. A README, a blog post, or a design doc for people is not a bundle. When it is unclear whether an artifact is agent-facing, ask before converting it.

Concept document at a glance

A concept is frontmatter plus a markdown body. Its identity is its path with the .md removed, so tables/orders.md is the concept tables/orders.

• Frontmatter. type is required. Recommended, in priority order: title, description (one sentence), resource (canonical URI for the underlying asset), tags (a YAML list), timestamp (ISO 8601). Producers may add any other keys, and consumers preserve unknown keys rather than rejecting them.
• Body. Favor structural markdown (headings, lists, tables, fenced code) over freeform prose. Conventional headings, used when they apply, are # Schema, # Examples, # Citations. For each fact, pick the sharpest form the extended set offers (next section).
• Reserved filenames, never a concept. index.md is a directory listing and carries no frontmatter, except the bundle-root index.md, which may declare okf_version. log.md is a dated change history.
• Links. Prefer bundle-absolute links like /tables/customers.md (stable when files move). Relative links such as tables/customers.md are also valid. A link asserts a relationship whose meaning lives in the surrounding prose, not in the link.
• External material. A webpage or doc you pull in becomes an ordinary concept under references/<slug>.md with type: Reference and its URL in resource. Absorb its content, not just its URL: extract the substance into the body so the concept stands alone offline — resource is provenance for re-checking, not a replacement for the knowledge. A summary that defers to the live link is a stub (see /okf export).

Pick the sharpest markdown form

"Favor structural markdown" extends past headings and tables. For a fact with inherent structure, the extended-markdown form is both more machine-readable than prose (an agent parses an edge list or a formula, not a paragraph about one) and renders richly where bundles are actually read (GitHub, OKF viewers). Where a consumer renders none of it, the source still reads as plain markdown, so there is no portability cost.

The fact	Write it as	Not as
Topology: joins, lineage, pipeline flow, states	A ```mermaid fence (erDiagram, flowchart, sequenceDiagram); the edges are the data	A prose paragraph describing arrows
A formal definition: metric formula, threshold, window	TeX, $…$ inline or $$…$$ display	Pseudo-math in prose ("count divided by the window")
Term meanings: a glossary, enum values, status codes	A definition list (Term then : definition)	Bullets shaped like "X - means Y"
A checklist with state: rollout or migration progress	A task list (- [x] / - [ ])	Prose like "steps 1 to 3 are done"
A caveat or provenance note too small for # Citations	A footnote ([^1])	A parenthetical that derails the sentence
Field-by-field facts: schemas, parameters	A markdown table (already the convention)	Key-value prose

Keep prose for meaning and reasoning; reach for these forms when the fact has shape. The worked examples in templates.md show each in place.

Validate

Run the bundled checker against a bundle directory:

node okf-validate.mjs path/to/bundle

It errors (exit 1) on the hard requirement (a concept missing frontmatter or a non-empty type) and warns on soft guidance without failing the bundle, because consumers tolerate those. Among the warnings it reports the bundle's graph connectivity — orphans (a concept with no concept-to-concept link in or out) and broken concept links (a link whose target is not a concept, including a link into a reserved index.md). Pass --strict to turn those into failures: that is the producer gate, because an agent traversing the bundle cannot reach an orphan or cross a broken link, so either is missing context by construction. The reviewer's checklist behind the script is in commands.md.

Validation checks conformance, not coverage. A thin stub of a fifty-page site passes it clean, because the one rule is about each file's type, not about whether the bundle captured the source. When you produce a bundle from a source (export, enrich), the default run is necessary but not sufficient — run okf-validate --strict and the creation gate in commands.md: every discovered section covered, concepts with real depth, every load-bearing name decomposed into its own linked concept (a bundle stops where the gate says, not where the source's own explanations ran out), a connected graph with no orphans or broken links, and any crawl boundary recorded in log.md. Passing the default okf-validate is not the same as finishing the export.

Files in this skill

• spec.md. The full OKF v0.1 normative reference (conformance, fields, linking, versioning, non-goals, design principles).
• commands.md. Each command end to end, with the files it touches and the validate checklist.
• templates.md. Concept, root index.md, sub index.md, and log.md templates, plus worked BigQuery table, metric, runbook, and external-reference examples.
• writing.md. The shared reader-job, prose, structure, revision, and fact-preservation contract for authoring and revision.
• capabilities/. The narrow inspect, retrieve, create, enrich, audit, repair, research, change-impact, migrate, author, and revise methods selected by the router above.
• okf-validate.mjs. The zero-dependency conformance checker.

Source

The Open Knowledge Format is published by Google Cloud. Spec: GoogleCloudPlatform/knowledge-catalog. Announcement: How the Open Knowledge Format can improve data sharing. The same repo ships a reference producer (an enrichment agent), a single-file HTML visualizer as a reference consumer, and three browsable sample bundles (GA4, Stack Overflow, Bitcoin); spec.md points to each. OKF v0.1 is an early, intentionally minimal standard designed for backward-compatible growth, so re-check the spec for fields added after this snapshot.