From 7123c78d888f5cbe2421733f450e3c4d3daee1e3 Mon Sep 17 00:00:00 2001 From: ebertti Date: Tue, 29 Sep 2026 17:26:51 -0300 Subject: [PATCH] docs: add okf agent skill (SKILL.md, references, README section) --- README.md | 9 ++ skills/okf/SKILL.md | 166 +++++++++++++++++++++++++++ skills/okf/references/frontmatter.md | 67 +++++++++++ skills/okf/references/templates.md | 118 +++++++++++++++++++ 4 files changed, 360 insertions(+) create mode 100644 skills/okf/SKILL.md create mode 100644 skills/okf/references/frontmatter.md create mode 100644 skills/okf/references/templates.md diff --git a/README.md b/README.md index b0c2204..5a7a4b6 100644 --- 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: /.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 new file mode 100644 index 0000000..91868dc --- /dev/null +++ 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: +> 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 ` (one command) and read the JSON. + +--- + +## 1 — The loop + +1. **Orient.** `okf list ` 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 --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 `, fix every `ERROR` finding, re-run until + `"valid": true` (exit 0). Then `okf lint ` for recommended fields + and broken links. +5. **Regenerate navigation.** `okf index ` rewrites the `index.md` + files. + +--- + +## 2 — Commands + +| Goal | Command | +|---|---| +| New bundle (`tables/`, `datasets/`, `playbooks/`, root `index.md` with `okf_version: "0.2"`) | `okf init ` (fails if the directory exists) | +| Spec check; exit 1 on errors | `okf validate [--format json\|sarif] [--exit-zero]` | +| Recommended fields and style (warnings only, exit 0) | `okf lint [--format json\|sarif]` | +| Generate `index.md` in every folder with concepts | `okf index ` | +| Inventory | `okf list ` | +| Read one concept as JSON | `okf show ` | +| Filter concepts | `okf search [--tag T] [--type T] [--text S]` (AND-combined) | +| Who links to this concept? | `okf backlinks ` | +| Link structure, orphans | `okf graph ` (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//`, 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: , at: }` | +| `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:` · `process:` · `/` (agents). +The trust tier `human-reviewed` is derived from a `human:` verifier, so: + +- record yourself as `generated: { by: /, 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 # inventory, status, trust tiers +okf lint # missing title/description/tags, broken links +okf graph # isolated > 0 means orphan concepts +okf search --text deprecated # stale or retired knowledge +okf backlinks # 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 new file mode 100644 index 0000000..698da69 --- /dev/null +++ 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:` · `process:` · `/` + +### 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 new file mode 100644 index 0000000..cbe0809 --- /dev/null +++ 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 ` 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 +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:, 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. +```