# ourdigital-okf — Claude Skill Design Spec

> **Status:** Approved (decisions resolved 2026-06-16) · **Author:** Claude Code (brainstorming skill)
> **Notion spec of record:** https://app.notion.com/p/381581e58a1e81128280f43839902dc8
> **Related:** OKF Reference Capture (Notion) · Local reference library at `~/Documents/reference-library/open-knowledge-format/`

A custom Claude skill, triggered by `/ourdigital-okf`, that **produces**, **visualizes**, and **validates**
Google Open Knowledge Format (OKF) v0.1 knowledge bundles. It puts Claude where it is strongest —
drafting and enriching concept documents — the work Google's reference implementation needs a full
Python ADK + Gemini agent to do.

---

## 1. Scope (finalized)

- **In scope:** produce · visualize · validate.
- **Dropped:** query/consume mode (decision 1 — largely native to Claude; not worth the surface area).
- **Out of scope:** wrapping Google's Python `enrichment_agent`; live BigQuery pulls.

## 2. Architecture — "Single skill + bundled utilities" (Approach A)

One coherent skill with three modes. Production *composes existing tooling* rather than reimplementing it,
and stays **MCP-agnostic** (decision 4):

| Need | Source |
| --- | --- |
| Data-source schemas | **Pasted or exported schema** — BigQuery DDL / `information_schema` dump, GA4 export schema, CSV/list of columns, JSON Schema, OpenAPI. No live MCP dependency. |
| Existing docs & markdown | direct file reads |
| Web-research topics | the `/reference-curator` pipeline (or Firecrawl) |
| Conformance + graph viz | two small bundled Python scripts (zero pip deps) |

## 3. Identity & install

- **Trigger:** `/ourdigital-okf` (decision 2 — part of the OurDigital skill family).
- **Source dir:** `/Users/ourdigital/Project/our-claude-skills/custom-skills/97-ourdigital-okf/`
- **Installs to:** `~/.claude/skills/ourdigital-okf/` via `install.sh` (symlink — existing pattern).
- **Conventions:** must follow OurDigital `ourdigital-*` skill rules (`_ourdigital-shared`, brand guide);
  verified by `ourdigital-skill-creator` at the end (decision 6).
- **Activates on:** "OKF", "Open Knowledge Format", "knowledge bundle", "concept docs with YAML frontmatter",
  produce/validate/visualize a bundle.

## 4. File layout (OurDigital `ourdigital-*` convention)

Follows the same structure as existing numbered OurDigital skills (e.g. `04-ourdigital-research`):
top-level `SKILL.md` + `README.md`, a `code/` variant (Claude Code), a `desktop/` variant
(Claude Desktop), and `docs/`.

```
97-ourdigital-okf/
├── SKILL.md                  # top-level canonical (YAML frontmatter: name, triggers, version, author, environment)
├── README.md                 # overview
├── DESIGN.md                 # this spec (repo copy — decision 5)
├── install.sh                # symlink top-level SKILL.md → ~/.claude/skills/ourdigital-okf
├── code/
│   ├── SKILL.md              # Claude Code variant: detailed produce/visualize/validate mode flows
│   ├── CLAUDE.md             # code-pattern pointer
│   ├── references/
│   │   ├── okf-spec-v0.1.md   # SPEC.md distilled into actionable authoring rules + conformance checklist
│   │   └── frontmatter-fields.md
│   ├── assets/
│   │   └── concept.md  index.md  log.md   # templates
│   └── scripts/
│       ├── okf_common.py      # shared frontmatter/link parsing (stdlib only)
│       ├── okf_validate.py    # conformance + broken-link linter
│       ├── okf_viz.py         # minimal viz.html generator (Cytoscape+marked via CDN)
│       ├── requirements.txt   # documents zero runtime deps
│       └── tests/             # stdlib unittest + a mini fixture bundle
├── desktop/
│   ├── SKILL.md              # Claude Desktop variant (leaner)
│   └── skill.yaml
└── docs/
    ├── CHANGELOG.md
    └── IMPLEMENTATION-PLAN.md # the build plan
```

