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