--- 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. The whole transform — frontmatter remapping, link rewriting, index and log regeneration, conformance validation — is done by a deterministic Python script, not by reading and rewriting every page by hand. The mapping is a fixed ruleset over a wiki that will keep growing, and a mechanical transform like this belongs in code, not in per-page model reasoning. Nothing in this skill needs an LLM to run correctly; the model's job is to invoke the script and relay its report. This skill only runs when explicitly invoked — it is deliberately not part of the always-loaded `CLAUDE.md`/`AGENTS.md` Ingest/Lint workflows. ## 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 — Run the script From the repository root: ```bash python3 "/scripts/export_okf.py" ``` Resolve `` to this skill's own directory. Flags: - `--check` — build into a temporary directory, run the conformance checks, print the report, and write nothing to `outputs/`. 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 than `outputs/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.md` files 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 in `wiki/` itself, not in the export — most commonly a page with no `type`, which the bundle exports as `type: unknown`. Surface them; the fix belongs in the source wiki (run `ckb-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-patching `outputs/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/okf` is 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//...` and `libs//...` 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 - **Empty `wiki/entities/` or `wiki/graph/`:** their `index.md` is still regenerated, as an H1 with an empty bullet list. An empty index is spec-valid; the directory is never skipped. - **A future `wiki//` subdirectory:** handled automatically — the script discovers directories dynamically, mirrors them, and generates an index for each. No script changes needed. - **A future `wiki/archived/`:** exported like any other subdirectory. OKF has no notion of archival status; `retention`/`freshness_window_days` already ride along as extension fields for any consumer that cares. - **Non-markdown files in `wiki/`** (e.g. `graph/edges.json`): copied verbatim into the same relative position and listed in their directory's index. Dotfiles (`.gitadd`) are skipped. - **Re-running with no wiki changes:** produces byte-identical output — every directory walk and generated list is sorted. If a run is ever nondeterministic, that's a bug in the script, not expected behavior. --- *Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE) at the repository root, or .*