150 lines
7.0 KiB
Markdown
150 lines
7.0 KiB
Markdown
---
|
|
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.
|