feat(okf): add SKILL.md variants (top/code/desktop), CLAUDE.md, README

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

custom-skills/97-ourdigital-okf/README.md

@@ -0,0 +1,51 @@
+# ourdigital-okf
+
+A custom OurDigital Claude skill for **Google Open Knowledge Format (OKF) v0.1** — produce,
+validate, and visualize knowledge bundles (directories of markdown concept files with YAML
+frontmatter).
+
+## Modes
+
+| Mode | What it does |
+|------|--------------|
+| **produce** | Claude drafts a conformant OKF bundle from a pasted/exported schema, a docs folder, or a `/reference-curator` research topic. |
+| **validate** | Lints a bundle for OKF v0.1 conformance (parseable frontmatter + non-empty `type`); reports broken cross-links as warnings. |
+| **visualize** | Renders a bundle as a self-contained interactive Cytoscape graph (`viz.html`). |
+
+## Install
+
+```bash
+./install.sh
+```
+
+Symlinks the skill into `~/.claude/skills/ourdigital-okf`. Invoke with `/ourdigital-okf`.
+
+## Scripts (Python standard library only — no pip install)
+
+```bash
+python3 code/scripts/okf_validate.py <bundle> [--json]
+python3 code/scripts/okf_viz.py --bundle <bundle> [--out viz.html] [--name "Name"]
+```
+
+Run the tests from `code/scripts/`:
+
+```bash
+python3 -m unittest discover -s tests
+```
+
+The suite is verified against Google's three reference bundles mirrored at
+`~/Documents/reference-library/open-knowledge-format/okf/bundles/` (crypto_bitcoin, ga4,
+stackoverflow).
+
+## Layout
+
+- `SKILL.md` — canonical entry; `code/SKILL.md` — detailed Claude Code flows; `desktop/` — Claude Desktop variant.
+- `code/references/` — distilled OKF spec + frontmatter reference.
+- `code/assets/` — concept/index/log templates.
+- `code/scripts/` — `okf_common.py`, `okf_validate.py`, `okf_viz.py` + tests.
+- `DESIGN.md` — approved design spec. `docs/IMPLEMENTATION-PLAN.md` — build plan.
+
+## Reference
+
+OKF spec and reference implementation:
+<https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf>

custom-skills/97-ourdigital-okf/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: ourdigital-okf
+description: |
+  Produce, visualize, and validate Google Open Knowledge Format (OKF) v0.1
+  knowledge bundles. Activated with the "ourdigital" or "our" keyword for OKF work.
+
+  Triggers (ourdigital or our prefix):
+  - "ourdigital okf", "our okf"
+  - "ourdigital open knowledge format", "our knowledge bundle"
+  - "ourdigital okf 만들기", "our okf 검증", "our okf 시각화"
+
+  Features:
+  - Produce conformant OKF bundles from a pasted/exported schema, a docs folder, or a research topic
+  - Validate a bundle for OKF v0.1 conformance + broken-link report
+  - Visualize a bundle as a self-contained interactive graph (viz.html)
+version: "1.0"
+author: OurDigital
+environment: Both
+---
+
+# OurDigital OKF
+
+Work with **Open Knowledge Format (OKF) v0.1** — Google's open, vendor-neutral standard
+for representing knowledge as a directory of markdown files with YAML frontmatter. Each
+file is a *concept* (table, dataset, metric, playbook, API, reference); the file path is
+its identity; markdown links make the directory a graph. The only required field is
+`type`.
+
+This skill has three modes:
+
+- **produce** — Claude drafts a conformant OKF bundle from one of three inputs: a
+  pasted/exported **schema** (BigQuery DDL, GA4 export schema, CSV/JSON-Schema/OpenAPI), a
+  **docs/markdown** folder, or a **research topic** (via `/reference-curator`). It plans a
+  concept hierarchy, writes one `type`-bearing concept per file, cross-links them, and
+  generates `index.md` files — then self-validates.
+- **validate** — lint a bundle for OKF v0.1 conformance (parseable frontmatter + non-empty
+  `type`) and report broken cross-links as warnings.
+- **visualize** — render a bundle as a self-contained interactive graph in one HTML file.
+
+## Quick start
+
+```bash
+# Validate
+python3 code/scripts/okf_validate.py <bundle> [--json]
+
+# Visualize → writes <bundle>/viz.html (or --out PATH)
+python3 code/scripts/okf_viz.py --bundle <bundle> [--name "Display Name"]
+```
+
+The scripts are Python standard-library only — no install needed.
+
+## Where to look
+
+- **Detailed mode flows:** `code/SKILL.md` (the Claude Code variant).
+- **Authoring authority:** `code/references/okf-spec-v0.1.md` — read before producing.
+- **Field guidance:** `code/references/frontmatter-fields.md`.
+- **Templates:** `code/assets/{concept,index,log}.md`.
+- **Design + plan:** `DESIGN.md`, `docs/IMPLEMENTATION-PLAN.md`.
+
+## Guardrails
+
+- Confirm the output directory with the user before creating it.
+- A bundle is "done" only after the validator reports CONFORMANT with zero errors.
+- Verified against Google's reference bundles at
+  `~/Documents/reference-library/open-knowledge-format/okf/bundles/`.

