OKF Builder Reference / Open Knowledge Format v0.1, explained for builders OKF v0.1
OKF OpenKnowledgeFormat

Open Knowledge Format, explained

Updated 2026-06-13 / OKF v0.1

Portable knowledge bundles for humans and AI agents.

OKF v0.1 YAML frontmatter Markdown body Git-friendly

v0.1

format version covered by this guide

7

copy-ready examples

6

adjacent standards compared

Example first

See it in 30 seconds.

Switch between common project types and copy the shape of an OKF bundle.

The examples are intentionally plain: folders, frontmatter, Markdown, and links before platforms.

File tree

okf/
|-- index.md
|-- log.md
|-- metrics/monthly-recurring-revenue.md
|-- tables/subscriptions.md
`-- playbooks/revenue-review.md

concept file

markdown

---
type: Metric
title: Monthly Recurring Revenue
description: Recurring subscription revenue normalized to a monthly period.
resource: dashboard://revenue/mrr
tags: [revenue, saas, finance]
timestamp: 2026-06-13T00:00:00Z
---

# Calculation

MRR is the predictable recurring revenue generated by active subscriptions in the [subscriptions table](/tables/subscriptions.md).

Include active subscriptions with recurring billing. Exclude one-time setup fees, refunds, and usage-only charges unless normalized into a recurring plan.

# Examples

```sql
select sum(monthly_amount_usd) as mrr
from analytics.subscriptions
where status = 'active';
```

# Citations

[1] [Revenue dashboard](dashboard://revenue/mrr)

File tree

okf/
|-- index.md
|-- datasets/sales.md
|-- tables/orders.md
|-- tables/customers.md
`-- metrics/gross-revenue.md

concept file

markdown

---
type: BigQuery Table
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, revenue]
timestamp: 2026-06-13T00:00:00Z
---

# Schema

| Column | Type | Description |
|--------|------|-------------|
| `order_id` | STRING | Unique order identifier. |
| `customer_id` | STRING | Foreign key to [customers](/tables/customers.md). |
| `total_usd` | NUMERIC | Order total in US dollars. |

# Citations

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

File tree

okf/
|-- index.md
|-- routes/api-users.md
|-- models/user.md
|-- policies/user-policy.md
`-- jobs/sync-stripe-customer.md

concept file

markdown

---
type: Laravel Model
title: User Model
description: Authenticated account model for customers and internal operators.
resource: repo://app/Models/User.php
tags: [laravel, model, authentication]
timestamp: 2026-06-13T00:00:00Z
---

# Responsibilities

The User model represents an authenticated account and owns customer-facing resources.

# Related concepts

Used by the [API users route](/routes/api-users.md) and protected by the [user policy](/policies/user-policy.md).

# Citations

[1] [Source file](repo://app/Models/User.php)

File tree

okf/
|-- index.md
|-- post-types/product.md
|-- taxonomies/product-category.md
|-- acf/product-fields.md
`-- templates/single-product.md

concept file

markdown

---
type: WordPress Post Type
title: Product
description: Custom post type used to manage product content.
resource: wp-admin/edit.php?post_type=product
tags: [wordpress, post-type, content]
timestamp: 2026-06-13T00:00:00Z
---

# Purpose

The Product post type stores product landing pages and related metadata.

# Related concepts

Rendered by the [single product template](/templates/single-product.md) and enriched by [product fields](/acf/product-fields.md).

File tree

okf/
|-- index.md
|-- endpoints/create-customer.md
|-- schemas/customer.md
`-- errors/rate-limit.md

concept file

markdown

---
type: API Endpoint
title: Create Customer
description: Creates a new customer record.
resource: https://api.example.com/customers
method: POST
path: /api/customers
tags: [api, customers]
timestamp: 2026-06-13T00:00:00Z
---

# Request

Accepts a customer payload shaped by the [Customer schema](/schemas/customer.md).

# Response

Returns the created customer object or a [rate limit error](/errors/rate-limit.md).

# Examples

```http
POST /api/customers
Content-Type: application/json
```

File tree

okf/
|-- index.md
|-- teams/support.md
|-- policies/refunds.md
|-- systems/billing.md
`-- playbooks/incident-response.md

