docs(okf): add distilled spec, frontmatter reference, and templates

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

custom-skills/97-ourdigital-okf/code/assets/concept.md

@@ -0,0 +1,18 @@
+---
+type: <Concept type, e.g. BigQuery Table>
+title: <Human-readable display name>
+description: <One-sentence summary>
+resource: <Canonical URI, omit for abstract concepts>
+tags: [<tag>, <tag>]
+timestamp: <ISO 8601, e.g. 2026-06-16T00:00:00Z>
+---
+
+# Schema
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `col`  | TYPE | What it is. FK to [other](/tables/other.md). |
+
+# Citations
+
+[1] [Source title](https://example.com)

custom-skills/97-ourdigital-okf/code/assets/index.md

@@ -0,0 +1,8 @@
+# Group Heading
+
+* [Title](relative-or-bundle-relative-path) - short description from the concept's frontmatter
+* [Another concept](/tables/orders.md) - one row per completed order
+
+# Subdirectories
+
+* [datasets/](datasets/) - dataset-level concepts

custom-skills/97-ourdigital-okf/code/assets/log.md

@@ -0,0 +1,5 @@
+# Update Log
+
+## 2026-06-16
+* **Initialization**: Created the bundle structure.
+* **Creation**: Added the [orders table](/tables/orders.md).

custom-skills/97-ourdigital-okf/code/references/frontmatter-fields.md

@@ -0,0 +1,54 @@
+# OKF Frontmatter Field Reference
+
+Per-field guidance for authoring OKF v0.1 concept frontmatter. Only `type` is required;
+everything else is recommended or optional. Producers may add arbitrary extra keys —
+consumers preserve them and never reject on unknown keys.
+
+| Field | Required | Format | Example |
+|-------|----------|--------|---------|
+| `type` | **Yes** | short string | `BigQuery Table` |
+| `title` | Recommended | string | `Customer Orders` |
+| `description` | Recommended | one sentence | `One row per completed customer order.` |
+| `resource` | Recommended | URI | `https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders` |
+| `tags` | Optional | list of strings | `[sales, revenue]` or block `- sales` |
+| `timestamp` | Optional | ISO 8601 datetime | `2026-05-28T14:30:00Z` |
+
+## `type` — the only required field
+
+A short string identifying the kind of concept. Consumers route, filter, and present on
+it. Type values are **not** registered centrally; pick descriptive, self-explanatory
+values. Common examples:
+
+- `BigQuery Table`, `BigQuery Dataset` — data assets
+- `Metric` — a derived/calculated measure
+- `Reference` — a standalone external doc captured as a concept (often under `references/`)
+- `Playbook`, `Runbook` — operational procedures
+- `API Endpoint` — an API surface
+
+Consumers MUST tolerate unknown `type` values (treat as generic concepts).
+
+## Recommended fields (priority order)
+
+- **`title`** — human-readable display name. If omitted, consumers derive one from the
+  filename.
+- **`description`** — a single summarizing sentence. Used by `index.md` generators,
+  search snippets, and previews — keep it crisp.
+- **`resource`** — a URI uniquely identifying the underlying asset. Omit for concepts
+  that describe abstract ideas (a metric, a business process) rather than a physical
+  resource.
+- **`tags`** — cross-cutting categorization. Accepts inline (`[a, b]`) or block list
+  (`- a` on following lines) form.
+- **`timestamp`** — ISO 8601 datetime of the last meaningful change.
+
+## Extensions
+
+Add any additional keys your producer needs (e.g. `owner`, `sensitivity`, `okf_version`).
+Round-tripping consumers SHOULD preserve unknown keys and SHOULD NOT reject documents
+that carry them.
+
+## Notes for this skill's parser (`okf_common.py`)
+
+The bundled validator/visualizer parse a small YAML subset that covers real OKF bundles:
+`key: value`, inline lists `[a, b]`, block lists (`key:` then `- item`), folded
+multi-line scalars (a value continued on indented lines), `>`/`|` block scalars, and
+quoted scalars. It is not a full YAML engine — keep frontmatter to these shapes.

custom-skills/97-ourdigital-okf/code/references/okf-spec-v0.1.md

@@ -0,0 +1,92 @@
+# OKF v0.1 — Authoring Rules & Conformance Checklist
+
+Distilled, actionable reference for producing and validating Open Knowledge Format
+bundles. Authority: the full spec at
+`~/Documents/reference-library/open-knowledge-format/okf/SPEC.md`. **Read this file
+before producing a bundle.**
+
+## Core model
+
+- **Bundle** — a directory tree of markdown files. The unit of distribution.
+- **Concept** — one markdown file = one unit of knowledge (a table, dataset, metric,
+  playbook, API, reference…).
+- **Concept ID** — the bundle-relative file path with `.md` removed
+  (`tables/users.md` → `tables/users`). The path *is* the identity.
+- Concepts form a **graph**, linked by ordinary markdown links — richer than the
+  parent/child implied by the directory tree.
+
+## Reserved filenames (not concepts)
+
+| File | Purpose |
+|------|---------|
+| `index.md` | Directory listing for **progressive disclosure** (§6). No frontmatter — except an optional bundle-root `index.md` may carry `okf_version: "0.1"`. |
+| `log.md` | Update history: date-grouped (`YYYY-MM-DD`, newest first), entries lead with a bold verb (`**Update**`, `**Creation**`…). |
+
+All other `.md` files are concept documents.
+
+## Frontmatter
+
+YAML block delimited by `---` at the very top of the file.
+
+| Field | Status | Notes |
+|-------|--------|-------|
+| `type` | **REQUIRED** | Short string, e.g. `BigQuery Table`, `BigQuery Dataset`, `Metric`, `Playbook`, `Reference`, `API Endpoint`. Not centrally registered; consumers tolerate unknown types. |
+| `title` | Recommended | Display name; else derived from filename. |
+| `description` | Recommended | One sentence; used in index snippets/previews. |
+| `resource` | Recommended | Canonical URI of the underlying asset; omit for abstract concepts. |
+| `tags` | Optional | List of short strings (inline `[a, b]` or block `- a`). |
+| `timestamp` | Optional | ISO 8601 last-modified time. |
+| *(extensions)* | Optional | Any extra producer keys; preserve, never reject. |
+
+## Body
+
+Standard markdown. Prefer structural markdown (headings, tables, lists, fenced code)
+over prose. Conventional section headings (use when applicable):
+
+| Heading | Purpose |
+|---------|---------|
+| `# Schema` | Columns/fields of an asset. |
+| `# Examples` | Concrete usage, usually fenced code. |
+| `# Citations` | Numbered external sources backing body claims. |
+
+## Cross-linking
+
+- **Bundle-relative (recommended):** leading `/`, from the bundle root —
+  `[customers](/tables/customers.md)`. Stable when files move within a subdirectory.
+- **Relative:** `[other](./other.md)`.
+- A link asserts an *untyped* relationship; the kind is conveyed by surrounding prose.
+- **Broken links are tolerated** — they may represent not-yet-written knowledge. Never
+  an error.
+
+## Conformance (§9) — what the validator enforces
+
+A bundle is conformant if:
+1. Every non-reserved `.md` has a parseable YAML frontmatter block.
+2. Every frontmatter block has a non-empty `type`.
+3. `index.md` / `log.md` follow their structure when present.
+
+Consumers MUST NOT reject for: missing optional fields · unknown `type` values ·
+unknown extra keys · broken cross-links · missing `index.md`.
+
+Run: `python3 ../scripts/okf_validate.py <bundle>` (exit 0 = conformant; broken links
+are warnings).
+
+## Producer authoring rules
+
+1. **One concept per file.** Choose a directory layout that fits the domain
+   (`datasets/`, `tables/`, `metrics/`, `references/`, `playbooks/`…).
+2. **Always set `type`** — descriptive and self-explanatory.
+3. Add `title` + a one-sentence `description` to every concept (drives indexes).
+4. Set `resource` for concepts bound to a real asset; omit for abstract ones.
+5. **Cross-link** related concepts with bundle-relative links; reference FKs/joins in
+   prose.
+6. Add a `# Citations` section (numbered) whenever the body makes externally-sourced
+   claims; cite as URLs, bundle paths, or `references/<slug>` concepts.
+7. Generate an `index.md` per directory (and the root) listing children with their
+   descriptions, for progressive disclosure.
+8. **Self-validate** before declaring done; fix every conformance error.
+
+## Versioning
+
+`<major>.<minor>`. Minor = backward-compatible additions; major = breaking changes.
+Bundles may declare `okf_version: "0.1"` in the root `index.md` frontmatter.