How to Create an OKF Bundle for AI Agents

This is a build guide, not a should-you guide. If you are still deciding whether OKF is worth adopting at all, and how it sits next to schema and llms.txt, start with the decision framework in our playbook chapter on the Open Knowledge Format. If you already know you want to ship a bundle, keep reading.

The Short Answer: What You Are Building

The Open Knowledge Format is Google Cloud's open spec, published as v0.1 in June 2026 under Apache-2.0, for writing down what an organization knows as plain markdown files an agent can read with no SDK. The format is deliberately tiny, so almost all the value is in good curation and honest framing, not in ceremony.

The Shape of an OKF Bundle (60 Seconds)

A bundle is a folder tree. Each concept (a service, a person, a metric, a policy) is exactly one markdown file whose path acts as its id. Files group into subdirectories, each with an index.md, and link to each other with ordinary markdown links so an agent can assemble context by following them. Here is the skeleton:

okf/
├── index.md            (root map; may declare okf_version)
├── log.md              (change history)
├── company/
│   ├── index.md
│   ├── about.md        type: Organization
│   ├── founder.md      type: Person
│   └── contact.md      type: Contact
├── services/
│   ├── index.md
│   └── geo-audit.md    type: Service
└── proof/
    ├── index.md
    └── case-study.md   type: Case Study

That is the whole mental model. The rest of this guide fills it in.

Step 1: Inventory What Your Company Knows

Before you write a single file, list what you actually know and where each fact already lives. This inventory is the real work: a bundle is only as trustworthy as its sourcing, and because machines cross-check your bundle against your site, a contradiction costs trust everywhere at once. Never invent facts to fill a file.

Walk your own surfaces and pull the structured facts that already drive them:

• Identity: your canonical brand name, domain, and contact. Your llms.txt and homepage already state most of it.
• Offerings: one concept per product or service. If your site is built from a data file or CMS collection, that is your source of truth, reuse it so claims match.
• People: founders and key authors, for expertise signals. Reuse your existing author or team profiles rather than writing new bios.
• Proof: case studies, results, and outcomes, using only what is already public. Respect any confidentiality rules you publish under.
• Method and positioning: how you think about the work, pulled from your about page or a pillar resource.
• Your page map: your sitemap tells you what you consider important and gives you the canonical URLs you will drop into each file's resource field.

Group the result into a short list of sections. Resist the urge to include everything; the goal is a small, clean directory of your highest-value concepts, not a mirror of your whole site.

Step 2: Model It as One-Concept Files

Turn the inventory into a file tree. The rule is one concept per file: a service, a person, a metric, an FAQ, each its own markdown file, because an agent should be able to grab the single file it needs without parsing an entire site. This is the same self-contained-unit instinct as passage optimization, applied to a whole knowledge base.

Group related files into subdirectories (company/, services/, method/, proof/), and give each concept a short, descriptive type value. Types are not registered anywhere, so make them self-explanatory: Organization, Person, Service, Case Study, Concept. Decide the bundle's root path now; on a website, a subpath like /okf/ is normal.

Step 3: Write Spec-Conformant Frontmatter

Every concept file opens with a YAML frontmatter block. Only type is required; the rest are recommended in a priority order, and you can add any producer-specific keys after them (a conformant reader must preserve keys it does not recognize). Put the standard fields first, then your extensions.

A finished service concept looks like this:

---
type: Service
title: GEO Audit
description: Measure what AI already believes about you across the major engines.
resource: https://www.example.com/geo-audit-services
tags: [geo-audit, measurement, ai-visibility]
timestamp: 2026-07-22T00:00:00Z
kpi: Mention rate, citation rate, share-of-voice across 5 engines
---

# GEO Audit

Measure what AI engines already believe about your brand before you change anything...

Note kpi: a producer key the spec did not define, kept after the standard fields. That is allowed, and it is how you carry domain detail without breaking conformance.

Step 4: Write the Body and Cross-Link

