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](references/okf-spec.md). Copy-ready concept doc: [assets/concept-template.md](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](references/okf-spec.md) — the format: frontmatter fields,

reserved files, conformance rules, permissive-consumption, versioning.

• [assets/concept-template.md](assets/concept-template.md) — copy-ready OKF concept doc.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: 0xDarkMatter
• Source: 0xDarkMatter/claude-mods
• License: MIT
• Homepage: https://github.com/0xDarkMatter/claude-mods#readme

Install and usage instructions live in the source repository linked above.