okf-skill

Two Claude Code skills for working with the Open Knowledge Format (OKF) — a universal, vendor-neutral format for representing knowledge as plain markdown files with YAML frontmatter, organized into directory "bundles".

• okf — produce, maintain, validate, and consume OKF bundles: turn what a project knows (datasets, schemas, APIs, architecture, domain concepts, playbooks) into a durable, git-versioned knowledge layer that humans and agents can read.
• okf-ingest — bring existing material into OKF compliance: point it at a repo, docs set, or second brain (Obsidian/Logseq/Notion) and it analyzes the source, recommends whether to convert fully / partially / not at all, asks how you want to proceed, then implements your choice non-destructively.

No SDK, database, or query language required.

What's in here

okf/                       # SKILL 1 — the format authority
├── SKILL.md               # trigger + operating guide (mental model, rules, workflows)
├── reference/spec.md      # condensed normative OKF v0.1 spec (progressive disclosure)
├── templates/             # ready-made concept.md / index.md / log.md scaffolds
└── scripts/validate_okf.py # stdlib-only OKF v0.1 conformance checker

okf-ingest/                # SKILL 2 — convert existing sources into OKF
├── SKILL.md               # analyze → summarize → recommend → ask → implement
├── reference/decision-framework.md  # the full / partial / none rubric
├── reference/source-adapters.md     # detection + conversion recipes per source type
└── scripts/analyze_source.py        # stdlib source inventory / type detector

example-bundle/            # a tiny, conformant demo bundle (e-commerce shop)
osha-standards/            # a larger real-world bundle: a catalog of all OSHA 29 CFR standards Parts
okf-skill-knowledge/       # a derived bundle: okf-ingest run on THIS repo (knowledge about itself)

Install

Copy whichever skill directories you want into your Claude Code skills folder:

• Personal (all projects): ~/.claude/skills/<skill>/
  • Windows: C:\Users\<you>\.claude\skills\<skill>\
• Project-local (this repo only): <repo>/.claude/skills/<skill>/

# personal install of both skills
git clone https://github.com/<you>/okf-skill
cp -r okf-skill/okf         ~/.claude/skills/okf
cp -r okf-skill/okf-ingest  ~/.claude/skills/okf-ingest

okf-ingest defers to okf for the spec, templates, and validator, so install both for the full ingest experience. Then run /reload-skills (or restart). The skills trigger on phrases like "OKF", "knowledge bundle", or "convert this to OKF".

Usage

In any project, ask Claude Code things like:

• "Use the okf skill to start a knowledge bundle for this repo."
• "Document this dataset as OKF."
• "Add an OKF concept doc for the orders table and refresh the index."
• "Validate this OKF bundle."
• "Use the okf-ingest skill on this: <path or URL>" — analyze an existing repo / docs / vault and convert it to OKF on your terms.

The okf-ingest skill

okf-ingest brings existing material into OKF compliance. Point it at a local path or a URL (it shallow-clones repos, fetches pages, or expands archives into a scratch area first):

Use the okf-ingest skill on this: <path or URL>

It runs a fixed five-step flow — step 4 is mandatory, so nothing is converted until you choose:

1. Analyze — analyze_source.py inventories the source (file/extension mix, markdown frontmatter & [[wikilink]] stats, source-type signals, likely excludes), supplemented by reading high-signal files.
2. Summarize — source type, volume, what's knowledge-bearing vs. noise, reusable metadata, and what to exclude.
3. Recommend — a per-segment verdict, not one global call:
   • Full — already knowledge-as-markdown (existing bundle, Obsidian/Logseq/ Notion, a docs site) → map ~1:1.
   • Partial / derived — a code repo → extract knowledge (architecture, module catalog, API & schema docs, glossary) into a sidecar bundle; don't convert source files.
   • None — generated output, vendored deps, binaries, secrets → skip.
4. Query — it asks you to choose scope, mode (sidecar vs. in-place), depth, and output path, with the recommended option first.
5. Implement — converts only what you selected, non-destructively by default, rewrites links to bundle-relative form, generates index.md/log.md, then validates with okf's checker and reports a conversion log.

Example recommendation table for a typical code repo:

Segment	Verdict	Why
docs/, README	Full	Curated markdown, high consumption value
src/	Derived	Knowledge is latent — extract architecture + API docs
adr/	Full	Decisions are durable knowledge
dist/, node_modules/	None	Generated / vendored
.env, secrets/	None (exclude)	Sensitive — never ingested

The verdict rubric lives in okf-ingest/reference/decision-framework.md and the per-source recipes in okf-ingest/reference/source-adapters.md. okf-ingest delegates to the okf skill for the spec, templates, and validation, so install both.

Validate a bundle

python okf/scripts/validate_okf.py <bundle_root>   # or: py / python3

Reports errors for real conformance failures (missing/empty type, misplaced frontmatter) and warnings for advisories (broken links, missing index.md). Add --strict to fail on warnings too. Broken links are warnings, never errors — that is intentional per the spec.

The format in one breath

• Each concept is one .md file: queryable YAML frontmatter (type required) + free-form markdown body (# Schema, # Examples, # Citations).
• Concepts link to each other with ordinary markdown links; the relationship's meaning lives in the surrounding prose, not the link. Broken links are OK.
• index.md (navigation) and log.md (changelog) are reserved filenames and carry no frontmatter — except a bundle-root index.md, which may declare okf_version.

See okf/reference/spec.md for the full condensed spec.

Credit

OKF is a specification from Google Cloud's knowledge-catalog project. This repository only packages a Claude Code skill around that format; it is not affiliated with or endorsed by Google.