okf-migrate

okf-migrate

The first time this tool's output was measured blind against raw, uncurated docs, it tied or lost on 3 of 9 eval questions. It took two more rounds of fixing real bugs the eval itself caught — a stale color claim a manual pass had missed, a completed plan silently keeping a wrong "done" checkbox — before the curated bundle cleanly beat raw search: fewer tool calls per query (~11 vs. ~17 across 9 queries), and an edge on catching stale or contradictory claims raw search structurally can't see. That's the honest version of what this does — undersell, then show the receipts.

Version 0.9.0 — feature-complete and validated against real, full-scale material across several independent runs, but not yet frozen: real-world use keeps surfacing small gaps that get folded back in. 1.0.0 is the bar where a run against genuinely new material stops finding anything new to fix.

A Claude Code Skill that turns a project's documentation into OKF (Open Knowledge Format) — a flat, index-first structure (index.md + log.md + typed content files) an agent can navigate without reading everything — or checks an existing OKF bundle for drift. No separate install, no published package, no CLI: this folder is the entire artifact, and it runs its mechanical checks in-session via bundled Python scripts.

What is OKF

OKF (Open Knowledge Format) is a plain-markdown convention, not a new file format or a database: every bundle has one index.md (a curated table of contents — what exists and why it matters, not just a file list) and one log.md (a dated record of every structural change: files added, moved, archived), and every content file underneath carries a small YAML frontmatter block (type, description, status) so it's identifiable without opening it. The payoff is narrow and concrete: an agent that starts from index.md finds the right doc in one or two hops, instead of grepping or reading a whole doc tree to figure out what's current and what's dead. Everything below is about getting a project's real docs into that shape, or checking that shape hasn't drifted.

It orchestrates a migration protocol distilled from several real curation runs, handling three situations:

• "My docs are a mess and I don't trust half of them" (UC1) — a pile of markdown that's never been curated, with plans marked "in progress" that actually shipped months ago, or specs that no longer match the code. The skill walks you through deciding each file's fate (Keep / Archive / Extract→Archive / Drop / Exclude), checks claims against your actual code where one exists, and builds an index.md/log.md bundle plus a short guide-curation-protocol.md documenting the conventions it actually used, so the bundle stays maintainable without this skill or this conversation in the loop.
• "I have code but no docs at all" (UC2) — nothing written down, or so little that starting from a blank page feels wrong. The skill scans routes, schemas, and manifests, proposes a small starter set of reference docs (with your sign-off before writing anything), generates them from the real source, and folds them into the same bundle structure as UC1.
• "I already have an OKF bundle — did it drift?" (UC3) — you've run this before and want to check nothing's gone stale since. The skill re-runs the mechanical checks, walks you through any findings (an orphaned file, a dangling link, an unlogged move), and fixes index.md/log.md together.

It self-detects which of these applies by inspecting the target project — you don't need to specify a mode unless detection is ambiguous.

Scale: the range below is about the markdown knowledge base — the docs the bundle actually indexes — not the size of the codebase those docs describe. The scan only ever counts .md files; a UC2 target can be an arbitrarily large codebase (routes, schemas, manifests) and still produce a small doc set well inside range, since the source code itself was never the thing being sized. Within that: sub-100 markdown files is the validated comfortable range — a flat, hand-authored index.md beats vector search at that size, since every link is a curation decision, not a similarity guess. The skill flags (non-blocking, just a warning) past 100 files. The largest single real run so far was ~124 files; nothing has tested the hundreds-of-files range this approach may eventually need a different answer for.

What it won't do

• It won't fully automate the judgment calls — deciding whether a discrepancy between a doc and your live code actually matters, or scoring how good the resulting bundle is — those stay guided steps where the skill states what it needs a decision on and why, not something it decides silently on your behalf.
• It won't self-score its own curation quality. The eval gate hands scoring off to a fresh-context subagent that hasn't seen the curation session, because an agent that already knows a bundle's structure will route around its gaps rather than exposing them.
• It doesn't integrate with any agent other than Claude Code, and it isn't an MCP server, a hosted dashboard, or a standalone CLI package. If you need OKF tooling outside a Claude Code session, this isn't that project.
• It won't touch a live/shared target without an explicit confirmation naming the specific write and where the backup lives — there's no "just proceed" path around that gate.
• It won't run any destructive step (move, archive, rename) against a dirty git tree. Commit or stash first; git history is the rollback path this replaces "copy the project first" with.
• In maintenance mode (UC3), the log-check that catches an unlogged file move only looks at uncommitted git changes. It catches drift as it's happening, not a past commit that already logged a move inadequately (e.g. it mentioned the file without properly describing what changed) — that kind of already-committed gap needs a manual look at git history, not something a maintenance run surfaces on its own.

