magnus919_agent-skills/open-knowledge-format/references/bundle-architecture.md

OKF Bundle Architecture

How to structure, organize, and distribute OKF knowledge bundles effectively.

Bundle Distribution

A bundle MAY be distributed as:

• A git repository (recommended) — provides history, attribution, diffs
• A tarball or zip archive of the directory
• A subdirectory within a larger repository

Directory Organization Strategies

Flat structure (small bundles)

For fewer than 10 concepts, a flat directory works:

bundle/
├── index.md
├── customers.md
├── orders.md
├── weekly-active-users.md
└── incident-response.md

Hierarchical structure (medium bundles)

Group by domain or type for bundles with 10-100 concepts:

bundle/
├── index.md
├── tables/
│   ├── index.md
│   ├── customers.md
│   ├── orders.md
│   └── products.md
├── metrics/
│   ├── index.md
│   ├── wau.md
│   └── revenue.md
└── playbooks/
    ├── index.md
    ├── incident-response.md
    └── data-freshness-alert.md

Deeply nested structure (large bundles)

For 100+ concepts, use subdirectories that mirror organizational or system boundaries:

bundle/
├── index.md
├── log.md
├── sales/
│   ├── index.md
│   ├── tables/
│   │   ├── orders.md
│   │   └── customers.md
│   └── metrics/
│       └── revenue.md
└── marketing/
    ├── index.md
    ├── tables/
    │   └── campaigns.md
    └── metrics/
        └── cac.md

Cross-linking Patterns

Linking to a specific concept

See the [customers table](/tables/customers.md) for the join key.

Linking to a subdirectory index

Browse available [metrics](/metrics/index.md).

Linking to an external resource

Defined in the [OpenAPI spec](https://example.com/openapi.yaml).

Linking from a dataset to its constituent tables

The sales dataset contains [orders](/tables/orders.md) and [customers](/tables/customers.md).

Index File Design

An index.md provides progressive disclosure — letting an agent or human see what's available without opening every document.

Root index pattern

# <Bundle Name> Knowledge Base

* [Tables](/tables/index.md) - Database tables reference
* [Metrics](/metrics/index.md) - Business metrics definitions
* [Playbooks](/playbooks/index.md) - Incident response and operational guides

Subdirectory index pattern

# Tables

* [Customers](customers.md) - Customer profile data
* [Orders](orders.md) - Completed customer orders
* [Products](products.md) - Product catalog

Log File Conventions

A log.md records history at any level of the hierarchy:

# Change Log

## 2026-06-18
* **Creation**: Established the sales dataset documentation.
* **Update**: Added revenue metrics with cross-links to orders table.

## 2026-06-15
* **Initialization**: Created bundle structure and index files.

Tips for Agent-Friendly Bundles

1. Always include index.md at the bundle root. Agents use it as an entry point for progressive loading.
2. Prefer absolute (bundle-relative) links starting with /. They survive document moves within subdirectories.
3. Use consistent type values across your bundle. While the spec doesn't require a registry, consistency helps agents route and filter.
4. Write descriptions for every concept. These are what index.md entries and search snippets use.
5. Bundle complementary domains separately. A bundle about "sales data" and one about "incident response" are better as separate bundles than a single flat one.
6. Tag liberally. Tags are the primary cross-cutting categorization mechanism. They enable agent filtering without directory reorganization.