From 626abd41735e6d51066b71d130b0766e681c5f5b Mon Sep 17 00:00:00 2001 From: Andrew Yim Date: Tue, 16 Jun 2026 19:43:41 +0900 Subject: [PATCH] feat(okf): add SKILL.md variants (top/code/desktop), CLAUDE.md, README Co-Authored-By: Claude Opus 4.8 (1M context) --- custom-skills/97-ourdigital-okf/README.md | 51 ++++++ custom-skills/97-ourdigital-okf/SKILL.md | 65 ++++++++ .../97-ourdigital-okf/code/CLAUDE.md | 11 ++ custom-skills/97-ourdigital-okf/code/SKILL.md | 149 ++++++++++++++++++ .../97-ourdigital-okf/desktop/SKILL.md | 56 +++++++ .../97-ourdigital-okf/desktop/skill.yaml | 10 ++ 6 files changed, 342 insertions(+) create mode 100644 custom-skills/97-ourdigital-okf/README.md create mode 100644 custom-skills/97-ourdigital-okf/SKILL.md create mode 100644 custom-skills/97-ourdigital-okf/code/CLAUDE.md create mode 100644 custom-skills/97-ourdigital-okf/code/SKILL.md create mode 100644 custom-skills/97-ourdigital-okf/desktop/SKILL.md create mode 100644 custom-skills/97-ourdigital-okf/desktop/skill.yaml diff --git a/custom-skills/97-ourdigital-okf/README.md b/custom-skills/97-ourdigital-okf/README.md new file mode 100644 index 0000000..436cd09 --- /dev/null +++ b/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 [--json] +python3 code/scripts/okf_viz.py --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: + diff --git a/custom-skills/97-ourdigital-okf/SKILL.md b/custom-skills/97-ourdigital-okf/SKILL.md new file mode 100644 index 0000000..b4a5ec3 --- /dev/null +++ b/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 [--json] + +# Visualize → writes /viz.html (or --out PATH) +python3 code/scripts/okf_viz.py --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/`. diff --git a/custom-skills/97-ourdigital-okf/code/CLAUDE.md b/custom-skills/97-ourdigital-okf/code/CLAUDE.md new file mode 100644 index 0000000..c06629d --- /dev/null +++ b/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 ` reports CONFORMANT + with zero errors. diff --git a/custom-skills/97-ourdigital-okf/code/SKILL.md b/custom-skills/97-ourdigital-okf/code/SKILL.md new file mode 100644 index 0000000..cd0d68d --- /dev/null +++ b/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 + ``` + + 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 # human-readable +python3 scripts/okf_validate.py --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 [--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. diff --git a/custom-skills/97-ourdigital-okf/desktop/SKILL.md b/custom-skills/97-ourdigital-okf/desktop/SKILL.md new file mode 100644 index 0000000..ba523dd --- /dev/null +++ b/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 +python3 code/scripts/okf_viz.py --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. diff --git a/custom-skills/97-ourdigital-okf/desktop/skill.yaml b/custom-skills/97-ourdigital-okf/desktop/skill.yaml new file mode 100644 index 0000000..1d43078 --- /dev/null +++ b/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