How to Create an OKF Bundle:
Step-by-Step Tutorial

What Is an OKF Bundle?

An OKF (Open Knowledge Format) bundle is a directory of markdown files that packages domain knowledge for AI agents. Each file — called a "concept document" — has YAML frontmatter for metadata and a markdown body for content.

Think of it as a portable, version-controllable knowledge base that any AI agent can load into its context window without needing any SDK, API, or proprietary tool. The format was launched by Google Cloud Platform in mid-2026 and has quickly become the standard for packaging knowledge in the AI agent ecosystem.

Currently, BundleDex indexes 270 OKF bundles from across the ecosystem. This tutorial will show you how to create the next one.

Prerequisites

You don't need much to create an OKF bundle:

• A text editor (VS Code, Vim, Cursor, or any plain text editor)
• Basic familiarity with Markdown (headings, lists, links, code blocks)
• Git (to version-control and publish your bundle)
• A GitHub account (to host your bundle publicly)

That's it. No SDKs, no APIs, no build tools, no databases.

Step 1: Create the Bundle Directory

Every OKF bundle starts as a directory. The name of the directory becomes your bundle's identity:

mkdir my-knowledge-bundle
cd my-knowledge-bundle

Later, this directory will become your GitHub repository. Choose a descriptive, hyphenated name that reflects your bundle's content.

Step 2: Write the index.md Manifest

The index.md file is your bundle's entry point. It tells AI agents what the bundle is about and provides a starting point for exploration.

Every index.md needs YAML frontmatter — metadata enclosed between --- delimiters — followed by a markdown body:

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

# My Knowledge Bundle

This bundle contains practical knowledge about building and using AI agent tooling. It's designed to be consumed by AI agents and human developers alike.

## Contents

- [Getting Started](./getting-started.md) — Set up your tooling environment
- [Agent Configuration](./guides/agent-config.md) — Configure AI agents for your stack
- [API Reference](./references/api.md) — Complete API documentation
- [Troubleshooting](./guides/troubleshooting.md) — Common issues and solutions

Required Frontmatter Fields

Step 3: Add Concept Documents

Each concept document is a markdown file that covers one topic well. Here's a template:

---
title: Getting Started with MyService
description: How to set up and authenticate with MyService
tags: [tutorial, setup, authentication]
---

## Overview

MyService provides [specific functionality]. This guide covers setup.

## Prerequisites

- An API key from the dashboard
- Node.js 18+ or your language of choice

## Authentication

All requests require an API key passed via the `X-API-Key` header:

