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

name, description, version, author, environment

name	description	version	author	environment
ourdigital-okf	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)	1.0	OurDigital	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:

   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:

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):

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.