custom-skills/97-ourdigital-okf/code/CLAUDE.md

@@ -0,0 +1,11 @@
+# ourdigital-okf (Claude Code)
+
+Use `SKILL.md` in this directory as the instruction set for producing, validating, and
+visualizing Open Knowledge Format (OKF) v0.1 bundles.
+
+- Scripts live in `scripts/` and use the Python standard library only (no pip install).
+- Read `references/okf-spec-v0.1.md` before producing a bundle.
+- Templates are in `assets/`.
+- Always confirm the output directory with the user before creating it.
+- A bundle is done only when `python3 scripts/okf_validate.py <bundle>` reports CONFORMANT
+  with zero errors.

custom-skills/97-ourdigital-okf/code/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: ourdigital-okf
+description: |
+  Produce, visualize, and validate Google Open Knowledge Format (OKF) v0.1
+  knowledge bundles. Activated with the "ourdigital" or "our" keyword for OKF work.
+
+  Triggers (ourdigital or our prefix):
+  - "ourdigital okf", "our okf"
+  - "ourdigital open knowledge format", "our knowledge bundle"
+  - "ourdigital okf 만들기", "our okf 검증", "our okf 시각화"
+
+  Features:
+  - Produce conformant OKF bundles from a pasted/exported schema, a docs folder, or a research topic
+  - Validate a bundle for OKF v0.1 conformance + broken-link report
+  - Visualize a bundle as a self-contained interactive graph (viz.html)
+version: "1.0"
+author: OurDigital
+environment: Both
+---
+
+# OurDigital OKF
+
+Produce, validate, and visualize **Open Knowledge Format (OKF) v0.1** bundles. OKF is an
+open, vendor-neutral standard that represents knowledge as a directory of markdown files
+with YAML frontmatter — each file is a *concept* (a table, dataset, metric, playbook, API,
+reference), the file path is its identity, and ordinary markdown links turn the directory
+into a graph. The only hard rule is a `type` field on every concept; everything else is
+producer-defined and consumers tolerate the unknown.
+
+**Before producing anything, read `references/okf-spec-v0.1.md`** — it is the authoring
+authority (reserved filenames, frontmatter fields, cross-linking, conformance). Use
+`references/frontmatter-fields.md` for per-field guidance and `assets/` for templates.
+
+## Mode dispatch
+
+Decide the mode from the request:
+
+- **produce** — "make/build/generate an OKF bundle from …"
+- **validate** — "check/validate/lint this bundle"
+- **visualize** — "visualize/graph this bundle", "make a viz"
+
+The scripts live in `scripts/` and use the Python standard library only (no pip install).
+
+## Mode: produce
+
+Claude drafts the concept documents directly — this is where the skill adds the most value.
+
+1. **Pick the input adapter** and **confirm the output directory with the user before
+   creating it** (OurDigital rule: never create a directory without explicit consent —
+   show the full path and wait for approval). Input adapters:
+   - **Schema (pasted/exported)** — the user pastes or points to an exported schema:
+     BigQuery DDL or `information_schema` dump, a GA4 export schema, a CSV/JSON-Schema/
+     OpenAPI file, or a column list. Do **not** call a live MCP; work from the supplied
+     text so the skill stays portable.
+   - **Docs & markdown** — read a provided file or folder and reorganize its knowledge
+     into concepts.
+   - **Research topic** — invoke `/reference-curator` (or Firecrawl) to gather sources,
+     then distill them into concepts with citations.
+2. **Plan the hierarchy.** Choose directories that fit the domain — typically
+   `datasets/`, `tables/`, `metrics/`, `references/`, `playbooks/`. One concept per file.
+3. **Draft each concept** using `assets/concept.md` as the skeleton. Every concept MUST
+   have a non-empty `type`. Add `title` and a one-sentence `description`; add `resource`
+   when the concept maps to a real asset; add `tags` and `timestamp`. Favor structural
+   markdown (`# Schema` tables, `# Examples`, `# Citations`) over prose.
+4. **Cross-link** related concepts with bundle-relative links (`/tables/customers.md`).
+   Express foreign keys, joins, and dependencies in prose next to the link.
+5. **Generate `index.md`** for each directory and the bundle root (use `assets/index.md`),
+   listing children with their descriptions for progressive disclosure. Optionally add a
+   `log.md` (use `assets/log.md`).
+6. **Self-validate and fix.** Run:
+
+   ```bash
+   python3 scripts/okf_validate.py <bundle>
+   ```
+
+   Resolve every conformance error before reporting the bundle done. Broken links are
+   warnings, not errors.
+
+7. Offer to visualize the result (see below).
+
+## Mode: validate
+
+Run the linter and interpret the report:
+
+```bash
+python3 scripts/okf_validate.py <bundle>          # human-readable
+python3 scripts/okf_validate.py <bundle> --json   # machine-readable
+```
+
+- **Errors** (block conformance): missing/unparseable frontmatter, missing or empty
+  `type`. Exit code is `1` when any error exists, `0` when conformant.
+- **Warnings** (informational): broken cross-links — a link whose target `.md` is not in
+  the bundle. Per the spec these are tolerated (not-yet-written knowledge), so report them
+  but do not treat them as failures.
+
+Summarize the result for the user (concepts count, status, errors, warnings) and, if there
+are errors, point to the exact concept and rule.
+
+## Mode: visualize
+
+Generate a self-contained interactive graph (one HTML file, Cytoscape + marked from a CDN,
+no backend, no data leaves the page):
+
+```bash
+python3 scripts/okf_viz.py --bundle <bundle> [--out viz.html] [--name "Display Name"]
+```
+
+Nodes are concepts colored by `type`; edges are cross-links; clicking a node renders its
+markdown body and frontmatter in a side panel. This is the *minimal* viewer (graph +
+detail panel) — search, type filters, and backlinks are deliberate future iterations.
+Tell the user the output path and that they open it in any browser.
+
+## Example: produce from a pasted schema
+
+The user pastes a BigQuery DDL for `acme.sales.orders` and `acme.sales.customers` and
+asks for a bundle. After confirming the output directory (e.g. `/tmp/sales-okf/`, with
+the user's approval), the producer:
+
+- Creates `datasets/sales.md` (`type: BigQuery Dataset`) describing the dataset and
+  linking to its tables.
+- Creates `tables/orders.md` and `tables/customers.md` (`type: BigQuery Table`), each with
+  a `# Schema` table built from the DDL columns. In `orders.md`, the `customer_id` row
+  links to `[customers](/tables/customers.md)`, and a sentence notes the join key.
+- Adds a root `index.md` and a `tables/index.md` listing each concept with its
+  `description`.
+- Runs `python3 scripts/okf_validate.py /tmp/sales-okf`; on `CONFORMANT`, offers to
+  generate `viz.html`.
+
+Nothing here requires a live database connection — the producer works entirely from the
+pasted DDL, which keeps the skill portable across machines and accounts.
+
+## Resources
+
+- `references/okf-spec-v0.1.md` — distilled authoring rules + conformance checklist (read first).
+- `references/frontmatter-fields.md` — per-field guidance and example `type` values.
+- `assets/concept.md`, `assets/index.md`, `assets/log.md` — templates.
+- `scripts/okf_common.py` — shared frontmatter/link parser (stdlib).
+- `scripts/okf_validate.py` — conformance + broken-link linter.
+- `scripts/okf_viz.py` — minimal graph visualizer.
+- `scripts/tests/` — stdlib `unittest` suite; run `python3 -m unittest discover -s tests`
+  from `scripts/`. The suite is verified against Google's reference bundles under
+  `~/Documents/reference-library/open-knowledge-format/okf/bundles/`.
+
+## Guardrails
+
+- Never create an output directory without explicit user confirmation of the path.
+- Keep the scripts dependency-free; if a real bundle uses YAML the parser cannot handle,
+  extend `okf_common.py` minimally and re-run the test suite.
+- A bundle is "done" only after `okf_validate.py` reports `CONFORMANT` with zero errors.

custom-skills/97-ourdigital-okf/desktop/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: ourdigital-okf
+description: |
+  Produce, visualize, and validate Google Open Knowledge Format (OKF) v0.1
+  knowledge bundles. Activated with the "ourdigital" or "our" keyword for OKF work.
+
+  Triggers (ourdigital or our prefix):
+  - "ourdigital okf", "our okf"
+  - "ourdigital open knowledge format", "our knowledge bundle"
+
+  Features:
+  - Produce conformant OKF bundles from a pasted/exported schema, docs, or a research topic
+  - Validate a bundle for OKF v0.1 conformance + broken-link report
+  - Visualize a bundle as a self-contained interactive graph
+version: "1.0"
+author: OurDigital
+environment: Desktop
+---
+
+# OurDigital OKF (Desktop)
+
+Work with **Open Knowledge Format (OKF) v0.1** — an open standard that represents knowledge
+as a directory of markdown files with YAML frontmatter. Each file is a *concept* (table,
+dataset, metric, playbook, API, reference); the path is its identity; markdown links form a
+graph. The only required frontmatter field is `type`.
+
+## What this skill helps with
+
+- **Produce** — draft a conformant OKF bundle from a pasted/exported schema (BigQuery DDL,
+  GA4 export schema, CSV/JSON-Schema/OpenAPI), from existing docs/markdown, or from a
+  research topic. Write one `type`-bearing concept per file, cross-link them with
+  bundle-relative links, and add an `index.md` per directory for progressive disclosure.
+- **Validate** — check that every non-reserved `.md` has a parseable frontmatter block
+  with a non-empty `type`; treat broken cross-links as tolerated warnings.
+- **Visualize** — render the bundle as a concept graph.
+
+## OKF authoring rules (summary)
+
+- One concept per file; `type` is required; add `title`, `description`, `resource`,
+  `tags`, `timestamp` when applicable.
+- Reserved filenames: `index.md` (directory listing), `log.md` (date-grouped history).
+- Cross-link with bundle-relative paths (`/tables/customers.md`); broken links are allowed.
+- Conventional body headings: `# Schema`, `# Examples`, `# Citations`.
+
+## Scripts
+
+The validator and visualizer are Python standard-library scripts in `code/scripts/`. In
+the Claude Desktop environment, run them from a terminal:
+
+```bash
+python3 code/scripts/okf_validate.py <bundle>
+python3 code/scripts/okf_viz.py --bundle <bundle>
+```
+
+Always confirm the output directory with the user before creating a bundle. See
+`code/references/okf-spec-v0.1.md` for the full authoring rules.

custom-skills/97-ourdigital-okf/desktop/skill.yaml

@@ -0,0 +1,10 @@
+# Skill metadata (extracted from SKILL.md frontmatter)
+
+name: ourdigital-okf
+description: |
+  Produce, visualize, and validate Google Open Knowledge Format (OKF) v0.1 bundles.
+  Triggers: "ourdigital okf", "our okf", "open knowledge format", "knowledge bundle".
+
+version: "1.0"
+author: OurDigital
+environment: Desktop