- D-0003: <python> interpreter resolution, per-OS install guide, lint_quick.sh/.ps1 session-start fallback, manual lint checklist, no-script retrieval path, exporters declare Python a hard requirement - Lint check 13 pairs each Crux quote block with the attribution under it, so a multi-source Crux no longer cross-fails; fixture KB gains a second source - Session summaries for 2026-09-29 and 2026-10-01 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
6.7 KiB
| name | description |
|---|---|
| ckb-export-okf | Export wiki/ as an Open Knowledge Format (OKF) v0.1-conformant bundle at outputs/okf/, so any generic OKF tool can consume it. Use for "export the wiki as OKF", "generate the OKF bundle", "export to OKF", or "sync outputs/okf". |
Export to OKF skill
Purpose
Regenerate outputs/okf/ from the current wiki/ tree as a bundle conforming to
Google's Open Knowledge Format (OKF) v0.1
(spec),
so a generic OKF consumer can read this KB without understanding its richer schema.
One-way and on-demand: wiki/ stays authoritative, outputs/okf/ is always derived,
never hand-edited, never fed back in. The whole transform is done by a deterministic
Python script — the model's job is to invoke it and relay its report.
How to run this skill
Step 1 — Run the script
From the repository root:
<python> "<skill-dir>/scripts/export_okf.py"
Resolve <skill-dir> to this skill's own directory and <python> per
"Scripts and the Python Runtime" in AGENTS.md. Python 3.8+ is a hard
requirement here — there is no manual fallback for a 500-line transform.
If no interpreter is found, stop, say so, and point to "Prerequisites" in
docs/MANUAL.md. Flags:
--check— build into a temporary directory, run the conformance checks, print the report, and write nothing tooutputs/. Use this when the user wants to know whether the wiki would export cleanly without touching the working tree (e.g. as part of a review, or before a lint pass).--out DIR— write somewhere other thanoutputs/okf(rarely needed).
The script deletes and rebuilds the output directory on every run, so the
bundle can never accumulate stale files from pages that were since renamed
or removed. It touches nothing outside the output directory and runs no
git commands.
The exit code is 0 when the generated bundle conforms and 1 when it does
not — the report always prints either way, so read it rather than relying on
the exit code alone.
Step 2 — Relay the script's report
The script prints, and you should summarize back to the user:
- Concept documents exported, and
index.md/log.mdfiles regenerated. - Wikilinks stripped and
/wiki/links rewritten to bundle-root paths. - How many
linked//libs/cross-cascade references were left unconverted — those won't resolve if the bundle is ever moved or shipped standalone, which is spec-compliant (OKF tolerates broken links) but worth stating. - Any
SOURCE ISSUE:lines. These are problems inwiki/itself, not in the export — most commonly a page with notype, which the bundle exports astype: unknown. Surface them; the fix belongs in the source wiki (runckb-lint), not in the export. - Any
NONCONFORMANT:lines. These are bugs in the export — an intra-bundle link that doesn't resolve, an index with the wrong frontmatter shape, a malformed log header. Do not report the run as successful when these appear; investigate the script rather than hand-patchingoutputs/okf/. - A reminder that
outputs/okf/has been regenerated on disk but not staged or committed — that's a separate step for the user when they're ready to publish the update. (outputs/okfis gitignored by default in this template, so "publish" usually means copying the bundle elsewhere rather than committing it in place.)
What the transform does (for context, not something you need to re-derive)
Concept documents (every .md that isn't index.md/log.md, including
overview.md, error-book.md, and query-gaps.md — only index.md and
log.md are OKF reserved names):
| wiki/ field | OKF output field | Rule |
|---|---|---|
type |
type |
passthrough; a page with no type exports as unknown and is reported as a source issue |
| (derive) | title |
the first # H1 in the body, else the slugified filename (foo-bar.md → "Foo Bar") |
tldr |
description |
rename |
resource |
resource |
passthrough |
last_updated |
timestamp |
passthrough as-is (bare YYYY-MM-DD is valid ISO 8601 — no time-of-day is fabricated) |
confidence, quality, retention, supersedes, superseded_by, freshness_window_days, source_fingerprint, source_checked |
same keys | passthrough as OKF extension fields, which consumers must tolerate |
kb_schema_version |
(dropped) | the root index.md's frontmatter is spec-limited to okf_version; this key has no valid home in the bundle |
| (none) | tags |
omitted — no source field to derive it from |
Links: the [[Wikilink]] half of every dual-link is dropped, keeping the
markdown half (a bare wikilink with no markdown twin degrades to its plain
label). Root-absolute /wiki/entities/foo.md becomes /entities/foo.md,
since the bundle root is outputs/okf/, not the repo root. Relative links
need no change — the export mirrors wiki/'s tree exactly.
linked/<name>/... and libs/<name>/... references are left untouched and
counted.
Indexes: regenerated from the tree rather than transcribed from the
source, so they can't drift. The root index.md carries only
okf_version: "0.1" (the one documented exception to "index.md has no
frontmatter"); nested indexes carry none. Each body is an H1 plus a flat
* [Title](path) - description bullet list of that directory's direct
children, sorted by path, with each page's own description as the
description text. The source's "Use when" column and prose sections are
dropped — they are Claude-agent lazy-loading optimizations with no meaning
to a generic OKF consumer. An empty list is spec-valid.
Logs: entries are regrouped under ## YYYY-MM-DD headers (date only,
newest date first) as * **Verb**: [affected files] — description (source: ...).
CREATE → Creation, UPDATE → Update, DELETE → Deprecation, anything else
→ Update. The - **Source:** line rides along as the trailing parenthetical
rather than being dropped — it's provenance worth keeping. The ---
separators between entries are dropped; they aren't part of OKF's log format.
Validation runs against the generated bundle before the report prints:
every non-reserved page has a non-empty type; the root index has only
okf_version and nested indexes have no frontmatter; every log.md header
matches ## YYYY-MM-DD; and every intra-bundle link resolves to a file that
exists (cross-cascade linked//libs/ references are exempt by design).
Edge cases
Unusual situations — an empty target, a partial run, a conflicting state,
a missing dependency — are catalogued in
references/edge-cases.md. Read that file when a
run hits something the steps above don't cover; don't load it otherwise.