okf — author and validate Open Knowledge Format bundles

What OKF is

Open Knowledge Format (OKF) is a vendor-neutral format for representing knowledge as plain markdown files with YAML frontmatter, organized in a directory hierarchy. It is not tied to any agent, framework, model provider, or serving system. A bundle is just a directory: version-controllable, portable, lock-in free, readable by humans and LLMs alike, and consumable by anything that reads markdown (Obsidian, Notion, MkDocs, a static file server, a search index, a graph viewer).

Read reference/SPEC.md first — it is the full OKF v0.1 spec, bundled so you can ground every decision in it without network access. When the spec and this skill disagree, the spec wins.

When to use

Initialize a new, empty OKF bundle with the correct layout.
Author or edit OKF concept documents (one concept per .md file).
Generate or refresh index.md (progressive disclosure) and log.md (history).
Validate an existing bundle for OKF v0.1 conformance.
Render a bundle as a self-contained, interactive graph viewer (viz.html).

To convert an existing pile of notes / a catalog export into an OKF bundle, use the companion okf-refactor skill instead.

The non-negotiable rules (from the spec)

Every non-reserved .md file MUST have parseable YAML frontmatter.
Every frontmatter block MUST include a non-empty type.
Reserved filenames — index.md, log.md — follow their special structure and carry NO frontmatter (the sole exception: the bundle-root index.md may carry okf_version).
Cross-links are normal markdown links; prefer absolute bundle-relative paths (/tables/orders.md) over relative ones so links survive file moves.
Be a disciplined producer: emit title, description, and (for assets) resource even though only type is strictly required — consumers index on them.

Initialize a new bundle

When asked to init/scaffold an OKF bundle at <path>:

Confirm <path> (ask if not given). Create the root directory.
Decide the top-level grouping from the domain — directories ARE the coarse taxonomy (e.g. datasets/, tables/, references/, or concepts/, playbooks/, …). Don't over-structure; start flat, nest only when a level earns it.

Write a bundle-root index.md that declares the version and links the groups:

---
okf_version: "0.1"
---

# <Bundle name>

- [Datasets](datasets/) - <group description>
- [Tables](tables/) - <group description>

Add a references/ directory only if you expect standalone citation docs.
Optionally seed a root log.md with an ## <YYYY-MM-DD> / * **Initialization** entry. Use the real current date.

Author a concept document

One concept per file, <group>/<slug>.md. Slug is kebab-case, stable, matches the asset name where possible.

---
type: <Type name> # REQUIRED — e.g. "BigQuery Table", "API Endpoint", "Playbook"
title: <Display name> # strongly recommended
description: <one-line summary> # strongly recommended — used in indexes/previews
resource: <canonical URI> # for assets that have one
tags: [<tag>, <tag>] # optional, cross-cutting
timestamp: <ISO 8601> # optional, last meaningful change
---

# Schema (when the concept has structured fields — prefer a table)

| Column | Type | Description                    |
| ------ | ---- | ------------------------------ |
| ...    | ...  | FK to [other](/group/other.md) |

# Examples (concrete usage in code blocks)

# Citations (external sources)

[1] [Title](https://example.com)

Guidance:

Prefer structural markdown (tables, lists, code blocks) over prose paragraphs.
Express relationships by linking related concepts inline in the prose; the link is an undirected edge in the knowledge graph.
Add producer-specific frontmatter keys freely — consumers preserve unknowns.

Generate / refresh `index.md`

For any directory worth navigating, write an index.md with NO frontmatter (except the root, which keeps okf_version). Group concepts under # sections; pull each bullet's description from the linked concept's description:

# Tables

- [Orders](orders.md) - one row per completed customer order
- [Customers](customers.md) - one row per customer

Use relative links inside an index (they sit beside their targets). Regenerate the index whenever concepts are added, removed, or re-described.

Maintain `log.md`

Append directory-level history, newest first, ISO dates:

# Directory Update Log

## 2026-06-14

- **Creation**: Added orders and customers tables.

Render a graph viewer

scripts/render_okf_viewer.py turns any bundle into a self-contained HTML graph viewer (cytoscape + marked, loaded from CDN, no build step) plus fresh index.md files at every level — the interactive counterpart to the flat listings in "Generate / refresh index.md" above.

python3 ${CLAUDE_PLUGIN_ROOT}/skills/okf/scripts/render_okf_viewer.py ./bundles/my_bundle
python3 ${CLAUDE_PLUGIN_ROOT}/skills/okf/scripts/render_okf_viewer.py ./bundles/my_bundle \
  --title "My Catalog" --out ./bundles/my_bundle/viz.html

(Outside a plugin runtime, the script lives next to this SKILL.md under scripts/.)

It draws one edge per link it finds, from any of three sources — a bundle written with only one of these still renders correctly:

related: ["[[slug]]", "other-slug"] frontmatter
[[slug]] wikilinks in the body
[text](path/to/concept.md) markdown links — bundle-relative absolute (/tables/orders.md) or relative to the linking file

Node color is assigned per type in first-seen order from a fixed palette, so any bundle's custom types get stable, distinct colors — nothing to configure. Regenerate after adding, removing, or re-linking concepts; it's idempotent.

Validate a bundle for OKF v0.1 conformance

Run scripts/validate_okf.py <bundle> (bundled with this skill) for a mechanical check, then eyeball the report. It verifies:

Every non-reserved .md has parseable frontmatter with a non-empty type.
index.md / log.md carry no frontmatter (root index.md may carry only okf_version).
Reports broken bundle-relative cross-links as warnings (broken links are tolerated by the spec — surface them, don't fail on them).

python3 ${CLAUDE_PLUGIN_ROOT}/skills/okf/scripts/validate_okf.py ./bundles/my_bundle