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/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.