/okf

name: okf
description: >-
  Author, maintain, and consume Open Knowledge Format (OKF) knowledge bundles —
  portable markdown + YAML frontmatter that both humans and agents read. Use when
  capturing project knowledge (services, APIs, schemas, metrics, runbooks,
  decisions) into an OKF bundle, when updating one after code or docs change, or
  when a repository contains an `.okf/` (or other OKF) bundle that should inform
  the task. Triggers on: "document this in OKF", "update the knowledge bundle",
  "capture this as a concept", or any work in a repo that has an OKF bundle.
user-invocable: true
argument-hint: "[produce|maintain|consume] [path]"
allowed-tools: Read Write Edit Grep Glob Bash

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](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, plus `recursive: true` (or a depth `n`: levels below the root, `true` is 6) to make the hook watch nested git repos) and `log.md` (ISO-dated history, newest first). Never use these names for concepts.

• **What goes in `log.md`:** lifecycle events only, written in the bundle-root

`log.md`: a bundle **created**, a concept **deprecated** or retired, one concept **superseding** another, concepts **regenerated** after their source changed, a **verification** pass. Routine edits to a concept do not get an entry: its `generated` and git already record them. A log is append-only, so never rewrite or drop an existing entry.

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`, an absolute ISO 8601 datetime (a bare date is tolerated), 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.

**Reading a v0.1 bundle?** Two constructs were superseded (§13.1): `timestamp` is now `generated.at`, and a body `# Citations` list is now `sources`. Read both, write v0.2 — and when you touch a legacy concept in **maintain** mode, migrate its frontmatter as part of the edit. The validator warns on both.

Templates to copy: [concept](templates/concept.md), [index](templates/index.md), [log](templates/log.md).

Default bundle location

Use `.okf/` at the repository root unless the project already uses another location. Commit it alongside the code it describes — knowledge as code.

Modes

produce — create or extend a bundle

**Starting a brand-new bundle?** Use the init fast-path instead of hand-writing the first files — it scaffolds a conformant `index.md`, `log.md`, and a `getting-started.md` concept with full recommended frontmatter in one shot:

uv run "${CLAUDE_SKILL_DIR}/scripts/okf_init.py" <target-dir> [--title "..."]

It refuses to touch a directory that already has `.md` files unless `--force` is given. Then extend it:

1. Read [reference/SPEC.md](reference/SPEC.md). 2. Pick the source(s): **code** (derive concepts from source, READMEs, docstrings, config), **docs/wiki** (distill pages into concepts, record the originals in `sources`), **manual** (decisions, playbooks, metrics). 3. Choose a directory layout by domain (e.g. `services/`