ebertti · Sep 29, 2026
diff --git a/README.md b/README.md
@@ -205,6 +205,15 @@ Graph and backlinks also follow §6.2 path-valued references: `sources[].resourc
 
 All four reference bundles in the upstream repository (acme_retail, crypto_bitcoin, ga4, stackoverflow) load and validate with zero errors.
 
+## Agent skill
+
+`skills/okf/` is a [Claude Code skill](https://docs.claude.com/en/docs/claude-code/skills) (a plain `SKILL.md` plus references) that teaches an agent how to write concepts, validate them, and audit a bundle using this CLI. Install it with:
+
+```bash
+cp -R skills/okf ~/.claude/skills/okf                # all projects
+# or: <project>/.claude/skills/okf                   # one project
+```
+
 ## Project status
 
 Early development. The CLI surface is functional:

diff --git a/skills/okf/SKILL.md b/skills/okf/SKILL.md
@@ -0,0 +1,166 @@
+---
+name: okf
+description: >-
+  Create, validate, lint, index, search and graph Open Knowledge Format (OKF
+  0.2) bundles with the `okf` CLI: directories of markdown files with YAML
+  frontmatter (`type` required) used as agent-readable knowledge bases. Use
+  when the user asks to document or catalog knowledge as OKF, add OKF
+  frontmatter to a file, create or fix an `index.md`/`log.md`, audit a bundle's
+  health, or find what links to a concept.
+---
+
+# Skill: okf — working with OKF bundles
+
+An OKF bundle is a directory of `.md` files. Each file is a **concept** with a
+YAML frontmatter block; only `type` is required. The `okf` CLI is the quality
+gate: it emits JSON on stdout, diagnostics on stderr, and a stable exit code.
+
+> Spec: <https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md>
+> Field cheat sheet: [references/frontmatter.md](references/frontmatter.md) ·
+> Copy-paste templates: [references/templates.md](references/templates.md)
+
+Never guess the CLI surface. Run `okf schema` (all commands) or
+`okf schema <command>` (one command) and read the JSON.
+
+---
+
+## 1 — The loop
+
+1. **Orient.** `okf list <bundle>` shows every concept with id, type, title,
+   status and trust tier. Read the bundle's `index.md` files first: local
+   conventions beat this guide.
+2. **Reuse vocabulary.** `okf search <bundle> --type <Type>` before inventing a
+   new `type`; `type` values are free text and unregistered, so consistency is
+   what makes filtering useful.
+3. **Write** the concept (section 3).
+4. **Gate.** `okf validate <bundle>`, fix every `ERROR` finding, re-run until
+   `"valid": true` (exit 0). Then `okf lint <bundle>` for recommended fields
+   and broken links.
+5. **Regenerate navigation.** `okf index <bundle>` rewrites the `index.md`
+   files.
+
+---
+
+## 2 — Commands
+
+| Goal | Command |
+|---|---|
+| New bundle (`tables/`, `datasets/`, `playbooks/`, root `index.md` with `okf_version: "0.2"`) | `okf init <bundle>` (fails if the directory exists) |
+| Spec check; exit 1 on errors | `okf validate <bundle> [--format json\|sarif] [--exit-zero]` |
+| Recommended fields and style (warnings only, exit 0) | `okf lint <bundle> [--format json\|sarif]` |
+| Generate `index.md` in every folder with concepts | `okf index <bundle>` |
+| Inventory | `okf list <bundle>` |
+| Read one concept as JSON | `okf show <bundle> <concept-id>` |
+| Filter concepts | `okf search <bundle> [--tag T] [--type T] [--text S]` (AND-combined) |
+| Who links to this concept? | `okf backlinks <bundle> <concept-id>` |
+| Link structure, orphans | `okf graph <bundle>` (see `isolated`) |
+
+A **concept id** is the file path relative to the bundle root without `.md`
+(`tables/users`). Exit codes: `0` ok · `1` validation · `2` I/O · `3` internal ·
+`4` usage. Errors arrive as `{"error": {"kind", "code", "reason", "message"}}`
+on stdout: branch on `kind`, not on message text. Every finding has a stable
+rule id (`okf/<family>/<check>`, e.g. `okf/links/broken`).
+
+Only `okf index` and `okf init` write files.
+
+---
+
+## 3 — Writing a concept
+
+Minimal valid concept:
+
+```yaml
+---
+type: Reference
+---
+```
+
+Default to the recommended set:
+
+```yaml
+---
+type: Table                      # REQUIRED, free text, reuse existing values
+title: Customer Orders
+description: One row per completed customer order.   # one sentence
+tags: [sales, orders]
+---
+```
+
+Rules of thumb:
+
+- Body is structured markdown (headings, lists, tables, fenced code), not
+  prose walls. Conventional headings: `# Schema`, `# Examples`, `# Computation`.
+- Link related concepts with bundle-absolute paths: `[users](/tables/users.md)`.
+  The relationship's meaning comes from the surrounding sentence. Broken links
+  are only warnings (they may be knowledge not yet written) — but fix the ones
+  you can.
+- Quote `title`/`description` if they contain `:` or `#`.
+- Extra frontmatter keys are allowed; keep any you did not write.
+- `index.md` and `log.md` are **reserved names**: never use them for concepts.
+  Frontmatter in `index.md` is allowed only at the bundle root, and only for
+  `okf_version`.
+
+### Optional trust / provenance / lifecycle fields
+
+| Field | Shape |
+|---|---|
+| `status` | `draft` \| `stable` (default) \| `deprecated` |
+| `generated` | `{ by: <actor>, at: <ISO 8601 UTC> }` |
+| `verified` | `{ by, at }` or a list of them |
+| `sources` | list of `{ resource (required), id, title, author, usage_count, last_modified }` |
+| `stale_after` | see the note below |
+
+Actors: `human:<id>` · `process:<id>` · `<producer>/<version>` (agents).
+The trust tier `human-reviewed` is derived from a `human:` verifier, so:
+
+- record yourself as `generated: { by: <producer>/<version>, at: ... }`;
+- **never write a `human:` entry in `verified` unless that person actually
+  confirmed the content.**
+
+Per-claim attribution uses a footnote whose label is a `sources[].id`
+(`text.[^id]` … `[^id]: Source title`).
+
+> **`stale_after` format.** The spec (§5.5) says ISO 8601 datetime, but
+> `okf` v0.5.0 currently rejects that and demands `YYYY-MM-DD`
+> (`okf/lifecycle/stale-after-invalid`, tracked in okfcli/okf#34). Use the
+> date form until that is fixed, or `validate` will fail.
+
+---
+
+## 4 — Gotchas
+
+- **Any non-reserved `.md` without frontmatter aborts the whole load**
+  (`validation` error naming the file), it is not just one finding. Keep
+  READMEs, `AGENTS.md` and other non-concepts outside the bundle directory, or
+  give them a `type`.
+- `okf validate` and `okf lint` are the same checks; lint hides errors.
+  Use `--exit-zero` only when a later step must still run (e.g. SARIF upload).
+- `okf index` regenerates `index.md` files and preserves an existing
+  `okf_version`. Do not hand-maintain listings that `index` will overwrite.
+- Legacy v0.1 constructs (`timestamp`, body `# Citations`) still load with
+  migration warnings; prefer `generated.at` and `sources`.
+
+---
+
+## 5 — Audits
+
+```bash
+okf list <bundle>                       # inventory, status, trust tiers
+okf lint <bundle>                       # missing title/description/tags, broken links
+okf graph <bundle>                      # isolated > 0 means orphan concepts
+okf search <bundle> --text deprecated   # stale or retired knowledge
+okf backlinks <bundle> <concept-id>     # blast radius before changing a concept
+```
+
+Summarize findings grouped by `rule`, fix the mechanical ones, and leave
+judgment calls (what a concept *means*) to the user.
+
+## 6 — CI
+
+```yaml
+- run: okf validate ./bundles/ga4                  # fails the job on errors
+# or, to surface findings as PR annotations:
+- run: okf validate --format sarif --exit-zero ./bundles/ga4 > okf.sarif
+- uses: github/codeql-action/upload-sarif@v3
+  with: { sarif_file: okf.sarif }
+```
diff --git a/skills/okf/references/frontmatter.md b/skills/okf/references/frontmatter.md
@@ -0,0 +1,67 @@
+# OKF 0.2 frontmatter cheat sheet
+
+Summary of the [spec](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md);
+the spec wins on any disagreement.
+
+## Base fields
+
+| Field | Status | Notes |
+|---|---|---|
+| `type` | **required** | Free text, not centrally registered (`Table`, `Playbook`, `Metric`, `Reference`…) |
+| `title` | recommended | Falls back to the filename |
+| `description` | recommended | One sentence; used by indexes, search, previews |
+| `resource` | recommended | Canonical URI of the underlying asset; omit for abstract concepts |
+| `tags` | recommended | List of short strings |
+
+## Provenance, trust, lifecycle (all optional)
+
+| Field | Shape | Notes |
+|---|---|---|
+| `sources` | `[{ resource, id?, title?, author?, usage_count?, last_modified? }]` | `resource` is a URL, bundle path, `references/...` path, or a scope descriptor |
+| `usage_window` | `{ from, to }` | Sibling of `sources`; frames every `usage_count` |
+| `generated` | `{ by, at }` | How/when the current content was produced |
+| `verified` | `{ by, at }` or list | Who confirmed the content; independent of `generated` |
+| `status` | `draft` \| `stable` \| `deprecated` | Absent means `stable` |
+| `stale_after` | instant | Stale when `now >= stale_after`. Spec: datetime; `okf` 0.5.0: `YYYY-MM-DD` (okfcli/okf#34) |
+
+Timestamps are ISO 8601 with an explicit offset (`2026-06-30T14:00:00Z`).
+
+### Actors (`generated.by`, `verified[].by`)
+
+`human:<id>` · `process:<id>` · `<producer>/<version>`
+
+### Trust tier (derived, never stored)
+
+| `verified` | Tier |
+|---|---|
+| absent | `unverified` |
+| only non-`human:` actors | `machine-confirmed` |
+| any `human:` actor | `human-reviewed` |
+
+## Attested Computation
+
+`type: Attested Computation` describes a sanctioned way to *compute* a value.
+Required: `runtime`. Also: `parameters` (`[{ name, type, required }]`),
+`computation` (file path; otherwise the fenced block under `# Computation`),
+`executor` (`resource`, `receipt`), `attester` (`resource`). Agents supply
+parameter values only; they do not edit the computation. Concepts that use the
+value just link to it. See spec §10.
+
+## Reserved files
+
+- `index.md` — folder listing (`okf index` generates it). No frontmatter except
+  `okf_version: "0.2"` at the bundle root.
+- `log.md` — history, newest first, `## YYYY-MM-DD` headings.
+
+## Links
+
+- Absolute (recommended): `[x](/tables/users.md)`, relative to the bundle root.
+- Relative: `[x](./other.md)`.
+- Broken links are tolerated by the spec; `okf` reports them as warnings.
+- Path-valued fields (`resource`, `sources[].resource`, `computation`,
+  `executor.resource`, `attester.resource`) that resolve to concepts become
+  edges in `okf graph` / `okf backlinks`.
+
+## v0.1 → v0.2
+
+`timestamp` → `generated.at` · body `# Citations` → `sources`.
diff --git a/skills/okf/references/templates.md b/skills/okf/references/templates.md
@@ -0,0 +1,118 @@
+# OKF concept templates
+
+Copy, adjust, delete what you do not need. Only `type` is required. Run
+`okf validate <bundle>` after writing.
+
+## Generic concept
+
+```markdown
+---
+type: Reference
+title: Readable name
+description: One sentence summarizing the concept.
+tags: [topic]
+---
+
+# Context
+
+# Details
+
+- ...
+
+See also [related concept](/folder/related.md).
+```
+
+## Table (bound to a resource)
+
+````markdown
+---
+type: Table
+title: Customer Orders
+description: One row per completed customer order.
+resource: https://example.com/warehouse/sales/orders
+tags: [sales, orders]
+---
+
+# Schema
+
+| Column | Type | Description |
+|--------|------|-------------|
+| order_id | UUID | Primary key |
+| user_id | UUID | FK to [Users](/tables/users.md) |
+
+# Examples
+
+```sql
+SELECT order_id FROM orders LIMIT 10;
+```
+````
+
+## Playbook
+
+```markdown
+---
+type: Playbook
+title: Freshness alert triage
+description: Steps to triage a freshness alert on the orders pipeline.
+tags: [oncall]
+status: draft
+---
+
+# Trigger
+
+# Steps
+
+1. ...
+```
+
+## Meeting note
+
+```markdown
+---
+type: Meeting Note
+title: Design review with <person>
+description: One-line summary of what was decided.
+tags: [review]
+date: 2026-09-29
+---
+
+# Context
+
+# Decisions
+
+# Next steps
+```
+
+## Concept with provenance and trust
+
+```markdown
+---
+type: Reference
+title: Revenue recognition
+description: How recognized revenue is defined.
+status: stable
+generated: { by: claude-code/opus-5, at: 2026-09-29T17:00:00Z }
+# add `verified` only after a person confirms:
+# verified: { by: human:<id>, at: 2026-09-30T09:00:00Z }
+sources:
+  - id: rev-policy
+    resource: https://wiki.example.com/finance/revenue-recognition
+    title: Revenue recognition policy
+---
+
+Revenue is booked when the service is delivered.[^rev-policy]
+
+[^rev-policy]: Revenue recognition policy
+```
+
+## `log.md`
+
+```markdown
+# Directory Update Log
+
+## 2026-09-29
+* **Creation**: Added [Customer Orders](/tables/orders.md).
+
+## 2026-09-15
+* **Initialization**: Created the bundle.
+```