okf

Files (10)

• SKILL.md
• index.md · examples/minimal_bundle/datasets/
• sales.md · examples/minimal_bundle/datasets/
• index.md · examples/minimal_bundle/
• customers.md · examples/minimal_bundle/tables/
• index.md · examples/minimal_bundle/tables/
• orders.md · examples/minimal_bundle/tables/
• spec-quickref.md · references/
• tooling.md · references/
• validate_okf.py · scripts/

SKILL.md (first lines)

# OKF — Open Knowledge Format

OKF represents **knowledge** (the metadata and context around data and systems) as
a directory of markdown files with YAML frontmatter. No schema registry, no SDK, no
required tooling: **if you can `cat` a file you can read OKF; if you can `git clone`
a repo you can ship it.** Authoritative spec: OKF v0.1 (`references/spec-quickref.md`).

## The model (learn this first)

You cannot author a bundle correctly without the mental model. Five terms:

- **Bundle** — a directory tree of markdown files. The unit of distribution (a git
  repo, a tarball, or a subdir of a larger repo).
- **Concept** — one unit of knowledge = one markdown file. May describe a real asset
  (a table, an API) or an abstract idea (a metric, a playbook).
- **Concept ID** — the file's path within the bundle with `.md` removed.
  `tables/users.md` → concept id `tables/users`. **The path *is* the concept's
  identity**: moving or renaming a file renames the concept and breaks every inbound
  link to it. Each segment must be a filesystem-safe slug (exact rule:
  `references/spec-quickref.md` §2).
- **Links** — a standard markdown link from one concept to another asserts a
  *relationship*; the kind of relationship lives in the surrounding prose, not the
  link. Prefer **bundle-relative links rooted at `/`**: `[customers](/tables/customers.md)`.
  These are robust to moving the *linking* file (the target path doesn't change with the
  source's depth); they still break if the *target* moves — nothing rewrites links, and
  consumers treat a broken link as not-yet-written knowledge, not an error.
- **Reserved files** — `index.md` (directory listing, §6) and `log.md` (update
  history, §7). These two filenames MUST NOT be used for concept documents. Every
  other `.md` file is a concept.

A concept document = a YAML frontmatter block delimited by `---` lines, then a
markdown body. The **`type` field is required** and must be non-empty — it is the one
field consumers route on. See `references/spec-quickref.md` for all fields and the
full conformance checklist.

**Why it's built this way.** OKF is *permissive by design*: no schema registry, unknown
`type`s and extra keys tolerated, broken links allowed. That is not sloppiness — it is
the bet that knowledge is authored incrementally and never complete, so a bundle must
stay useful while it is half-written, refactored, or partly agent-generated. Treat
missing concepts and broken links as gaps to fill later, not defects to reject.

**Conformance vs. tooling-strict (one rule, stated once).** Spec §9 conformance needs
only a non-empty `type`. The reference producer (`enrichment_agent`) is stricter —
`type`, `title`, `description`, `timestamp` all truthy. Authoring all four is *defensive*
(maximal compatibility with the strictest likely consumer), not an OKF requirement.
Default to all four; validate with `--strict` to enforce them. See `spec-quickref.md`
§"Spec vs. reference-tooling differences" for the full divergence.

## How to create a bundle from scratch

1. `mkdir` a bundle directory. Decide a shallow type-based layout (`datasets/`,
   `tables/`, `references/`, `playbooks/` …) — the structure is yours; OKF does not
   dictate a taxonomy.
2. Write one concept document per unit of knowledge (next section).
3. Cross-link related concepts with `/`-rooted markdown links.
4. Write an `index.md` per directory for progressive disclosure (how-to below).
5. Validate: `python3 scripts/validate_okf.py <bundle-dir> --strict`.
6. (Optional) Add a `log.md` (hand-authored only — see `spec-quickref.md` §7; no tool
   generates it), ship as a git repo, or render with the visualizer (`references/tooling.md`).

See a complete, validated bundle in `examples/minimal_bundle/`.

## How to author a concept document

Create `<type-dir>/<name>.md`:

```markdown
---
type: BigQuery Table          # the only field §9 requires; must be non-empty
title: Orders
description: One row per completed customer order.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders]
timestamp: 2026-05-28T00:00:00Z
---

# Schema

| Column     | Type    | Description                                  |
|------------|---------|----------------------------------------------|
| `order_id` | STRING  | Unique order identifier.                     |
| `cust_id`  | STRING  | FK to [customers](/tables/customers.md).     |

Part of the [sales dataset](/datasets/sales.md).
```

Field meanings and which are required: `references/spec-quickref.md` §4.1.

**Always open the file with `---`.** A file *missing* the opening fence parses as
all-body with empty frontmatter and silently fails conformance (no `type`); a file with
an *unterminated* fence is a hard error. The silent case is the trap — start every
concept with `---`.

Favor structural markdown (headings, tables, lists, fenced code) over prose — it aids
both human reading and agent retrieval. Conventional headings: `# Schema`, `# Examples`,
`# Citations` (use when applicable). Producers MAY add any extra frontmatter keys;
consumers must tolerate unknown keys and unknown `type` values.

## How to write an index.md

`index.md` has **no frontmatter**. Group entries under `#` headings (by type), one
bullet per entry, description from the linked concept's frontmatter:

```markdown
# BigQuery Table

* [Orders](orders.md) - One row per completed customer order.
* [Customers](customers.md) - One row per customer.

# Subdirectories

* [datasets](datasets/index.md) - Dataset-level concepts.
```

The one permitted exception to "no frontmatter": the **bundle-root** `index.md` may
carry a single `okf_version` line as a bare key (no `---` fences), at the very top:

```markdown
okf_version: "0.1"

From mattjoyce/okf-skill, Apache-2.0.