140 lines
7.5 KiB
Markdown
140 lines
7.5 KiB
Markdown
# 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 |
|