What a run looks like

Before, a typical UC1 target — five files, no structure, no way to tell what's current without opening each one:

README.md                    → "See plan-signup-redesign.md and spec-api-auth.md" (stale pointer)
plan-signup-redesign.md      → all checkboxes ticked, status line says "shipped"
plan-search-revamp.md        → all checkboxes ticked, status line says "shipped"
spec-api-auth.md             → frontmatter says `status: draft`, but describes the live API
guide-deploy-checklist.md
notes-standup-2026-05-15.md

Both "plans" are actually finished work wearing a plan's clothes, and the spec's frontmatter disagrees with its own content — exactly the kind of quiet drift this skill looks for. After a UC1 run, the facts survive but the shape changes: finished plans get their real content Extract→Archived into short reference docs, and index.md becomes the entry point instead of a stale README pointer:

# index.md (excerpt)

## Reference
- [Signup API](ref-signup-api.md) — `POST /signup`, extracted from the completed redesign plan.
- [Search API](ref-search-api.md) — `GET /search?q=`, extracted from the completed revamp plan.

## Archive
- [plan-signup-redesign.md](archive/plan-signup-redesign.md) — superseded by `ref-signup-api.md`.
- [plan-search-revamp.md](archive/plan-search-revamp.md) — superseded by `ref-search-api.md`.

# log.md (excerpt)
## 2026-07-29
- Extract→Archived `plan-signup-redesign.md` → `ref-signup-api.md` (plan shipped; content is now a
  live API reference, not a plan).
- Extract→Archived `plan-search-revamp.md` → `ref-search-api.md`, same reason.

This is a real fixture, not a mockup — copy examples/uc1-realistic/ out and run the skill against it yourself (see "Use it" below) to watch the same walk happen live, with the same files.

Why this exists

Curating docs by hand catches real problems (stale claims, orphaned files, undocumented moves) but the process itself is easy to get wrong in ways that compound quietly — a file moves and the index doesn't follow, a completed plan gets kept as "current" because nobody re-checked it against a sibling doc that got archived. This skill exists to make that curation repeatable and to catch the specific failure modes a prior manual pass of this same work actually hit more than once. It has been run end-to-end against real, previously-unseen material at full scale (a 53-file raw doc corpus, a real TypeScript full-stack app with its docs stripped, and a deliberately-introduced drift case) — not just small fixtures — and the gaps those runs found are fixed directly in SKILL.md and scripts/, not left as known issues.

Install

There's nothing to build or publish — copy this folder to one of two places, depending on whether you want it available everywhere or scoped to one project. Claude Code picks either up automatically: no restart, no registration step.

First, get the folder onto disk. Either:

git clone git@github.com:brianarizaga/okf-migrate.git

or use GitHub's "Code → Download ZIP" and unzip it. If you used Download ZIP, the extracted folder is named okf-migrate-main (repo name + branch), not okf-migrate — the commands below target the destination folder explicitly, so the source folder's name doesn't matter, but don't skip renaming or aiming the copy: Claude Code discovers skills by the destination folder's name, and a copy that lands as ~/.claude/skills/okf-migrate-main/ won't respond to /okf-migrate.

Global — available in every project:

cp -r okf-migrate-main ~/.claude/skills/okf-migrate   # Download ZIP
cp -r okf-migrate ~/.claude/skills/                   # git clone

Per-project — available only in this repo, and shareable with collaborators if committed:

cp -r okf-migrate-main /path/to/your-project/.claude/skills/okf-migrate   # Download ZIP
cp -r okf-migrate /path/to/your-project/.claude/skills/                   # git clone

Use the per-project install if you want the skill version-controlled alongside the project it curates (so a teammate who clones the repo gets it too), or if different projects on your machine need different versions of it. Use the global install otherwise — it's the simpler default, and most projects don't need their own pinned copy.

Requirements: a Claude Code session, and Python 3 on the machine the session runs on (the bundled scripts use only the standard library — no pip install needed). If your target project isn't a git repository, the mechanical checks that read git status skip cleanly rather than failing.

Use it

Invoke it in a Claude Code session:

/okf-migrate

with no arguments, pointed at whatever project you're in — it detects UC1/UC2/UC3 from the project's own shape and asks if the signals are ambiguous rather than guessing. You can also force a mode explicitly if you already know which applies, skipping detection:

