From okf
Converts loose notes, docs, wikis, or catalog exports into an Open Knowledge Format (OKF) bundle with markdown concept files, YAML frontmatter, index.md, and a knowledge graph. Use when migrating existing knowledge to OKF or normalizing a notes folder.
How this skill is triggered — by the user, by Claude, or both
Slash command
/okf:okf-refactorThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Take knowledge that already exists in some other shape — a folder of loose
Take knowledge that already exists in some other shape — a folder of loose
markdown notes, a wiki, README/docs, a data-catalog export, a database schema, a
JSON/CSV metadata dump — and emit a conformant OKF v0.1 bundle: a directory of
one-concept-per-file markdown docs with YAML frontmatter, navigable index.md
files, and a cross-linked knowledge graph.
This skill depends on the okf skill for the format itself. Read
../okf/reference/SPEC.md (the bundled OKF v0.1 spec) before refactoring — it is
the source of truth. Use ../okf/scripts/validate_okf.py to check the result.
<src>): a directory, file set, or export to read FROM. Treat it as
immutable ground truth — never edit the source in place.<out>): the bundle directory to write TO. New, separate from <src>.Confirm both paths before writing. If <out> is omitted, default to
./bundles/<name> and state the choice.
Survey the source. Inventory every item of knowledge and its natural
boundaries. Identify what each "thing" is (a table, an endpoint, a concept, a
runbook) — that becomes a concept's type. Note relationships between things
(foreign keys, "see also", parent/child) — those become cross-links.
Design the taxonomy = the directory layout. Group concepts into top-level
directories by type or domain (tables/, datasets/, references/,
concepts/, playbooks/…). Start flat; nest only when a level earns it.
Directories are the coarse taxonomy; frontmatter tags carry cross-cutting
facets.
Map each source item to one concept doc. Atomic — one concept per file,
<group>/<slug>.md, kebab-case stable slug. Never pack two concepts into one
file; split multi-topic source notes.
Write frontmatter for each concept. Always set a non-empty type. Derive
title and description (one line — this is what indexes show). Set
resource to the canonical URI when the item has one. Map source metadata to
tags and timestamp. Preserve any source-specific metadata as extra
frontmatter keys (consumers tolerate unknown keys) rather than dropping it.
Write the body. Move structured fields under # Schema (prefer a table),
runnable usage under # Examples, and sources under # Citations. Keep prose
tight; favor structural markdown. Do not invent facts not present in the source.
Wire the graph. Convert every relationship into an inline markdown link
using absolute bundle-relative paths ([orders](/tables/orders.md)).
Ensure no concept is fully orphaned — each should link, or be linked by, at
least one other where a real relationship exists.
Mint reference docs. External authoritative sources cited by many concepts
become standalone references/<slug>.md concept docs (with their own type,
e.g. Reference), linked from # Citations.
Generate indexes. Write an index.md per navigable directory (no
frontmatter; group under # sections; copy each bullet's description from the
linked concept). Write the bundle-root index.md with okf_version: "0.1"
frontmatter linking the top-level groups.
Seed log.md. At the root, record an ## <YYYY-MM-DD> entry noting the
* **Initialization**: Refactored from <source>. Use the real current date.
Validate. Run validate_okf.py <out>. Fix every error. Broken
cross-links are warnings (the spec tolerates them) — resolve the ones you can,
report the rest.
<out>; <src> is read-only.After the pass, summarize: number of concepts emitted (by type/group), index and
reference docs created, cross-links wired, and any unresolved gaps or broken links
the source left dangling. Then show the bundle tree.
<src> (read-only) and <out> (new) paths.type, plus title + description.okf_version: "0.1"; per-directory indexes generated.npx claudepluginhub duyet/codex-claude-pluginsGuides test-driven development for Django applications using pytest-django, factory_boy, and Django REST Framework. Covers red-green-refactor workflow, conftest fixtures, and coverage reporting.