How to Build an OKF Knowledge Bundle and Share It with Any AI Agent
OKF bundles let you package structured knowledge and share it across agents. Here's how to build one, add metadata, and deploy it to your second brain.
What Is an OKF Knowledge Bundle (and Why Your Agents Need One)
If you’ve ever built more than one AI agent and watched them give inconsistent answers about the same company, product, or process, you’ve already felt the problem that OKF Knowledge Bundles solve.
An OKF Knowledge Bundle — short for Open Knowledge Format — is a portable, structured package of information, context, rules, and metadata that any AI agent can consume. Think of it less like a document and more like a shareable brain module: you build it once, define how it should be read, and attach it to as many agents as you want. Every agent that receives the bundle knows the same facts, follows the same rules, and uses the same definitions.
This matters especially when you’re running multi-agent workflows. Without a shared knowledge layer, each agent gets its own slice of context and makes its own assumptions. With an OKF bundle, they all start from the same foundation.
This guide walks through how to build one from scratch — structuring your content, writing useful metadata, and deploying the bundle so your agents can actually use it.
The Problem with Unstructured Knowledge
Most teams start by pasting information into system prompts. It works, until it doesn’t.
System prompts get long. They become hard to update. If you change a product name or a policy, you have to find and update every agent individually. And because raw text has no structure, the agent has no way to know which parts are definitions, which are rules, and which are background context. It treats everything the same.
The result is agents that hallucinate details, contradict each other, or confidently state outdated information.
OKF bundles address this by treating knowledge as a first-class object — something with structure, metadata, version history, and a defined scope. When knowledge is packaged properly, it’s easier to maintain, easier to share, and easier for agents to interpret correctly.
What Goes Into an OKF Knowledge Bundle
Before you start building, it helps to understand the four components that make a bundle work.
1. Core Knowledge Content
This is the actual information: facts, procedures, definitions, policies, product details, FAQs, brand guidelines, or anything else your agents need to know. The format can be plain text, Markdown, JSON, or structured tables — whatever matches the complexity of what you’re describing.
A support agent bundle might include product FAQs, escalation procedures, and refund policies. A sales agent bundle might include pricing tiers, competitor comparisons, and objection-handling scripts. The content defines what the agent knows.
2. Metadata
Metadata is information about your knowledge, not the knowledge itself. It tells the agent (and any system processing the bundle) how to interpret and use what’s inside.
Key metadata fields typically include:
- Bundle name — a short, clear identifier (e.g.,
customer-support-v2) - Version number — so agents know if they’re working with current information
- Created and updated timestamps — for freshness checks
- Scope — what this bundle is and isn’t meant to cover
- Author or source — who owns and maintains this knowledge
- Tags — for categorization and retrieval (e.g.,
product,policy,internal) - Confidence level — optional, but useful for flagging content that’s still being verified
3. Schema or Structure Definitions
If your bundle includes structured data — like a list of products with prices and SKUs — you should define what each field means. A schema entry might look like:
{
"field": "base_price",
"type": "float",
"unit": "USD",
"notes": "Excludes tax and shipping. Effective as of last updated date."
}Without this, agents make guesses about what data means. With it, they have an explicit reference.
4. Usage Instructions
This is the part most people skip, and it’s often the most valuable. Usage instructions tell the agent not just what the knowledge is, but how to apply it.
Examples:
- “Use pricing information from this bundle only when the user has confirmed their region.”
- “Policy content in this bundle supersedes anything in the system prompt.”
- “When citing figures from the data tables, always note the effective date.”
Good usage instructions turn a passive knowledge store into a directive the agent can act on.
How to Plan Your Bundle Before Building
Building a bundle without a plan produces bloated, unfocused packages that agents can’t navigate efficiently. Before writing a single line, work through these questions.
What is this bundle for? Define the specific use case. A support agent for a SaaS product has different knowledge needs than a research assistant or a sales qualification bot. Narrow bundles are more useful than broad ones.
Who will use it? This affects tone, depth, and format. An agent serving end customers needs simpler language than one serving internal technical teams.
How often does this information change? High-velocity content (pricing, promotions, availability) should be separated from stable content (product descriptions, company history) so you can update one without touching the other.
What shouldn’t be in this bundle? Explicitly defining what’s out of scope prevents the bundle from becoming a dumping ground and helps agents know when to look elsewhere.
Once you have answers, sketch a simple outline before writing. A good outline for a mid-size bundle looks like:
- Metadata block
- Scope and usage instructions
- Core content sections (grouped by topic)
- Structured data tables (if applicable)
- Schema definitions (if applicable)
- Change log
Step-by-Step: Building the Bundle
Step 1: Create the Metadata Block
Start every bundle with a clearly labeled metadata block. JSON works well for machine readability, but YAML or Markdown front matter is fine too.
{
"bundle_name": "product-knowledge-v3",
"version": "3.1.2",
"created": "2024-01-10",
"last_updated": "2025-05-15",
"owner": "Product Team",
"scope": "Covers all products in the core subscription tier. Does not include enterprise-only features.",
"tags": ["product", "core-tier", "pricing", "features"],
"language": "en-US",
"status": "active"
}Keep this block at the top. When another system ingests your bundle, it reads the metadata first to decide whether to use the content at all.
Step 2: Write the Scope and Usage Instructions Section
Immediately after the metadata, write a short plain-language description of what this bundle covers and how agents should use it.
## Scope
This bundle covers product features, pricing, and usage limits for the Core subscription tier (Individual and Team plans). It does not cover Enterprise plan specifics or legacy pricing.
## Usage Instructions
- Reference this bundle when answering questions about plan features or pricing.
- For enterprise inquiries, redirect to the sales team rather than estimating from this data.
- Pricing is listed in USD. For local currency, instruct the user to check the pricing page.
- This bundle is authoritative. If the user provides conflicting information, trust this bundle.Plain sentences work better here than bullet-only formats. Agents process imperative instructions clearly.
Step 3: Write the Core Content
This is the substantive knowledge. Write it in whatever format matches the content type:
- Use plain paragraphs for explanations and background context
- Use numbered lists for procedures and step-by-step guides
- Use tables for structured comparisons, pricing tiers, or feature matrices
- Use definitions lists for glossaries or key terms
Write for the agent, not for a human reader. That means being explicit about things a human would infer. Instead of “plans vary,” write “Individual plan supports 1 user seat; Team plan supports 5–50 user seats.” Precision reduces hallucination.
Group content into clearly labeled sections. Use H2 or H3 headers so the bundle has navigable structure. If it’s a JSON bundle, use nested objects with descriptive keys.
Step 4: Add Structured Data and Schema Definitions
If your bundle includes data tables or any content with multiple fields, add a schema section.
{
"schema": {
"pricing_table": {
"plan_name": "string — official product name",
"monthly_price": "float — USD, per seat, billed monthly",
"annual_price": "float — USD, per seat, billed annually",
"seat_limit": "integer or 'unlimited'",
"includes_api_access": "boolean"
}
}
}Remy doesn't write the code. It manages the agents who do.
Remy runs the project. The specialists do the work. You work with the PM, not the implementers.
This takes five minutes to write and saves significant debugging time later.
Step 5: Add a Change Log
A change log is optional but worth including for any bundle that will be updated over time.
## Change Log
- v3.1.2 (2025-05-15): Updated Team plan pricing. Removed discontinued Starter plan.
- v3.1.0 (2025-03-02): Added API access field to pricing table.
- v3.0.0 (2025-01-10): Full rewrite to cover new product tier structure.Agents don’t use change logs directly, but they help the humans maintaining the bundle — and they’re useful when troubleshooting agent behavior after an update.
Packaging and Formatting Your Bundle
Once the content is written, decide on your delivery format based on how the agents will consume it.
Plain Text or Markdown
Best for agents that receive bundles via system prompts or context windows. Markdown structure (headers, lists, code blocks) makes it easier for language models to parse sections correctly. This is the simplest approach and works with nearly any agent framework.
JSON
Best when bundles are stored in a database or accessed via API. JSON is machine-readable, easy to validate, and can be queried programmatically. Combine JSON for the structured data portions with a content field containing Markdown text for prose sections.
Chunked Retrieval Format
If your bundle is large, you’ll need to chunk it for retrieval-augmented generation (RAG). Each chunk should be self-contained enough to be useful in isolation. Avoid chunks that end mid-sentence or require the previous chunk for context.
A practical chunking approach:
- One chunk per major topic section
- Repeat key identifiers (bundle name, version, section name) at the top of each chunk
- Keep chunks under 500 tokens when possible
Proper chunking is what makes large bundles actually retrievable — not just stored.
Deploying the Bundle to AI Agents
Building the bundle is only half the work. Deploying it so agents can actually use it requires a bit more thought.
Option 1: Direct Injection via System Prompt
For small to mid-size bundles (under ~3,000 tokens), paste the bundle directly into the agent’s system prompt or a dedicated context block. This works well for single-agent setups and guarantees the agent always has the knowledge available.
The downside: context window limits. Large bundles pushed into a prompt eat up space that could be used for the conversation.
Option 2: Dynamic Retrieval with RAG
For large bundles or frequently updated content, store the bundle in a vector database (Pinecone, Weaviate, Chroma, or similar) and retrieve relevant chunks at runtime based on the user’s query.
This approach keeps context windows lean and ensures agents always access current information — as long as the vector store is kept up to date. The trade-off is added infrastructure complexity and the occasional retrieval miss if chunks aren’t well-structured.
Option 3: Shared Knowledge Service
For multi-agent workflows, the most scalable approach is treating the bundle as a shared service. Store it in a central location (a database, file store, or API endpoint), and have each agent fetch the bundle — or relevant sections — when needed.
Plans first. Then code.
Remy writes the spec, manages the build, and ships the app.
This is where OKF metadata earns its keep. Agents can query the metadata first: “Is there an active bundle tagged pricing with a last_updated date within the past 30 days?” If yes, fetch and apply. If not, flag for human review.
Versioning Across Agents
One common mistake is updating a bundle without considering which agents are pinned to which version. If Agent A is mid-conversation using v3.1.0 and you push v3.1.2, do you want that agent to switch immediately or finish its session on the old version?
The answer depends on your use case, but the key is to decide in advance and build that logic into your deployment. Version pinning at the agent level is a small design decision that prevents a lot of production headaches.
How MindStudio Handles Knowledge Sharing Across Agents
If you’re managing multiple AI agents — or building workflows where agents hand off work to each other — keeping their knowledge consistent is one of the harder operational problems. MindStudio’s multi-agent workflow builder is designed to address exactly this.
In MindStudio, you can create a dedicated knowledge agent whose sole job is to receive a query, consult a structured knowledge source, and return the relevant answer. Other agents in the same workflow call this knowledge agent as a step — rather than each carrying a full copy of the bundle in their own context.
The result is a single source of truth that every downstream agent draws from. When the knowledge needs updating, you update it in one place.
You can store bundle content in connected data sources — Google Sheets, Airtable, Notion, or a webhook-backed API — and use MindStudio’s 1,000+ integrations to keep that content current. Combine that with MindStudio’s visual workflow builder and you can build a full knowledge refresh pipeline: ingest updated content, re-chunk it, update the store, and notify dependent agents, all without writing infrastructure code.
MindStudio also supports webhook and API endpoint agents, which means you can expose your OKF bundle as an endpoint that any external agent — including ones built in LangChain, CrewAI, or Claude Code — can query using the MindStudio Agent Skills Plugin. You build the bundle once in MindStudio, then share it with any system that can make an HTTP request.
You can start for free at mindstudio.ai.
Common Mistakes to Avoid
Overloading a Single Bundle
A bundle that covers everything covers nothing well. Agents retrieve what’s relevant to the current context — a massive bundle increases noise and retrieval failure. Scope your bundles narrowly and compose them when you need broader coverage.
Skipping Metadata
Metadata feels like overhead when you’re building the first bundle. By the third one, you’ll wish you’d been disciplined about it from the start. Metadata is what lets you search, filter, and manage bundles programmatically.
Not Versioning
Any bundle that will change over time needs version numbers. Even a simple v1, v2 convention is better than nothing. Without versioning, you can’t safely update bundles that agents are actively using.
Writing for Humans Instead of Agents
Human-facing documentation is often vague because humans use context and inference to fill gaps. Agents don’t. Every ambiguity in your bundle is an opportunity for the agent to hallucinate a plausible-sounding answer. Be explicit, even when it feels redundant.
Forgetting Usage Instructions
Content without instructions is just data. Usage instructions are what turn a bundle into a directive. Without them, agents are left to decide on their own how to apply the knowledge — and they will make that decision, often incorrectly.
FAQ
What does OKF stand for in the context of AI agents?
OKF stands for Open Knowledge Format. It refers to a structured approach to packaging knowledge — facts, rules, metadata, and context — in a way that’s portable and machine-readable. The goal is to give AI agents a consistent, well-defined knowledge source they can reliably consume rather than parsing unstructured documents or relying on inconsistent system prompts.
How is an OKF Knowledge Bundle different from a system prompt?
A system prompt is a set of instructions injected at the start of a conversation. An OKF bundle is a separate, structured knowledge object with its own metadata, versioning, and scope definitions. System prompts tell the agent how to behave. OKF bundles tell it what to know. In practice, a bundle can be referenced from within a system prompt, retrieved dynamically via RAG, or served by a dedicated knowledge agent — it’s a more persistent and maintainable artifact than inline prompt text.
Can I share one OKF bundle with multiple AI agents?
Yes, and that’s one of the main reasons to build them. A bundle stored in a shared location — a vector database, a file endpoint, or a knowledge API — can be queried by any agent that has access. In multi-agent workflows, this means all agents operate from the same facts, which reduces inconsistency. You can also version-gate access so different agents use different bundle versions if needed.
What’s the right size for an OKF Knowledge Bundle?
There’s no universal rule, but smaller and more focused is almost always better. A bundle that covers 3–5 related topics with depth is more useful than one that covers 20 topics shallowly. For bundles used in RAG pipelines, individual chunks should stay under 500 tokens for reliable retrieval. For bundles injected directly into context windows, keep the full bundle under 3,000 tokens when possible.
How do I keep bundles up to date across many agents?
The most reliable approach is centralized storage with programmatic updates. Store the authoritative version of your bundle in a single location, and have agents fetch from that location rather than holding their own copies. Combine this with a versioning convention so you can push updates without breaking agents mid-session. For high-velocity content, automated ingestion pipelines that refresh bundle content on a schedule are worth building early.
Do agents need special configuration to use an OKF bundle?
Not necessarily. Any agent that can read text can use a bundle injected into its context window. For more sophisticated setups — dynamic retrieval, version checking, or shared knowledge services — you’ll need to configure retrieval logic or build a small knowledge-layer agent. The bundle format itself is designed to be agnostic to the agent framework, so it works with OpenAI-based agents, Anthropic Claude, LangChain, CrewAI, or custom-built systems.
Key Takeaways
- An OKF Knowledge Bundle packages structured information, metadata, and usage instructions into a portable format that AI agents can consistently consume.
- Bundles separate “what the agent knows” from “how the agent behaves,” making both easier to maintain and update independently.
- Good bundles are narrow in scope, explicit in content, versioned, and include clear usage instructions — not just raw data.
- For multi-agent workflows, centralizing knowledge in a shared bundle eliminates inconsistency and lets you update all agents at once.
- Deploying bundles via a shared knowledge agent or API endpoint is more scalable than injecting copies into every individual agent’s system prompt.
If you’re building workflows with multiple agents, structuring your knowledge as reusable, shareable bundles is one of the highest-leverage investments you can make. Start with one bundle, one agent, and one clear use case — then expand from there. MindStudio makes it straightforward to build the knowledge layer and wire it into multi-agent workflows without managing infrastructure manually. Try it free at mindstudio.ai.
