0xDarkMatter/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.

Read the histogram, not just the %. A repo at "0% readiness" with rich consistent keys (e.g. every file has title/level/tags) is a cheap migration — you derive type from an existing key. A repo at "0%" with mostly empty frontmatter is expensive. To find candidates across many repos, run assess on each and compare.

2. Decide — adopt only where the squeeze is worth the juice

• Frontmatter-consistent repo → adopt: derive type, fix any malformed files, done.
• Mixed prose + frontmatter repo → usually skip, or adopt a subset (designate only the real concept docs; OKF has no built-in prose exemption — that's a known rigidity).

3. Validate — does a bundle conform?

python scripts/check-okf.py ./bundle                  # exit 0 conformant, 10 if not
python scripts/check-okf.py --json ./bundle | jq '.data[] | select(.severity=="error")'
python scripts/check-okf.py --strict ./bundle         # soft warnings also fail

Enforces only the hard rules (every non-reserved .md has parseable frontmatter with a non-empty type; reserved files get light sanity). Per OKF's permissive-consumption rule, broken links and missing optional fields are INFO, never failures (unless --strict). Wire check-okf.py --strict as a CI gate (exit 10 fails the build) once a repo has adopted OKF.

Tools

Both scripts follow the Skill Resource Protocol: stdout is data-only (--json emits a {"data":…,"meta":{"schema":…}} envelope), framing/progress to stderr, --help with examples, semantic exit codes. Stdlib-only; PyYAML used if present, else a built-in frontmatter parser (announced on stderr).

| Script | Role | Exit codes | |--------|------|-----------| | scripts/assess-okf.py | Read-only readiness scan of a doc tree | 0 scanned, 2 usage, 3 not-found | | scripts/check-okf.py | Conformance validator for a bundle | 0 conformant, 10 non-conformant, 4 unparseable frontmatter, 3 not-found, 2 usage |

See also

• references/okf-spec.md — the format: frontmatter fields, reserved files, conformance rules, permissive-consumption, versioning.
• assets/concept-template.md — copy-ready OKF concept doc.