How to Build OKF Bundles — Tools, Templates, and Step-by-Step Guide

What Is an OKF Builder?

An OKF builder is a tool, template, or process used to create Open Knowledge Format bundles. The term covers everything from full-featured CLI scaffolding tools to the simple act of writing markdown files in a text editor.

Building an OKF bundle involves:

• Defining the bundle manifest — Creating index.md with YAML frontmatter (title, description, tags, version)
• Writing concept documents — Adding markdown files that each cover one knowledge concept
• Structuring the bundle — Organizing files into directories (concepts, guides, references)
• Cross-linking concepts — Connecting related ideas with relative markdown links
• Validating conformance — Checking that the bundle follows the OKF specification
• Publishing — Pushing to GitHub and submitting to BundleDex for indexing

The beauty of the OKF format is its simplicity — you don't need any specialized software to build a bundle. But dedicated builder tools can accelerate the process significantly.

OKF Builder Tools Compared

Here are the most popular OKF builder tools organized by workflow preference:

Step-by-Step: Creating Your First OKF Bundle

This section walks you through building an OKF bundle from scratch — no tools required beyond a text editor.

Step 1: Create the Bundle Directory

mkdir my-okf-bundle
cd my-okf-bundle

Step 2: Create the index.md Manifest

Every OKF bundle needs an index.md file at the root. This is the entry point for AI agents and human readers:

---
title: My Knowledge Bundle
description: A practical OKF bundle covering domain concepts
tags: [developer-tools, documentation, best-practices]
version: "1.0.0"
author: Your Name
okf_version: "0.1"
---

# My Knowledge Bundle

This bundle contains structured knowledge about [your domain].
It is designed for AI agents and human readers alike.

## Contents

- [Getting Started](./getting-started.md)
- [Core Concepts](./concepts/core.md)
- [Advanced Usage](./guides/advanced.md)
- [API Reference](./references/api.md)

Step 3: Add Concept Documents

Each concept document covers one topic. Create files with YAML frontmatter and markdown content:

---
title: Getting Started with My Domain
description: A beginner's introduction to the core concepts
tags: [tutorial, beginner, introduction]
---

## Overview

This guide covers the fundamentals of [your domain].

## Prerequisites

- Basic understanding of markdown
- Familiarity with Git

## Core Concepts

[Explain your domain concepts here]

## Next Steps

- See [Core Concepts](./concepts/core.md) for deeper dives
- Check the [Advanced Guide](./guides/advanced.md) for complex scenarios

Step 4: Structure with Subdirectories

As your bundle grows, organize files into subdirectories following standard conventions:

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

Step 5: Cross-Link Related Concepts

Use relative markdown links to build a knowledge graph within your bundle:

# In guides/installation.md

## Prerequisites

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

For configuration details, see the [Configuration Reference](../references/configuration.md).

Step 6: Validate Your Bundle

Before publishing, validate your OKF bundle to ensure it follows the spec:

# Using Open Knowledge CLI
openknowledge validate ./my-okf-bundle/

# Manual validation checklist
ls my-okf-bundle/index.md     # Must exist with YAML frontmatter
head -5 my-okf-bundle/index.md # Check for title and description
find . -name "*.md" | wc -l   # Count concept documents
grep -r "\\](" .               # Check cross-links exist

Step 7: Publish and Submit

Push your bundle to a public GitHub repository, then submit it to BundleDex for indexing:

git init
git add -A
git commit -m "Initial OKF bundle: My Knowledge Bundle"
gh repo create my-okf-bundle --public --push

Templates to Get Started Faster

Instead of starting from an empty directory, use these templates to jump-start your OKF bundle:

my-bundle/
├── index.md

my-bundle/
├── index.md
├── log.md
├── concepts/
├── guides/
└── references/

my-bundle/
├── index.md
├── api/
│   ├── authentication.md
│   ├── endpoints.md
│   └── errors.md
├── sdks/
│   ├── python.md
│   └── javascript.md
└── changelog.md

You can also clone any existing bundle on BundleDex and modify it. Browse the directory for inspiration from top bundles like iwe.

Validating Your OKF Bundle

Validation ensures your bundle is correctly structured and will work with AI agents. Here's what to check:

Automatic Validation

• Open Knowledge CLI — Run openknowledge validate ./your-bundle/ for automated checks
• BundleDex submission — When you submit your bundle, we validate it automatically
• okf.md validator — Online validator at okf.md for quick checks
• okf-lint — Dedicated linter for OKF frontmatter and structure

Manual Validation Checklist

• ✅ index.md exists at the bundle root with valid YAML frontmatter
• ✅ index.md has at minimum a title field
• ✅ All concept documents have YAML frontmatter with title
• ✅ YAML frontmatter uses --- delimiters correctly (not +++ or other formats)
• ✅ No broken internal links — every ](./path) points to an existing file
• ✅ Files use .md extension (not .markdown or .mdown)
• ✅ No large binary files or blobs in the bundle directory
• ✅ Bundle is a public GitHub repository

Publishing and Submitting Your Bundle

Once your bundle is built and validated, share it with the world:

1. Push to GitHub — Make the repository public so AI agents can access it
2. Add a README.md — Separate from index.md, this helps human visitors understand the repo
3. Submit to BundleDex — Go to bundledex.net/submit and enter your GitHub URL
4. Spread the word — Share on X, LinkedIn, or relevant AI communities

After approval, your bundle will appear in search results, the BundleDex API, and in /llms.txt — making it discoverable by AI agents worldwide.

Best Practices for Building OKF Bundles

Naming Conventions

• Use kebab-case for file names: getting-started.md, api-reference.md
• Keep directory names short: concepts/, guides/, references/
• Use descriptive titles in frontmatter — they power search results

Content Quality

• Each concept document should be 100-500 words — complete but concise
• Start with a summary paragraph for quick context loading
• Use concrete examples over abstract descriptions
• Include code blocks for CLI commands, API calls, and configurations

Linking Strategy

• Every concept should link to 2-3 related concepts
• Use relative links (not absolute URLs) for cross-bundle portability
• Create a log.md for version history — helps agents understand changes

SEO for Your Bundle

• Write descriptive descriptions — they appear in BundleDex search and Google
• Tag with both broad and specific tags: [ai-agents, documentation, okf]
• Keep index.md informative — it's the preview shown on BundleDex

Frequently Asked Questions