okf

OKF — Open Knowledge Format

Open Knowledge Format (OKF) is an open specification proposed by the Google Cloud Data team that formalizes the LLM-Wiki pattern into a portable, interoperable format. Knowledge is stored as YAML-frontmatter Markdown files inside a directory (a "bundle"). Any producer can write it, any agent can consume it — no proprietary SDK, no special runtime, no lock-in.

Core idea: Just markdown. Just files. Just YAML frontmatter.

When to use this skill

• You need to create structured knowledge documents an AI agent can parse — table schemas, API specs, metric definitions, runbooks, deprecation notices
• You want a portable knowledge bundle that survives tool changes (no vendor catalog dependency)
• You're building a multi-agent context layer where different systems need the same organizational knowledge (join paths, business KPIs, incident guides)
• You want to cross-link knowledge atoms into a richer relationship graph than a parent/child hierarchy allows
• You need to publish or distribute knowledge as a tarball, git repo, or filesystem mount
• You want to formally align your LLM-wiki output with the OKF v0.1 standard

When NOT to use this skill

• Raw web-source capture and vault-level wiki maintenance → llm-wiki
• Obsidian vault automation (plugin dev, CLI, URI handoff) → obsidian
• Durable committed knowledge graphs from code/docs → graphify
• Web scraping to feed knowledge documents → scrapling

OKF Structure

The bundle directory

knowledge-bundle/
├── tables/
│   ├── orders.md
│   └── customers.md
├── metrics/
│   └── wau.md
├── runbooks/
│   └── outage-response.md
└── concepts/
    └── revenue-calculation.md

Each file is a knowledge atom — one YAML-frontmatter Markdown document. The directory itself is the distributable unit (tarball / git / filesystem mount).

Frontmatter schema (OKF v0.1)

---
type: <string>          # (required) kind of atom: "BigQuery Table", "API Endpoint",
                        #   "Concept", "Runbook", "Metric Definition", "Data Source", …
title: <string>         # (required) human-readable name
description: <string>   # (required) one-sentence summary the agent can quote verbatim
resource: <url>         # (optional) URL to the described resource
tags: [<tag>, …]        # (optional) list for filtering / discovery
timestamp: <ISO 8601>   # (optional) last-updated datetime, e.g. 2026-06-21T10:00:00Z
---

Only type, title, and description are strictly required. Add resource whenever the atom is bound to a live system or URL. timestamp enables freshness checks for consuming agents.

Markdown body sections

Section	Purpose
# Overview	Free-form context — motivation, ownership, caveats
# Schema	Structural description of columns / fields / parameters (table format recommended)
# Examples	Concrete usage examples, primarily code blocks
# Joins / # Relations	Cross-links to related atoms
# Citations	External sources backing the document's claims

Sections are optional; include only those relevant to the atom type.

Instructions

Step 1 — Bootstrap a bundle

# Create the bundle root
mkdir my-knowledge-bundle && cd my-knowledge-bundle

# Scaffold a directory layout
mkdir -p tables metrics runbooks concepts api

For an existing project, place the bundle alongside code or in its own repo:

my-project/
├── src/
├── docs/
└── knowledge/          ← OKF bundle lives here
    ├── tables/
    └── metrics/

Step 2 — Author a knowledge atom

Table atom example

---
type: BigQuery Table
title: Customer Orders
description: One row per completed customer order across all channels.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders, revenue]
timestamp: 2026-06-21T10:00:00Z
---

# Overview

Primary fact table for order analytics. Owned by the Data Engineering team.
Refreshed hourly from the Kafka `orders` topic.

# Schema

| Column        | Type      | Description                                          |
|---------------|-----------|------------------------------------------------------|
| `order_id`    | STRING    | Globally unique order identifier.                    |
| `customer_id` | STRING    | Foreign key into [customers](/tables/customers.md).  |
| `total_usd`   | NUMERIC   | Order total in US dollars after discounts.           |
| `placed_at`   | TIMESTAMP | When the customer submitted the order (UTC).         |
| `channel`     | STRING    | `web` \| `mobile` \| `api` \| `partner`.             |

