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 c

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: 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/ , datasets/ , decisions/ ). One concept per file. 4. Write each concept from [templates/concept.md](templates/concept.md): set a descriptive type , fill recommended fields, record generated and the sources you actually read, cross link related concepts. 5. Add/refresh index.md per directory (and okf version: "0.2" in the root index). A new bundle gets a dated Creation entry in log.md . Extending an existing one does not. 6. Validate (see below). Fix every error before finishing. maintain — keep a bundle in sync with reality 1. Identify which concepts the change affects (search by resource , path, or topic). This bookkeeping is exactly what agents are good at — touch every affected file in one pass. 2. Update the body and generated.at (with your own actor in generated.by ); fix or add cross links; create new concepts for new assets; mark removed assets status: deprecated and note the deprecation in log.md rather than silently deleting context. Facing a whole v0.1 bundle rather than a stray field? Do not hand edit it — run the validator's migrate once. 3. Update the relevant index.md files. Append a dated log.md entry only if the change is a lifecycle event (see What goes in log.md ). 4. Validate. consume — use a bundle as context 1. Read the bundle root index.md first for progressive disclosure, then follow links only into the concepts relevant to the task. 2. Weigh what you read: status: draft / deprecated , a stale after already past, or no verified entry all mean "check before relying on this". Treat broken links as not yet written knowledge, not errors. 3. Need a number an Attested Computation covers? Run its computation with values bound to the declared parameters — never write your own query. 4. If you learn something durable while working, switch to maintain and write it back. Validation (do this before declaring done) Never eyeball conformance — run the deterministic checker. Invoke the companion validate skill ( /okf:validate <bundle dir strict ), which ships the checker. If that skill is not installed, run it directly: Resolve every ERROR (hard §11 failures). Under strict warnings also fail the run (exit 1), so clear them too; drop strict (or use max warnings N ) if you only want §11 conformance gated.