OKF Tutorial for Beginners — Complete Guide to Open Knowledge Format

What Is OKF? (Open Knowledge Format)

OKF stands for Open Knowledge Format — an open, vendor-neutral standard for packaging knowledge in a way that both humans and AI agents can read. It was created by Google Cloud Platform and has quickly become the most popular format for sharing structured knowledge in the AI agent ecosystem.

At its core, an OKF bundle is simply a directory of markdown files. Each file — called a "concept document" — covers one topic and includes YAML frontmatter (metadata) at the top. The format deliberately requires no special tools, SDKs, or APIs to create or read.

Key Characteristics of OKF

• Portable — OKF bundles are plain files on disk. Copy them, version them with Git, host them anywhere
• Vendor-neutral — No platform lock-in. Any AI agent, any editor, any OS can read OKF
• Self-contained — A bundle includes everything needed to understand a domain
• Cross-linked — Concepts connect via relative markdown links, forming a knowledge graph
• Discoverable — BundleDex indexes bundles so AI agents can find them

Why AI Agents Use OKF

AI agents (like Claude Code, ChatGPT, Cursor, and custom agent frameworks) need knowledge to work effectively. Before OKF, there was no standard way to give them domain expertise. Each agent had its own format — or worse, no format at all.

OKF solves this by providing a universal knowledge format that any agent can read. Here's why it matters:

For a deeper look at why this format matters, read What Is Open Knowledge Format? or explore the State of OKF 2026 report.

Anatomy of an OKF Bundle

Every OKF bundle follows a simple structure. Here's what you'll find inside:

my-knowledge-bundle/
├── index.md                 # Bundle manifest (required)
├── log.md                   # Changelog (optional)
├── getting-started.md       # A concept document
├── concepts/                # Core concepts directory
│   ├── architecture.md
│   └── data-model.md
├── guides/                  # How-to guides
│   └── installation.md
└── references/              # Reference docs
    └── api.md

The index.md Manifest

Every bundle has an index.md at its root. This file contains YAML frontmatter describing the bundle and a markdown body that serves as the entry point:

---
title: My Knowledge Bundle
description: A bundle about AI agent tooling
tags: [ai-agents, tools, documentation]
version: "1.0.0"
author: Your Name
okf_version: "0.1"
---

# My Knowledge Bundle

This bundle contains knowledge about AI agent tooling.

## Contents

- [Getting Started](./getting-started.md)
- [Core Concepts](./concepts/architecture.md)
- [Installation Guide](./guides/installation.md)

Concept Documents

Each additional markdown file covers one concept. Every concept document needs YAML frontmatter with at minimum a title field:

---
title: Architecture Overview
description: How the system components interact
tags: [architecture, design, system]
---

# Architecture Overview

The system has three main components: [explain here].

## Component 1: [Name]

[Description of component 1]

## See Also

- [Data Model](./data-model.md)
- [Installation Guide](../guides/installation.md)

How to Create an OKF Bundle

Creating your first OKF bundle takes about 30 minutes. Here's the condensed process:

For a detailed walkthrough with code examples, see the full OKF tutorial: How to Create an OKF Bundle.

How to Publish and Share Your Bundle

Once your bundle is built, getting it out into the world is straightforward:

1. Push to a Public GitHub Repository

AI agents need to access your bundle via URL. GitHub is the most common host:

git init
git add -A
git commit -m "My first OKF bundle"
git remote add origin https://github.com/your-username/my-okf-bundle.git
git push -u origin main

2. Add a README.md

Create a README.md at the repo level (separate from index.md) that explains what the bundle is. This helps humans who discover your repo on GitHub.

3. Submit to BundleDex

BundleDex is the central directory for OKF bundles. Submit your bundle to make it discoverable by AI agents. After approval, your bundle appears in search results, the BundleDex API, and /llms.txt.

4. Share with the Community

Spread the word on social media, in developer communities, and on platforms like X and LinkedIn. The OKF ecosystem grows when knowledge creators share their bundles.

Where to Find OKF Bundles

There are two main ways to discover OKF bundles:

BundleDex — The Central Directory

BundleDex.net is the largest public index of OKF bundles, with 583 bundles across dozens of categories. You can:

• Search by keyword across all bundle names, descriptions, and tags
• Filter by category (ai-agents, pkm, cli, documentation, etc.)
• Sort by GitHub stars to find the most popular bundles
• View detailed bundle pages with metadata, concept listings, and GitHub links

GitHub Search

You can also find OKF bundles directly on GitHub by searching for files containing okf_version or okf.json. Many bundles are discoverable this way before they're added to directories.

Next Steps and Resources

You've completed the beginner OKF tutorial. Here's what to do next:

Frequently Asked Questions