Create, validate, and consume Google's Open Knowledge Format (OKF) bundles — YAML-frontmatter Markdown files with type / title / description / resource / tags / timestamp fields for portable, interoperable AI-agent knowledge sharing. OKF formalizes the LLM-Wiki pattern into a vendor-neutral open specification so any producer can write and any agent can consume without translation. Routes: use `llm-wiki` for raw source capture + vault maintenance, `obsidian` for Obsidian-vault workflows, `graphify` for durable committed graphs, `scrapling` for web-content extraction into OKF docs. Triggers on: okf, open knowledge format, knowledge bundle, okf document, llm wiki standard, knowledge atom, agent context format, okf frontmatter, okf bundle, knowledge interoperability.
Create, validate, and consume Google's Open Knowledge Format (OKF) bundles — YAML-frontmatter Markdown files with type / title / description / resource / tags / timestamp fields for portable, interoperable AI-agent knowledge sharing. OKF formalizes the LLM-Wiki pattern into a vendor-neutral open specification so any producer can write and any agent can consume without translation. Routes: use `llm-wiki` for raw source capture + vault maintenance, `obsidian` for Obsidian-vault workflows, `graphify` for durable committed graphs, `scrapling` for web-content extraction into OKF docs. Triggers on: okf, open knowledge format, knowledge bundle, okf document, llm wiki standard, knowledge atom, agent context format, okf frontmatter, okf bundle, knowledge interoperability.
allowed-tools
Read Write Edit Bash Grep Glob WebFetch
compatibility
Universal — pure Markdown + YAML, no runtime dependencies. Works in any agent that can read and write files (Claude Code, Codex, Gemini CLI, OpenCode, Cursor, Copilot). Plugin-installable via `npx skills add`. Routes raw source collection to `llm-wiki`, Obsidian vault automation to `obsidian`, durable knowledge graphs to `graphify`, and web scraping into OKF docs to `scrapling`.
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
Each file is a knowledge atom — one YAML-frontmatter Markdown document.
The directory itself is the distributable unit (tarball / git / filesystem mount).
# (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.
---
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.
# Steps1. 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
defload_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:
ifnot f.endswith('.md'):
continue
path = os.path.join(root, f)
text = open(path).read()
ifnot text.startswith('---'):
continue
fm_end = text.find('---', 3)
if fm_end == -1:
continuetry:
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:
passreturn 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
One atom, one concept — each file covers exactly one table, metric,
API endpoint, runbook, or concept; split when scope grows beyond one topic.
description is the agent's headline — write it so an agent can quote it
verbatim in a response without additional context.
Timestamp every production atom — consuming agents can skip stale atoms
based on timestamp; without it, freshness is undetectable.
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.
Validate before distributing — run the Step 4 linter; broken frontmatter
causes silent consume failures in downstream agents.
Git-track for freshness — a git repo lets consumers detect staleness via
commit dates and receive diffs via standard git pull.
