--- name: ckb-export-okf description: Export the local wiki/ knowledge base as an Open Knowledge Format (OKF) v0.1-conformant bundle at outputs/okf/, so any generic OKF tool can consume it. Use when the user asks to "export the wiki as OKF", "generate the OKF bundle", "export to OKF", "publish the OKF export", or "sync outputs/okf". --- # Export to OKF skill ## Purpose Regenerate `outputs/okf/` from the current `wiki/` tree as a bundle that conforms to Google's Open Knowledge Format (OKF) v0.1 spec (https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md), so any generic OKF consumer (e.g. Google's reference graph visualizer) can read this knowledge base without needing to understand this repo's richer, more opinionated schema (`confidence`, `quality`, `retention`, `supersedes`, dual-linking, the cascade layers). This is a one-way, on-demand export — `wiki/` stays the authoritative source; `outputs/okf/` is always a derived artifact of it, never edited by hand and never fed back in. This skill only runs when explicitly invoked — it is deliberately not part of the always-loaded `CLAUDE.md`/`AGENTS.md` Ingest/Lint workflows, so its mapping ruleset doesn't tax every session's context. ## Trigger phrases Use this skill when the user says things like: - "export the wiki as OKF" / "export to OKF" - "generate the OKF bundle" / "regenerate outputs/okf" - "publish the OKF export" - "sync outputs/okf with the wiki" ## How to run this skill ### Step 1 — Read the source tree Read every file under `wiki/` (the whole tree, including `entities/`, `graph/`, and any other subdirectories present). Note which filenames are `index.md` or `log.md` at any depth (these are OKF's two reserved names) — everything else is a concept document. ### Step 2 — Clear and rebuild `outputs/okf/` `outputs/okf/` is a pure, fully-regenerated build artifact. Delete its current contents (if any) and rebuild it from scratch by mirroring `wiki/`'s directory structure 1:1 under `outputs/okf/`. Never hand-patch an existing export — always regenerate the whole bundle, so it can't accumulate stale files left over from wiki pages that were since renamed or removed. Do not touch anything outside `outputs/okf/`. Do not run any `git` commands — regenerating files is this skill's job; staging and committing the result is a separate, explicit action left to the user. ### Step 3 — Transform concept documents (every file that isn't `index.md`/`log.md`) For each such file, rewrite its frontmatter using this field mapping: | wiki/ field | OKF output field | Rule | |---|---|---| | `type` | `type` | passthrough (required on both sides — every wiki page should already have one; if a page is somehow missing it, use `type: unknown` and flag it in the final report rather than skipping the file) | | `resource` | `resource` | passthrough | | `tldr` | `description` | rename | | `last_updated` | `timestamp` | passthrough as-is (bare `YYYY-MM-DD` is a valid ISO 8601 date — do not fabricate a time-of-day that was never recorded) | | *(none — derive)* | `title` | the first `# H1` heading in the body; if there is none, slugify the filename (e.g. `foo-bar.md` → "Foo Bar") | | `confidence`, `quality`, `retention`, `supersedes`, `superseded_by`, `freshness_window_days` | same key names | passthrough unchanged, as OKF extension fields — OKF requires consumers to tolerate unrecognized keys, so these ride along as-is | | `kb_schema_version` (only ever present on `wiki/index.md`) | *(omit)* | OKF's root `index.md` frontmatter is spec-limited to `okf_version` only; this key has no valid home in the bundle and is dropped, not relocated | | *(none)* | `tags` | omit — there is no source field to derive it from; do not fabricate | Then rewrite the body's links: 1. **Strip wikilinks.** Every dual-link in the source looks like `[[Page Name]] / [Page Name](path.md)`. Delete the `[[...]]` half (and the ` / ` separator if present), keep only the `[text](path.md)` half. OKF has no wikilink concept. 2. **Rewrite repo-root-absolute intra-wiki links.** A link like `/wiki/entities/foo.md` becomes `/entities/foo.md` — the OKF bundle root is `outputs/okf/`, not the repo root, so the leading `/wiki` segment must be stripped. Plain relative links (e.g. `../entities/foo.md`) need no change, since the export mirrors `wiki/`'s tree exactly. 3. **Leave `linked//...` and `libs//...` references untouched.** These point outside `wiki/` and outside any self-contained bundle — converting or inlining them is out of scope. OKF explicitly tolerates broken links, so leaving these as unresolvable-outside-the-repo references is spec-compliant. Count how many of these you leave untouched, for the final report. ### Step 4 — Regenerate `index.md` files **Root `outputs/okf/index.md`:** frontmatter contains *only* `okf_version: "0.1"` — this is the one documented exception to "index.md has no frontmatter" in the OKF spec. Body is a flat bullet list, one line per linked page or subdirectory, in the form `* [Title](path) - one-line description` (reuse each page's `description`, i.e. the renamed `tldr`, as the description text). Drop the source `wiki/index.md`'s "Use when" column entirely — it's a Claude-agent-only lazy-loading optimization with no meaning to a generic OKF consumer — and drop any prose sections (like the source's "## Entity Pages" paragraph). **Every nested `index.md`** (`entities/index.md`, `graph/index.md`, and any future topic-folder index): no frontmatter, ever. Strip the source's explanatory prose and italic placeholder notes (e.g. "*(No entities yet — populated on the next ingest.)*"), keeping only the bullet list — an empty list is spec-valid if the directory has no pages yet. ### Step 5 — Regenerate `log.md` files For each `log.md` in the source tree (root and any subdirectory), reformat its entries into OKF's convention: group entries by date under `## YYYY-MM-DD` headers (date only, no time, newest date first), each entry as a bullet: ``` * **Verb**: description with [links](/path/to.md) (source: original source text). ``` Map the source's `ACTION TYPE` to an OKF verb: `CREATE` → Creation, `UPDATE` → Update, `DELETE` → Deprecation, `RESTRUCTURE` → Update (fallback for anything else). Fold the source entry's `- **Source:**` line in as the trailing parenthetical shown above rather than dropping it — it's useful provenance information and OKF's format has room for free text after the verb. Drop the `---` horizontal-rule separators between entries; they are not part of OKF's log format. ### Step 6 — Handle non-reserved special pages `wiki/error-book.md` and `wiki/overview.md` are not OKF reserved filenames (only `index.md` and `log.md` are) — export them as ordinary concept documents using the Step 3 rules like any other page. They should already carry `type`/`tldr`/`last_updated` frontmatter; if you ever find one that doesn't, that's a lint problem in the source wiki — flag it in the report rather than silently patching the export. ### Step 7 — Validate the output bundle Before reporting done, re-check the *generated* `outputs/okf/` bundle against OKF's own conformance criteria (the same shape of check `CLAUDE.md` §6 step 1 runs against the source wiki): - Every non-reserved `.md` file has frontmatter with a non-empty `type`. - The root `index.md`'s frontmatter contains only `okf_version` (or is empty); every nested `index.md` has no frontmatter at all. - Every `log.md` entry matches the `## YYYY-MM-DD` header pattern. - Every intra-bundle link (i.e. every link you did NOT leave untouched in Step 3.3) resolves to a file that actually exists in `outputs/okf/`. If the rewrite in Step 3.2 produced a link that doesn't resolve, that's a bug in this export, not an acceptable "broken link" — fix it before reporting done, don't just note it as a warning. ### Step 8 — Report Tell the user: - How many concept documents were exported. - How many `index.md`/`log.md` files were regenerated. - How many `linked/`/`libs/` cross-cascade references were left unconverted (Step 3.3), since those won't resolve if the bundle is ever moved or shipped standalone. - Any conformance issues found in Step 7 and whether they were fixed. - A reminder that `outputs/okf/` has been regenerated on disk but not staged or committed — that's a separate step for the user to take when ready to publish the update. ## Edge cases - **Empty `wiki/entities/` or `wiki/graph/`** (as of writing, both are empty): still regenerate their `index.md` as an empty bullet list under `outputs/okf/entities/` and `outputs/okf/graph/` — an empty index is spec-valid, don't skip the directory entirely. - **A wiki page missing `type`:** per Step 3, use `type: unknown` and flag it in the report — this indicates the source wiki itself failed lint's conformance check (see `CLAUDE.md` §6 step 1), which is worth surfacing to the user rather than quietly masking it in the export. - **A future `wiki/archived/` directory:** export it like any other subdirectory (mirror the structure, apply the same per-file rules) — OKF has no notion of archival status; `retention`/`freshness_window_days` already ride along as extension fields for any consumer that cares. - **Re-running the skill with no wiki changes since the last run** should produce byte-identical output — if you notice non-determinism (e.g. from arbitrary ordering when listing directory entries), sort filenames alphabetically wherever you're generating a bullet list or walking a directory, so re-runs are stable. --- *Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE) at the repository root, or .*