ckb/.agents/skills/ckb-export-okf/SKILL.md

name	description
ckb-export-okf	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/<name>/... and libs/<name>/... 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 §5 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 §5 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 at the repository root, or http://www.apache.org/licenses/LICENSE-2.0.