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.