feat(okf): scaffold ourdigital-okf skill skeleton + mini fixture bundle

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-16 19:34:22 +09:00
parent b574c97fcc
commit 4416833cb3
7 changed files with 1250 additions and 0 deletions
--- a/custom-skills/97-ourdigital-okf/DESIGN.md
+++ b/custom-skills/97-ourdigital-okf/DESIGN.md
@@ -0,0 +1,139 @@
+# 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 |