okf

name	okf
description	Conventions for working inside an OKF knowledge bundle (a directory of markdown files with YAML frontmatter, plus reserved index.md/log.md). Use whenever reading, editing, or creating files in or near an OKF bundle — to preserve source formatting, keep links OKF-conformant, maintain the log, and apply trust tiers. Auto-applies when an okf.json or a bundle index.md is present.
user-invocable	false
allowed-tools	Bash Read Edit

okfm: conventions

How to behave inside an OKF bundle so it stays healthy.

Engine invocation

These skills call the okfm engine through one CLI, written here as okf <command>. Resolve it for the current harness:

• Claude Code: python "${CLAUDE_PLUGIN_ROOT}/scripts" <command> <args> (the form used in the command skills).
• Any other harness / plain shell: okf <command> (the CLI on PATH) or python okf.pyz <command> or python /path/to/scripts <command>.

The <command> <args> part is identical everywhere; subcommands are new, add, convert, seed, move, check, map, find, scan. Porting a skill to another harness is just swapping that prefix.

Workflow

• Read before work: start from the relevant concept, follow links for context, treat notes as orientation, then verify against the live repo/state.
• Write back: when a durable decision changes, update the concept and add a log.md entry.

Source-preserving edits

• Never re-render a whole file. Change only the bytes that change. Keep manually aligned tables, ASCII diagrams, and whitespace pristine.
• Frontmatter edits preserve key order, indentation, inline comments, and unknown custom keys. Use okf_fmwrite (via the new/add/move commands) rather than hand-rewriting blocks.

Links

• Standard markdown links only — [text](/path.md) (absolute from bundle root) or relative. Avoid wikilinks: standard links stay OKF-conformant and parseable by check, and Obsidian reads them fine (a folder of markdown is already a valid Obsidian vault).
• Prefer absolute links (the default link_style); they survive move unchanged.
• A broken link means "knowledge not yet written" — surface it, never delete it.

Reserved files

• index.md is engine-owned: regenerate it with check --fix rather than hand-editing (your frontmatter title/description are the source of truth for each bullet).
• log.md is newest-first, ISO ## YYYY-MM-DD headings, bullets prefixed with a bold action (* **Update**: ...). Add an entry on any automated change.

Fields

• type is the only required key. Recommended: title, description, resource, tags, timestamp.
• resource is a URI uniquely identifying the underlying asset (a table, an endpoint, a document). It is the stable identity key for catalog-style concepts; omit it for abstract concepts.

Body sections (conventional)

• # Schema — structured field/column descriptions. # Examples — usage in code blocks. # Citations — numbered sources (absolute URLs, bundle-relative paths, or concepts under references/).
• convert writes a # Citations block automatically (the source file, or explicit --citation URLs). Agent-curated concepts with no citations are flagged no-citations by check — a nudge, not an error.
• references/ holds external-source concepts (type: Reference) that other concepts cite.

Trust tiers

• Machine-drafted concepts carry curated_by: agent. When a human reviews and verifies one, change it to curated_by: human so AI drafts never blend invisibly into verified knowledge.

Capture filter

• Capture only what is Relevant, Actionable, has Depth, and is Authoritative. Skip raw dumps, image-only notes, secrets, uncurated transcripts.

Forward-compatible keys (documented now; no view renders them yet)

• status (Backlog/Todo/In Progress/In Review/Done), priority, assignee, epic, and a # Dependencies section with Blocks / Blocked by bullets. Capturing these now means v3 views "just work" later.