**Zero-dependency choice:** OKF frontmatter uses a tiny YAML subset (`key: value`, `[a, b]` lists),
so `okf_common.py` ships a minimal built-in parser — no PyYAML / pip install. Tests use stdlib
`unittest` (no pytest), keeping the whole skill installable-free.

## 5. Mode: produce (Claude-native)

1. Pick input adapter (schema / docs / research) and **confirm the target bundle directory before
   creating anything** (honors the no-directory-without-consent rule).
2. Gather raw material per §2 — for the data adapter, ingest a pasted/exported schema (no live MCP call).
3. Plan a concept hierarchy (`datasets/`, `tables/`, `metrics/`, `references/`, `playbooks/` — as fits).
4. Draft one concept `.md` per concept: **required** `type` + recommended fields
   (`title`, `description`, `resource`, `tags`, `timestamp`), bundle-relative cross-links
   (`/path/concept.md`), and a `# Citations` section.
5. Auto-generate `index.md` per directory + root; optional `log.md`.
6. **Self-validate** with `okf_validate.py`; fix all errors before reporting done.

## 6. Mode: visualize (minimal first — decision 3)

`okf_viz.py --bundle <dir> [--out viz.html] [--name X]` → one self-contained HTML.
**v1 (minimal):** force-directed concept graph (Cytoscape), type-colored nodes, click a node to see its
rendered markdown + frontmatter. **Later iterations:** "cited by" backlinks, search box, type filter,
layout switch (parity with Google's viewer).

## 7. Validation (supporting)

`okf_validate.py <bundle>` checks: parseable frontmatter on every non-reserved `.md`; non-empty `type`;
`index.md` / `log.md` structure; **broken cross-link report** (warning, not failure). Text + JSON output,
meaningful exit code. Invoked automatically by produce, available standalone.

## 8. Built-in fixtures / regression test

Validator and visualizer are verified against **Google's own three sample bundles** already mirrored:
`~/Documents/reference-library/open-knowledge-format/okf/bundles/{crypto_bitcoin, ga4, stackoverflow}`.
Authoritative, conformant fixtures — no invented test data.

## 9. Success criteria

- `/ourdigital-okf produce` from a pasted schema, a docs folder, or a research topic emits a bundle that
  passes `okf_validate.py` with **0 conformance errors**.
- `okf_viz.py` on any bundle opens a working graph in the browser.
- Both scripts validate/visualize Google's 3 reference bundles cleanly.
- Skill passes `ourdigital-skill-creator` consistency/rules check.

## 10. Build sequence

1. Scaffold `97-ourdigital-okf/` (SKILL.md, README, USER-GUIDE, install.sh, templates) to OurDigital conventions.
2. Distill `SPEC.md` → `reference/okf-spec-v0.1.md` authoring rules + checklist.
3. Write `okf_validate.py`; verify against the 3 Google sample bundles.
4. Write `okf_viz.py` (minimal); verify a working graph for those bundles.
5. Write the produce/visualize/validate mode flows in SKILL.md.
6. End-to-end test: produce a small bundle from a docs folder → validate → visualize.
7. `install.sh` into `~/.claude/skills/ourdigital-okf/`; smoke-test `/ourdigital-okf`.
8. Run `ourdigital-skill-creator` consistency check; fix any rule violations.

## 11. Resolved decisions (2026-06-16)

| # | Question | Decision |
|---|----------|----------|
| 1 | Keep query mode? | **No** — produce + visualize + validate only |
| 2 | Naming | **`ourdigital-okf`** |
| 3 | Viz scope | **Minimal graph first**, iterate |
| 4 | Data adapter | **Accept pasted/exported schema** (MCP-agnostic) |
| 5 | Spec home | Notion (of record) **+ repo `DESIGN.md` copy** |
| 6 | Build method | **writing-plans → implementation**, then `ourdigital-skill-creator` validity check |