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/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.