our-claude-skills/custom-skills/97-ourdigital-okf/DESIGN.md

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