okf-ops

OKF Ops

The Open Knowledge Format (OKF) is a minimal, open convention for representing knowledge as a directory tree of markdown files with YAML frontmatter — the metadata and curated context that surrounds data and systems. This skill helps you assess whether a repo is a good fit, validate a bundle for conformance, and adopt OKF where it earns its keep.

Full format rules: references/okf-spec.md. Copy-ready concept doc: assets/concept-template.md.

Honest scope (read this before adopting)

OKF is a v0.1 draft (Google-published, platform-agnostic). It's deliberately minimal: one required frontmatter field (type), reserved index.md/log.md, and a permissive-consumption contract. Two consequences worth knowing up front:

• Adoption cost is shaped by the repo, not the size. A repo that already uses frontmatter consistently is often one mechanical type-derivation pass from conformant. A repo of bare prose markdown needs frontmatter authored on every file — often not worth it, and arguably the wrong files to make "concepts."
• Conformance is a weak guarantee. "OKF-conformant" means the structural floor is met, not that the content is good. Use the assessment to decide adoption per-repo; don't make it a blanket mandate.

The tools here are useful regardless of OKF's trajectory — assess-okf.py is a general "how frontmatter-consistent is this doc tree?" scanner.

Workflow: assess → decide → validate

1. Assess (read-only) — is this repo a good candidate?

python scripts/assess-okf.py docs/                    # human summary
python scripts/assess-okf.py --json docs/ | jq '.data.readiness_pct'

Reports total .md, how many already carry frontmatter, how many have a non-empty type, a histogram of existing frontmatter keys (shows what vocabulary you already have to derive type from), type-value distribution, reserved files present, files that would need a type, and an overall readiness %. Never writes.