Synthesis okf
Skill synthesisengineering/synthesis-skills/skills/synthesis-okf
Validate, convert, and author content for Google's Open Knowledge Format (OKF v0.1) — the markdown-plus-YAML-frontmatter knowledge-bundle spec announced 2026-06-12. Includes a conformance validator (the checker Google's own OKF repo ships none of), a converter that backfills OKF frontmatter onto an existing markdown corpus idempotently, a config-driven seven-point metadata-consistency checker, and the proven repo-by-repo conversion procedure. Use when adopting OKF for an "LLM wiki" style knowledge base, auditing conformance, checking frontmatter/body drift or taxonomy consistency, or converting a corpus of markdown notes/docs into a conformant, agent-readable bundle.From its SKILL.md
npx -y skills add synthesisengineering/synthesis-skills --skill synthesis-okfAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 23 stars23 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its file declares
Copied from the file, not written here
The file declares its own license as CC0-1.0. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.
SKILL.md
9.9 KB, as published. Nobody here has run it
synthesis-okf
Google's Open Knowledge Format (OKF v0.1, announced 2026-06-12) formalizes a pattern many
"LLM wiki" knowledge bases already use: a directory tree of markdown files with YAML
frontmatter, readable by any agent that can cat a file, shippable by anyone who can
git clone a repo. Per the spec's own §10, this is exactly the pattern OKF names as one
of its target use cases — the differentiator is only that it's now specified.
Google's reference repo (github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf)
ships an enrichment agent and an HTML visualizer, but no conformance validator or converter.
This skill fills that gap: a conformance validator, a converter, a house-consistency
checker, and a procedure proven across several real-world repo conversions.
The spec, in brief
A bundle is a directory (conventionally a repo's source/ directory, or the whole
repo for a dedicated knowledge repo). A concept is one markdown file: one unit of
knowledge. Conformance (§9) has exactly three hard rules:
- Every non-reserved
.mdfile has a parseable YAML frontmatter block. - Every frontmatter block has a non-empty
typefield. - Reserved filenames (
index.md,log.md) follow their defined structure when present.
Everything else — missing optional fields (title, description, tags, timestamp,
resource), unknown type values, broken cross-links, missing index.md — is soft
guidance. A validator or consumer must not reject a bundle for any of it. Full spec:
references/okf-spec-v0.1.md (verbatim, 451 lines).
index.md and log.md are the only two reserved filenames. index.md is a directory
listing for progressive disclosure and carries no frontmatter, except the bundle-root
index.md, which may declare okf_version: "0.1". log.md is a chronological change
history (## YYYY-MM-DD headings, newest first). Both are excluded from a bundle's own
"knowledge" content — they're navigation scaffolding, not concepts.
Tools
scripts/okf_validate.py — conformance checker
python3 scripts/okf_validate.py <bundle_dir> [--summary] [--check-links] [--quiet]
Checks the three hard rules against every .md file in the bundle. --summary prints a
concept/type breakdown; --check-links additionally reports broken relative links (as
info, never as a conformance failure — broken links are explicitly valid per §5.3).
Exit codes: 0 conformant, 1 errors found, 2 usage error.
scripts/okf_convert.py — idempotent frontmatter backfill
python3 scripts/okf_convert.py <bundle_dir> \
--type-map instructions=Instruction,runbooks=Runbook,datasets=Dataset,contexts=Context \
--descriptions <repo>-descriptions.yaml \
[--dry-run]
Backfills OKF frontmatter onto an existing markdown corpus without disturbing what's already there:
- Assigns
typeby top-level subdirectory per--type-map(free-form per spec §4.1 — name types after what they actually are; richer repos can add finer types likeBiography Timeline Entryor a repo-specificClienttype for aclients/directory). - Existing frontmatter fields are never overwritten, only backfilled where missing — safe to run against a corpus where some files already carry hand-authored metadata.
- Derives
titlefrom each file's H1 if absent,timestampfrom the file's last git-commit time if absent. - Renames in-bundle
README.mdfiles to the reservedindex.md(no frontmatter needed) and regenerates them in OKF §6 style: lead paragraph (preserved verbatim from the original README) + a concept list grouped by type + a subdirectories list. Walks every ancestor directory up to the bundle root, not just each concept file's direct parent, so a directory holding only subdirectories (no concept file directly inside it) still gets its ownindex.mdand its parent's link to it isn't left broken. - Sets
okf_version: "0.1"on the bundle-rootindex.mdonly, per spec. --dry-runprints what would change without writing anything. Always run this first.
--descriptions <file>.yaml supplies curated {description, tags} per concept relpath —
the one genuinely editorial step. Auto-extracting a good one-sentence description from a
file's body is unreliable (skill-stub runbooks in particular tend to be a title plus an
npx code fence with no real prose to extract from); curate this file by hand per bundle.
scripts/okf_consistency.py — configured house-consistency checker
python3 scripts/okf_consistency.py <repo_root> [<repo-relative-doc> ...] [--strict]
Reads .agents/knowledge-base.yaml and its configured taxonomy_path. With no
document arguments it checks the full configured bundle. It reports
file:line — SEVERITY — finding in this order:
- Inline metadata that duplicates frontmatter.
- Date aliases and inline dates that conflict with the configured
frontmatter.date_field. - Status/confidence and lifecycle/current-phase conflicts.
- Missing required fields, fields outside the house schema, malformed tags, and values absent from the taxonomy.
- Long resource-linked concepts without a canonical-source or synchronization note.
- Frontmatter title and H1 disagreement.
- Filename, date-in-name, and configured topic-routing placement problems.
Exit 1 when a CONFLICT or DUPLICATE exists; warnings are review findings
unless --strict is supplied. Exit 2 for a missing/invalid config or unsafe
path. The config's date field is the sole last-update key: if it declares
timestamp, an added last_updated is a conflict, not a tolerated alias.
The conversion procedure
Full step-by-step, proven across multiple real conversions (a public 26-doc repo, a 72-doc personal knowledge base, and several other repos of varying size): see references/conversion-procedure.md. Summary:
- Baseline — run the validator, expect non-conformant.
- Author descriptions — the editorial 20%. Write
<bundle>-descriptions.yaml. - Convert — dry-run first, review, then apply for real.
- Validate to clean — 0 errors, 0 warnings,
--check-linkstoo. - Check house consistency — when
.agents/knowledge-base.yamlexists, runokf_consistency.pyand resolve every conflict/duplicate. - Compiler config — if the bundle feeds a compilation pipeline, add
**/index.mdand**/log.mdto its exclude list (navigation scaffolding, not knowledge to compile). - Review the diff — confirm no README's unique guidance was lost in its
index.mdregeneration; spot-check descriptions. - Commit.
Known lessons from real conversions
- The converter needs to walk every ancestor directory, not just each file's direct
parent, when deciding what needs an
index.md. A purely-organizational directory (holding only subdirectories, no concept file of its own) is easy to miss and leaves a dangling link from its parent's generated index. Fixed in this skill's copy ofokf_convert.py— if you're comparing against an older copy, this is the diff to look for. - Space-containing filenames break generated links. CommonMark markdown link
destinations can't contain unescaped spaces; a runbook named
Podcast Transcript Enhancement.mdneeds a kebab-case rename (git mv, preserves history) before the converter's generated index links to it correctly. - Workspace-private / minimal-stub repos may have no
sources:/compilation:block at all in their compile config — if there's nothing for a compiler to walk, step 5 (theindex.md/log.mdexclude) has nothing to add to; that's a legitimate no-op, not a gap. - A bundle with zero markdown files is vacuously conformant. Don't treat an empty
source/tree as something needing conversion — there's nothing non-conformant about it. typevalues are genuinely free-form (spec §4.1, no central registry). Don't force a one-size-fits-all vocabulary across very different repos; a richer repo earns its own finer-grained types where the coarseInstruction/Runbook/Datasetsplit loses real distinctions worth keeping (e.g. a repo with substantial per-client content benefits from its ownClienttype rather than folding everything intoDataset).
Related skills
synthesis-context-lifecycle— the tiered CONTEXT.md/REFERENCE.md/sessions/ project-memory pattern this skill's own conversion procedure was tracked with; OKF is about the content corpus, not the project-management layer (which stays explicitly out of OKF's own bundle scope).synthesis-anti-shortcuts— dispatch/acceptance hygiene for running this conversion at scale (one sub-agent per repo).synthesis-kb-edit— config-driven editing and shipping; this skill owns its format and consistency gates.synthesis-knowledge-capture— durable fact extraction and in-place reconciliation before validation.