123 lines
6.5 KiB
Markdown
123 lines
6.5 KiB
Markdown
---
|
|
name: ckb-export-okf
|
|
description: 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
|
|
|
|
One-way and on demand: `wiki/` stays authoritative, `outputs/okf/` is
|
|
derived, never hand-edited, never fed back in. A deterministic script does
|
|
the whole transform to [OKF v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md);
|
|
the model invokes it and relays its report.
|
|
|
|
## How to run this skill
|
|
|
|
### Step 1 — Run the script
|
|
|
|
From the repository root:
|
|
|
|
```bash
|
|
<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 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/<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`](references/edge-cases.md). Read that file when a
|
|
run hits something the steps above don't cover; don't load it otherwise.
|