git:20260616.8349e57 to git:20260708.e0b865f

1 added, 2 removed. Audit A to A.

---

name: okf-ops

- description: "Assess, validate, and adopt the Open Knowledge Format (OKF) across markdown+frontmatter knowledge bases. Use to scan a doc repo for OKF-readiness (how frontmatter-consistent it already is), validate a bundle for conformance, find good OKF-adoption candidates among many repos, or migrate a frontmatter-heavy repo onto OKF. Triggers on: OKF, open knowledge format, knowledge bundle, knowledge base format, assess docs, doc repo readiness, frontmatter conformance, validate frontmatter, type frontmatter, markdown knowledge base, adopt OKF, is this repo OKF-ready, index.md log.md."

- when_to_use: "Use when deciding whether/how to adopt OKF in a repo, scanning one or many doc trees for frontmatter consistency, or validating an OKF bundle — e.g. 'how OKF-ready is this repo', 'check this bundle conforms', 'which of my repos are good OKF candidates', 'validate the frontmatter in docs/'."

+ description: "Assess, validate, and adopt the Open Knowledge Format (OKF) across markdown+frontmatter knowledge bases. Triggers on: OKF, open knowledge format, knowledge bundle, frontmatter conformance, validate frontmatter, markdown knowledge base, adopt OKF, is this repo OKF-ready, index.md log.md."

license: MIT

compatibility: "Python 3.8+. PyYAML used if present; falls back to a built-in parser otherwise."

allowed-tools: "Read Bash Glob Grep"

metadata:

author: claude-mods

related-skills: "adr-ops, doc-scanner"

---

# 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?

```bash

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?

```bash

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.