okf

Open Knowledge Format (OKF) skill

OKF represents knowledge as a directory of markdown files with YAML frontmatter. It is minimal by design: no schema registry, no runtime, no SDK. Your job is to produce, maintain, and consume OKF bundles conformant with the spec, not your memory of it.

Always read the canonical spec before non-trivial work: reference/SPEC.md. It is the verbatim OKF v0.2 specification and the source of truth for every rule below.

The one hard rule

A bundle is conformant (§11) iff: every non-reserved .md file has a parseable YAML frontmatter block, and every such block has a non-empty type field. Everything else is soft guidance. Consumers MUST tolerate missing optional fields, unknown types, and broken links — never reject a bundle over them.

Conventions to apply

• One concept = one file. The file path (minus .md) is the concept ID.
• Frontmatter: type is required. Add title, description, tags when they aid consumption; add resource (a canonical URI) only for concepts bound to a real asset — omit it for abstract concepts.
• Body: prefer structural markdown (headings, tables, lists, fenced code). Conventional headings: # Schema, # Examples, # Computation.
• Cross-links: standard markdown links; prefer absolute bundle-relative form (/services/auth-api.md). A link asserts a relationship; its kind lives in the surrounding prose, not the link.
• Reserved files: index.md (directory listing, no frontmatter, except the bundle-root index, which may carry okf_version and this plugin's upkeep: enforced opt-in flag) and log.md (ISO-dated change history, newest first). Never use these names for concepts.

The v0.2 families (all optional, all worth filling)

• Trust (§5.2): generated: { by, at } — who produced the current content and when. verified: [{ by, at }] — who confirmed it since (a bare mapping is one entry). Write by in the actor convention (§7): <producer>/<version> for an agent, human:<id> for a person, process:<id> for an automated job. Use human: whenever a person authored or signed off — consumers key trust tiers off that prefix.
• Lifecycle (§5.4–5.5): status: draft|stable|deprecated (absent means stable) and stale_after: YYYY-MM-DD, an absolute date, not a TTL.
• Provenance (§5.1): sources: [{ id, resource, title, author, usage_count, last_modified }] plus a usage_window: { from, to } sibling of sources framing every usage_count (an entry may carry its own to override it); a usage_count without a window warns. resource is required per entry and may be a URL, a bundle path, or a scope descriptor. Attribute a specific claim with a markdown footnote whose label is the source's id: …sharded daily.[^ga4-schema] plus a [^ga4-schema]: … definition. The label is the join key, it must match a sources[].id.
• Attestation (§10): a sanctioned computation is its own concept, type: Attested Computation, carrying runtime (required), parameters, executor, attester, and the computation itself under # Computation (or a computation: path). Concepts that need the value link to it. Never inline a number's SQL into the concept that narrates it.