# Joins

- Join to [customers](/tables/customers.md) on `customer_id` for user attributes.
- Join to [products](/tables/products.md) via [order_items](/tables/order_items.md).

# Citations

[1] [BigQuery table](https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders)

Metric definition atom

---
type: Metric Definition
title: Weekly Active Users (WAU)
description: Count of distinct users who triggered at least one qualifying event in the trailing 7-day window.
tags: [kpi, growth, users]
timestamp: 2026-06-21T10:00:00Z
---

# Overview

Owned by the Growth Analytics team. Used in all executive dashboards.

# Definition

```sql
SELECT
  DATE_TRUNC(event_date, WEEK) AS week_start,
  COUNT(DISTINCT user_id)      AS wau
FROM [events](/tables/events.md)
WHERE event_name IN ('session_start', 'purchase', 'share')
  AND event_date >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
GROUP BY 1
\```

# Relations

- Source table: [events](/tables/events.md)
- Related metric: [Monthly Active Users (MAU)](/metrics/mau.md)

Runbook atom

---
type: Runbook
title: Database Connection Pool Exhaustion
description: Steps to diagnose and recover from connection pool exhaustion on the primary Postgres cluster.
tags: [incident, database, postgres, oncall]
timestamp: 2026-06-21T10:00:00Z
---

# Overview

Triggered when `pg_stat_activity` shows ≥95% pool utilization or `FATAL: remaining connection slots are reserved` errors appear.

# Steps

1. Check active connections: `SELECT count(*) FROM pg_stat_activity;`
2. Identify blocking queries: see [slow-query runbook](/runbooks/slow-queries.md).
3. Kill idle connections older than 5 min if count > threshold.
4. Scale pool via [connection pooler config](/concepts/pgbouncer-config.md).
5. Page DBA on-call if not resolved in 10 min.

# Citations

[1] [PgBouncer docs](https://www.pgbouncer.org/)

Step 3 — Cross-link atoms

Use absolute bundle-root links (recommended — stable across moves):

See the [customers table](/tables/customers.md) for join key details.

Use relative links for co-located files:

See [related concept](./other-concept.md).

Design rule: a link asserts a relationship exists; the surrounding prose (not the link itself) names the relationship type (parent, foreign-key, join, depends-on). This keeps the graph type-free and consumer-flexible.

Step 4 — Validate a bundle

Run a basic structural lint before consuming or distributing:

# Check all .md files have required frontmatter fields
python3 -c "
import os, sys
import re

bundle = '.'  # path to bundle root
errors = []

for root, dirs, files in os.walk(bundle):
    for f in files:
        if not f.endswith('.md'):
            continue
        path = os.path.join(root, f)
        text = open(path).read()
        if not text.startswith('---'):
            continue  # skip non-OKF files
        fm_end = text.find('---', 3)
        if fm_end == -1:
            errors.append(f'{path}: unclosed frontmatter')
            continue
        fm = text[3:fm_end]
        for field in ('type:', 'title:', 'description:'):
            if field not in fm:
                errors.append(f'{path}: missing required field {field!r}')

if errors:
    for e in errors: print('ERROR:', e)
    sys.exit(1)
else:
    print('OK — all OKF files valid')
"

Step 5 — Distribute a bundle

# As a tarball
tar -czf my-knowledge-bundle.tar.gz my-knowledge-bundle/

# As a git repo (recommended for versioning + freshness via timestamp)
git init my-knowledge-bundle && cd my-knowledge-bundle
git add . && git commit -m "Initial OKF bundle"
git remote add origin https://github.com/acme/knowledge-bundle.git
git push -u origin main

# As a filesystem mount in a Docker container
# docker run -v $(pwd)/my-knowledge-bundle:/knowledge ...

Step 6 — Consume a bundle from an AI agent

import os, re, yaml

def load_okf_bundle(bundle_path: str) -> list[dict]:
    """Load all OKF atoms from a bundle directory."""
    atoms = []
    for root, _, files in os.walk(bundle_path):
        for f in files:
            if not f.endswith('.md'):
                continue
            path = os.path.join(root, f)
            text = open(path).read()
            if not text.startswith('---'):
                continue
            fm_end = text.find('---', 3)
            if fm_end == -1:
                continue
            try:
                fm = yaml.safe_load(text[3:fm_end])
                body = text[fm_end + 3:].strip()
                atoms.append({
                    'path': os.path.relpath(path, bundle_path),
                    'frontmatter': fm,
                    'body': body
                })
            except Exception:
                pass
    return atoms

# Usage
atoms = load_okf_bundle('./knowledge')
tables = [a for a in atoms if a['frontmatter'].get('type') == 'BigQuery Table']

Step 7 — Integrate with llm-wiki

OKF bundles are compatible with the repo's llm-wiki skill workflow:

# After running llm-wiki to capture raw sources, promote to OKF-compliant format:
# 1. Add required frontmatter (type, title, description) to each wiki/*.md
# 2. Add resource: field pointing to the source URL
# 3. Organize into typed subdirectories (tables/, metrics/, concepts/, …)
# 4. Run the Step 4 validator

# Use the llm-wiki skill for:
#   - Raw source capture and summarization
#   - Query filing and lint passes
#   - Obsidian/git vault maintenance

# Use OKF for:
#   - Portable, interoperable distribution to other teams/agents
#   - Standard frontmatter that consuming agents can parse without a custom schema

Step 8 — Plugin install

# Project install
npx skills add https://github.com/akillness/jeo-skills --skill okf

# Global install
npx skills add -g https://github.com/akillness/jeo-skills --skill okf

# Target specific agents
npx skills add -g https://github.com/akillness/jeo-skills --skill okf -a claude-code -a codex -y

Also ships scripts/install.sh — a one-shot helper that verifies the pyyaml dependency and optionally validates an existing bundle. See references/usage.md for the full field and section reference.

Output format

When the user asks okf for help, return a compact brief:

# OKF Routing Brief

## Scope
- Task: create-bundle | author-atom | validate | distribute | consume | migrate-from-llm-wiki
- Atom type: table | metric | runbook | concept | api-endpoint | other

## Recommended next move
- bootstrap-bundle | author-atom | validate | distribute | consume | llm-wiki-promote

## Why
- 2-3 bullets grounded in the user's request

## Route-outs
- `llm-wiki` for raw source capture and vault maintenance
- `obsidian` for Obsidian vault automation
- `graphify` for durable committed knowledge graphs
- `scrapling` for web-content extraction into OKF documents

Best practices

1. One atom, one concept — each file covers exactly one table, metric, API endpoint, runbook, or concept; split when scope grows beyond one topic.
2. description is the agent's headline — write it so an agent can quote it verbatim in a response without additional context.
3. Absolute bundle links over relative — /tables/customers.md survives file moves; ../tables/customers.md silently breaks.
4. Timestamp every production atom — consuming agents can skip stale atoms based on timestamp; without it, freshness is undetectable.
5. Type is a free string, not an enum — "BigQuery Table", "Kafka Topic", "REST API", "Runbook", "Metric" are all valid; pick consistently within a bundle and document the conventions in a root README.md.
6. Validate before distributing — run the Step 4 linter; broken frontmatter causes silent consume failures in downstream agents.
7. Git-track for freshness — a git repo lets consumers detect staleness via commit dates and receive diffs via standard git pull.

References

• OKF Specification: https://github.com/google/open-knowledge-format
• PyTorchKR discussion (Korean): https://discuss.pytorch.kr/t/open-knowledge-format-okf-google-ai-feat-llm-wiki/10701
• LLM-Wiki pattern: see llm-wiki skill (../llm-wiki/SKILL.md)
• Obsidian integration: see obsidian skill (../obsidian/SKILL.md)
• Knowledge graph: see graphify skill (../graphify/SKILL.md)
• Web scraping into OKF: see scrapling skill (../scrapling/SKILL.md)
• Local usage reference: references/usage.md
• Local installer: scripts/install.sh