okf

name

okf

description

Create, maintain, validate, and consume Open Knowledge Format (OKF) bundles — vendor-neutral knowledge directories made of plain markdown files with YAML frontmatter. Use when the user wants to capture a project's datasets, schemas, APIs, architecture, domain concepts, or playbooks as a durable OKF bundle; add or update OKF concept documents; build or refresh index.md / log.md; validate a bundle for conformance; or read an existing OKF bundle to inform work. Triggers on "OKF", "open knowledge format", "knowledge bundle", "knowledge catalog".

Open Knowledge Format (OKF)

OKF is a universal, vendor-neutral format for representing knowledge as plain markdown files with YAML frontmatter, organized into directory "bundles". No SDK, database, or query language is required to produce or consume it — anything that can read markdown can read OKF, and bundles live naturally in git for versioning, review, and collaborative curation. This skill lets you turn what a project knows (its data, interfaces, and domain) into a durable knowledge layer that both humans and agents can consume.

This file is the operating guide. The exact normative rules live in reference/spec.md — read it before producing or editing a bundle, and load the ready-made templates/ rather than writing structure from memory.

When to use this skill

• Produce: "Document this dataset / API / service as an OKF bundle", "capture our domain concepts as knowledge", "start a knowledge catalog for this repo".
• Maintain: add a concept doc, update a schema, refresh index.md, append to log.md, reorganize a bundle.
• Validate: check a directory conforms to OKF v0.1.
• Consume: read an existing OKF bundle and use it to answer questions, write queries, or guide a change.

The mental model (read this first)

A bundle is just a directory tree of .md files. Two ideas carry the format:

1. Hybrid documents — each concept is one .md file: queryable YAML frontmatter on top, free-form markdown prose below (schemas, examples, SQL).
2. Untyped link graph — concepts reference each other with ordinary markdown links. The meaning of a link (joins-with, depends-on, parent/child) lives in the surrounding prose, not the link. Consumers build a directed graph; broken links are tolerated (they may point at not-yet-written knowledge).

Two filenames are reserved: index.md (a directory listing for navigation) and log.md (a chronological changelog). Everything else .md is a concept.

The hard rules (must follow — full detail in reference/spec.md)

• Every non-reserved .md file MUST open with a parseable YAML frontmatter block delimited by ---, and that block MUST contain a non-empty type field. type is a free string (e.g. BigQuery Table, API Endpoint, Playbook, Reference) — not a fixed enum.
• index.md and log.md carry no frontmatter — with one exception: the bundle-root index.md MAY declare okf_version: "0.1" in frontmatter.
• Prefer bundle-relative links that start with / (e.g. [customers](/tables/customers.md)) — they survive file moves. Relative links (./other.md) are also valid.
• Never reject or drop unknown frontmatter keys, unknown type values, missing optional fields, broken links, or missing index.md. Preserve unknown keys on round-trip.

Recommended frontmatter (priority order)

type (required) → title → description (one sentence, used for previews and index entries) → resource (a URI uniquely identifying the underlying asset; omit for abstract concepts) → tags (YAML list) → timestamp (ISO 8601). Add any extra producer-specific keys freely.

Workflows

Produce a new bundle

1. Decide the root. Default to knowledge/ (or okf/) at the repo root, or a path the user names. Ask only if ambiguous.
2. Inventory the knowledge. Identify the concepts worth capturing — tables, datasets, endpoints, services, metrics, joins, playbooks, glossary terms — and group them into subdirectories by kind (e.g. tables/, datasets/, references/metrics/, references/joins/). Mirror the project's real structure; don't invent taxonomy.
3. Write concept docs from templates/concept.md. One concept per file, with a precise one-sentence description. Use conventional body headings where they fit: # Schema, # Examples, # Citations. Cross-link related concepts and describe the relationship in prose.
4. Write index.md at every directory level from templates/index.md — grouped link lists whose descriptions match each concept's description. Put okf_version: "0.1" frontmatter only on the root index.md.
5. Start log.md at the root from templates/log.md with an **Initialization** entry (use the real current date, ISO YYYY-MM-DD).
6. Validate (see below) and report the tree to the user.

Add or update a concept

• Create/edit the concept file; keep description and timestamp accurate (update timestamp on meaningful change).
• Update the enclosing index.md entry to match.
• Prepend a dated entry to the nearest log.md (**Creation**, **Update**, or **Deprecation**).
• Re-validate.

Validate a bundle

Run the bundled checker (pure Python stdlib, no install needed). Try python, then py, then python3 — on Windows the bare python may be a Store stub:

python <skill_dir>/scripts/validate_okf.py <bundle_root>
# or:  py <skill_dir>/scripts/validate_okf.py <bundle_root>

Add --strict to also fail on warnings. It reports errors for true conformance failures (missing/empty type, unparseable or wrongly-placed frontmatter) and warnings for advisories (broken intra-bundle links, missing index.md, missing recommended fields). Broken links are warnings, never errors — that's intentional per spec.

If no Python is available, validate by inspection instead: confirm each non-reserved .md opens with a closed --- frontmatter block containing a non-empty type; that index.md/log.md carry no frontmatter (except a root index.md with only okf_version); and flag broken intra-bundle links as advisories. The rules are in reference/spec.md §9.

Consume an existing bundle

Start at the root index.md, descend through directory index.md files (progressive disclosure), then read individual concepts. Treat frontmatter as the queryable layer (filter by type/tags/resource) and the body as the detail. Follow cross-links to build context; tolerate broken ones.

Notes

• Bundles are portable: a git repo (recommended), a tarball/zip, or a subdirectory of a larger repo are all valid distributions. Existing markdown tools (Obsidian, MkDocs, Notion) can render them as-is.
• This skill is provider-neutral, but when you generate the prose, write precisely and cite sources under # Citations so the knowledge stays trustable.