concept file

markdown

---
type: Policy
title: Refund Policy
description: Rules support and billing teams use when evaluating customer refund requests.
resource: docs://policies/refunds
tags: [support, billing, policy]
timestamp: 2026-06-13T00:00:00Z
---

# Purpose

The refund policy defines when support can approve a refund, when billing review is required, and which cases must be escalated.

# Decision points

* Check whether the customer has an active subscription in the [billing system](/systems/billing.md).
* Escalate disputes, chargebacks, and unclear billing events through the [incident response playbook](/playbooks/incident-response.md).

# Citations

[1] [Refund policy source](docs://policies/refunds)

File tree

okf/
|-- index.md
|-- systems/billing.md
|-- tools/stripe.md
|-- playbooks/support-triage.md
`-- constraints/agent-safety-rules.md

concept file

markdown

---
type: Constraint
title: Agent Safety Rules
description: Operating boundaries an AI agent must follow before using tools or changing customer-facing systems.
resource: docs://agent-context/safety-rules
tags: [agent, safety, tools]
timestamp: 2026-06-13T00:00:00Z
---

# Rules

The agent must read relevant system, tool, metric, and playbook concepts before taking action.

Do not change billing data, refund customers, send external messages, or modify production settings unless a human explicitly approves the specific action.

# Related concepts

Read the [billing system](/systems/billing.md), [Stripe tool](/tools/stripe.md), and [support triage playbook](/playbooks/support-triage.md) before using operational tools.

What is OKF?

A small folder can carry enough context for people, tools, and agents to understand how knowledge fits together.

A minimal format for exchanging knowledge bundles.

A bundle is a directory of concept files; each concept has YAML frontmatter, a Markdown body, and links that make relationships traversable.

01

Knowledge bundle

The unit of distribution: a folder, repo, archive, or subdirectory containing related knowledge.

02

Concept files

One Markdown document per metric, table, API, playbook, process, system, or idea.

03

Frontmatter

Required `type`, plus recommended title, description, resource, tags, timestamp, and extension keys.

04

Links and citations

Markdown links express relationships. Citations point to the sources behind claims.

Why this matters for AI agents.

Agents need more than raw documents. They need self-describing context they can read, filter by type, traverse through links, and preserve across tools.

Context pipeline

Database schema API docs Runbooks Website concepts
OKF bundle
AI agent Search Catalog Docs

Build on OKF

Do not just read about it.

Because OKF is just Markdown, YAML, folders, and links, builders can start with small tools before inventing platforms.

The current toolkit starts with validation, repeatable folder structures, copyable prompts, and examples that keep knowledge portable.

Validator

Check hard v0.1 rules and catch soft quality issues in concept files.

Open validator

Bundle templates

Template

Create bundle folders, root indexes, concept files, and logs for common projects.

View templates

Prompt generator

Prompt

Copy an agent prompt that creates OKF bundles for apps, APIs, warehouses, and knowledge bases.

Copy prompt

Examples

Copy small OKF bundles that show frontmatter, links, logs, and concept files.

View examples

Start here.

A small OKF bundle can begin as a folder in a repo. Keep the first pass boring: choose concepts, add required frontmatter, link related files, and validate.

  1. 1Create an `okf/` folder in a repo or export directory.
  2. 2Add a root `index.md` so people and agents can scan the bundle.
  3. 3Add concept files with a required `type` field and useful descriptions.
  4. 4Use bundle-relative links like `/tables/orders.md` to express relationships.
  5. 5Add citations where claims depend on external sources, then validate.

Compare OKF with adjacent standards.

Create a bundle, then validate it.

Start with a prompt or template, review the generated concept files, and use the validator before sharing the folder with people or agents.