ckb/.agents/skills/ckb-export-okf/SKILL.md
Michał Kopeć bf2cc8e8aa Template 1.23.0: agent-knowledge release 2, schema 1.6
Schema 1.6, all fields optional (D-0014):
- F7 review: `review: draft|reviewed|needs_update`, `reviewed_by`,
  `reviewed_on`; lint check 17 and a review queue; ckb-lint marks reviews
- F4 `> CONTRADICTION:` marker, lint check 18; validity dates deferred
- F21 `tags` against the new `wiki/tags.md`, lint check 19,
  retrieve_candidates.py --tag, DRAFT/NEEDS_UPDATE flags
- F9 profiles in workload/profiles/, protected `## Rules` on project
  scope pages, precedence AGENTS.md > Rules > profile
- F8 explicit lessons (profile or wiki/lessons.md); new ckb-profile skill

Carry-over: `.secrets-allow` `<glob> match:<hash>` entries (also in the
bash/PowerShell fallbacks); open threads no longer print twice.
ckb-upgrade migrates 1.5 -> 1.6; init/reset know tags.md; Starlight
shows review and tags. Smoke test covers a 1.6 KB. Docs in EN and PL.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 20:06:02 +01:00

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`, and from schema 1.6 `review`, `reviewed_by`, `reviewed_on`, `tags` | 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.