/okf-migrate existing      # or: curate      — forces UC1 (curate an existing markdown corpus)
/okf-migrate scan          # or: init        — forces UC2 (codebase, no docs yet)
/okf-migrate maintenance   # or: check       — forces UC3 (check an existing bundle for drift)

Before pointing it at a real project, try it against the fixtures shipped in examples/ — seven small directories: three for mode detection alone (one per UC), one purpose-built for the mechanical checks (checks-fixture/), and three larger "realistic" fixtures, one per workflow, that exercise the full UC1/UC2/UC3 steps end to end. See SKILL.md's "Try it first" section for exactly what each one plants and what a correct run should find.

How to actually test against one of these fixtures (not a real project — this whole section is about dry-running the skill against the disposable examples/ material above before trusting it with anything real):

1. Copy the fixture out of examples/ into a scratch directory first — don't run the skill against the shipped copy in place. The three realistic fixtures (uc1-realistic/, uc2-realistic/, uc3-maintenance/) are also this skill's own regression tests; if a live run edits them in place (moves files, writes index.md, etc.) they stop being a reusable clean baseline for the next person or the next test.

   cp -r okf-migrate/examples/uc1-realistic /tmp/try-uc1
   cd /tmp/try-uc1
   

2. For anything involving log_check.py or clean_tree.py (the mechanical checks that read git history — this includes UC3's uc3-maintenance/ drift scenario), run init_git.py on the copy first, since those checks skip cleanly rather than erroring on a non-repo target and won't have anything to catch otherwise. It seeds a .gitignore for any vendored dependency directory it finds (node_modules/, __pycache__/, and similar) before making the baseline commit, so nothing like that ends up staged by accident:

   python3 /path/to/okf-migrate/scripts/init_git.py .
   

3. Start a Claude Code session in that directory and invoke the skill:

   /okf-migrate
   

   Watch that the stated detected mode matches what the fixture is meant to trigger (uc1-corpus/, uc1-realistic/ → UC1; uc2-codebase/, uc2-realistic/ → UC2; uc3-bundle/, uc3-maintenance/ → UC3) before letting it proceed further — a wrong detection here means something's off before any real work happens.

4. For uc3-maintenance/ specifically, the log-check drift case needs one extra step beyond the committed baseline: move guide-onboarding.md to reference/onboarding.md, update index.md's link to match, but deliberately leave log.md untouched — then invoke the skill and confirm it flags the unlogged move rather than passing clean. (checks-fixture/'s planted problems don't need this extra step — they're already present in the fixture as shipped, except its own log-check case, which needs the same git-init-and-commit treatment as step 2.)

5. To sanity-check a mechanical check without going through the skill at all (faster, no LLM judgment involved), run the script directly against the fixture:

   python3 /path/to/okf-migrate/scripts/full_check.py /tmp/try-uc1
   

   Useful for confirming a fixture is in the state you expect before layering a full workflow run on top of it, or for spot-checking a script change against the regression fixtures after editing anything in scripts/.

Structure

• SKILL.md — the skill definition: mode detection, the mechanical checks, safety gates, and the three workflows.
• scripts/ — the seven mechanical checks (inventory, validate, sync-check, staleness, log-check, full-check, scan), the four safety gates (clean-tree, live-target gate, scale flag, protocol stamp), init_git.py (seeds a non-repo target with a vendored-dependency-aware .gitignore and a baseline commit, so clean_tree.py has something to check), and the CLAUDE.md updater — all standalone Python, runnable directly against any target path.
• agents/eval-grader.md — the fresh-context grading instructions the eval gate hands scoring off to.
• examples/ — fixture directories for trying the skill safely and as regression tests for each workflow.
• run_fixture_tests.py / CONTRIBUTING.md — maintainer-only: the regression test runner for scripts/, and how to run it. Not needed to use the skill.

Dev notes

Built and tested against:

• AI assistant: Claude Sonnet 5, via Claude Code CLI 2.1.201.
• Python: 3.12.12. The bundled scripts only use the standard library — no pip install, no requirements.txt — so any reasonably current Python 3 should work, but 3.12 is the version actually exercised.

Not yet verified: macOS and Windows. Python 3's standard-library-only approach was a deliberate choice specifically to avoid platform-specific dependencies, and the git-status parsing is plain and portable, so there's no known reason this wouldn't work on either — it just hasn't been run there yet. If you try it on macOS/Windows and hit something, that's genuinely new information, not a known gap being silently ignored.