\`\`\`bash
curl -H "X-API-Key: your-key" https://api.myservice.com/v1/hello
\`\`\`

## Making Your First Request

Once authenticated, make a GET request to the health endpoint:

\`\`\`bash
curl https://api.myservice.com/v1/health
\`\`\`

## Next Steps

- See the [Full API Reference](./references/api.md)
- Learn [Advanced Usage](./guides/advanced.md)

Concept Document Best Practices

• One topic per file. If a concept is getting long, split it into sub-concepts.
• Use descriptive titles. The title field is what agents and search engines show in results.
• Include a description. Helps with discovery on BundleDex and in LLM context.
• Tag generously. Tags power the search and category system on BundleDex.
• Use real code examples. Agents learn best from concrete, runnable examples.

Step 4: Structure with Subdirectories

As your bundle grows, use subdirectories to group related concepts. The standard convention:

my-knowledge-bundle/
├── index.md                # Bundle manifest (required)
├── log.md                  # Changelog (optional)
├── getting-started.md      # Top-level concept
├── concepts/               # Core domain concepts
│   ├── architecture.md
│   ├── data-model.md
│   └── security.md
├── guides/                 # How-to guides
│   ├── installation.md
│   ├── configuration.md
│   └── troubleshooting.md
└── references/             # Reference documentation
    ├── api.md
    └── configuration.md

This structure is a convention, not a requirement. Arrange your bundle however makes sense for your domain. The key principle: filesystem organization mirrors conceptual organization.

Step 5: Cross-Link Concepts

One of OKF's key strengths is that concepts naturally form a knowledge graph through markdown link:

# In guides/installation.md
## Prerequisites

Before installing, understand the [Architecture](../concepts/architecture.md)
and review the [System Requirements](../concepts/requirements.md).

For API key setup, see the [Authentication Guide](./authentication.md).

AI agents follow these links to build a complete understanding of your domain. Well-linked bundles are significantly more useful than flat, unconnected files.

Step 6: Validate Your Bundle

Before publishing, validate that your bundle follows the OKF spec correctly:

# Option 1: Use the Open Knowledge CLI
openknowledge validate ./my-knowledge-bundle/

# Option 2: Use the online validator at okf.md
# Option 3: Manual checklist
./my-knowledge-bundle/
├── index.md                ✅ Has YAML frontmatter with title, description, tags
├── getting-started.md      ✅ YAML frontmatter present
├── concepts/               ✅ Directory organized
│   └── core.md
└── log.md                  ✅ (Optional) Changelog present

Validation Checklist

• ✅ index.md exists at the bundle root
• ✅ index.md has valid YAML frontmatter with title
• ✅ All concept documents have YAML frontmatter with title
• ✅ YAML frontmatter uses --- delimiters correctly
• ✅ All internal links point to files that exist
• ✅ No binary blobs or large non-markdown files in the bundle directory

Step 7: Publish to GitHub

Bundles need to be publicly hosted so AI agents and directory services can discover them. GitHub is the most common host:

git init
git add -A
git commit -m "Initial OKF bundle: My Knowledge Bundle"
gh repo create my-knowledge-bundle --public --push
# Or manually:
git remote add origin https://github.com/your-username/my-knowledge-bundle.git
git push -u origin main

Step 8: Submit to BundleDex

Once your bundle is published, get it indexed so AI agents can discover it:

1. Go to bundledex.net/submit
2. Enter your GitHub repository URL
3. Add a description and tags
4. We'll review and add it within 24 hours

After approval, your bundle will appear in search results, the API at /api/bundles.json, and in /llms.txt — meaning every AI agent that checks BundleDex can find your knowledge.

Best Practices

Based on patterns from the top 5 bundles on BundleDex:

Naming

• Use kebab-case for file names: getting-started.md, api-reference.md
• Use descriptive titles in frontmatter (these show in search results)
• Keep directory names short and meaningful: concepts/, guides/, references/

Content

• Each concept document should be 100-500 words — long enough to be useful, short enough to load in context
• Start with a TL;DR paragraph for agents that need a quick summary
• Use concrete examples over abstract descriptions
• Include code blocks for any command-line or API usage

Cross-Referencing

• Every concept should link to at least 2-3 related concepts
• Use relative links: ../concepts/architecture.md (not absolute URLs)
• Create a log.md to track version history — it helps agents understand what's changed

SEO for OKF Bundles

• Use descriptive descriptions — they power search results on BundleDex and Google
• Tag with both broad and specific tags: [ai-agents, markdown-memory, okf]
• Keep index.md informative — it's the page shown on BundleDex

Real-World Examples

Study these top bundles to see what a well-structured OKF bundle looks like:

• iwe (★ 1,279) — Markdown memory system for you and your AI agent
• Lineage Skill (★ 272) — Distill videos, PDFs, transcripts, and notes into source-backed Agent Skills. Uses OKF/OKF-format for structured knowledge output from course and book materials.
• echoes-vault-opencode (★ 146) — Persistent memory plugin for OpenCode. Obsidian-style knowledge base that survives across sessions
• Claude Mega Brain (★ 111) — OKF-powered knowledge context for Claude Code — injects your project's knowledge base at every session. Includes OKF-conformant index.md with YAML frontmatter and cross-linked concept files.
• obsidian-gemini-helper (★ 101) — AI chat, workflow automation, semantic search (RAG), LLM Wiki (OKF), and dashboards with reading memos powered by Google Gemini. Works on both desktop and mobile.

Each of these bundles follows the patterns described in this tutorial. Clone one, study its structure, and model your own after it.

Helpful Tools

FAQ