Below the frontmatter, write normal markdown in your own voice: what the concept is, who it is for, the facts that matter. Pull claims from your Phase 1 sources as close to verbatim as you can, and do not embellish, since the bundle's job is to be a clean, trusted record, not marketing.

Then connect related concepts with plain markdown links. The relationship (a service relates to a case study, a person to the organization) is carried by your surrounding prose, not by the link syntax. One caveat that trips people up: the spec recommends bundle-root-absolute links, but if you serve the bundle on the web at a subpath like /okf/, a link such as /services/geo-audit.md resolves against your site root and breaks. When hosting on the web at a subpath, use relative links (../services/geo-audit.md) so they resolve over HTTP.

Step 5: Add the Reserved Files

Two filenames are special, and getting them right is where most first bundles slip. index.md is a folder's table of contents; it carries no frontmatter and lists its concepts so an agent reads the map before drilling in. log.md is a change history, newest first. Everything else is a concept.

A section index.md (no frontmatter) uses a simple entry format:

# Services

## Concepts
* [GEO Audit](geo-audit.md) - Measure what AI already believes about you.
* [Prompt Research](prompt-research.md) - Buyer questions as a tracked set.

The root index.md is the one exception that may carry frontmatter, and only to declare the version: okf_version: "0.1". A log.md uses dated headings with a bold prefix per entry:

# Change log

## 2026-07-22
**Create** Initial bundle: company, services, method, and proof concepts.

Step 6: Publish and Wire Discovery

Serve the folder with any static file server and version it with git; no backend or database is required. The catch is discovery: there is no official mechanism, and bundles are explicitly loaded, not crawled. You have to tell a named agent where the directory is. Three practical patterns:

• Link it from llms.txt in a short "machine-readable knowledge" section, pointing at your bundle root.
• Add a /.well-known/okf pointer file naming the bundle URL. It is a convention, not a standard, but it is cheap.
• Pass the path in your agent config for the tools you actually run against your knowledge.

Optionally, add a human-facing page at the bundle root that explains the bundle and links every concept, reusing your existing site layout rather than inventing a new one. It gives people (and your sitemap) a front door. Be honest on that page: publishing a bundle is an early-mover bet and a proof asset, not a ranking play. For the strategic why behind that framing, and where OKF sits next to schema, see the playbook.

Step 7: Validate Conformance

Before you ship, check the three v0.1 conformance rules: every non-reserved markdown file has a parseable YAML frontmatter block, every one carries a non-empty type, and reserved files follow their structure. A reader must gracefully tolerate missing optional fields, unknown types, and broken links, so validation is about your own hygiene, not strictness.

Run a validator over the directory. It should catch the hard failures (a concept file with no type, an unterminated frontmatter block) plus soft quality issues worth fixing: a timestamp that is a bare date instead of a full ISO datetime, and broken relative cross-links. Fix every hard failure; review the soft warnings. Then keep the freshness discipline of wiring each timestamp to a real change, the same content freshness habit applied to your knowledge directory.

A Real Example You Can Open

We built one for ourselves, because we build them for clients and it should exist on our own domain. It is live, conformant, and readable: open our OKF bundle to see the human index, then follow it into the raw concept files. It is the exact structure this guide describes: a small company, services, method, and proof directory, wired into our llms.txt and a /.well-known/okf pointer.

Five Mistakes to Avoid

Frequently Asked Questions

The Bottom Line

Creating an OKF bundle is genuinely easy: it is markdown and YAML, one concept per file, validated in seconds. What separates a bundle worth loading from a folder nobody reads is the part that is not mechanical: a truthful knowledge inventory, sourced from what you already publish, kept small, and kept fresh. Build it for an agent you can name, publish it honestly, and treat the search upside as a bonus that may never come.

Want the strategic view (whether to adopt OKF at all, and where it fits in the standards race)? Work through the GEO Playbook, starting with the Open Knowledge Format chapter.