Example library

OKF examples for real knowledge bundles

These examples show how different teams can organize OKF bundles. They are starter patterns, not official conformance tests.

How to read these examples

Each example shows a bundle shape, the fields that matter most, common mistakes, and a practical next step.

Use the structure as a starting point, then adapt file names, tags, and links to your actual content model.

Example

Website content bundle

A marketing and docs team wants agents to answer questions from public website pages without scraping every page from scratch.

Field notes

`index.md` lists the bundle contents for progressive reading.
Each page file uses frontmatter fields for type, title, description, resource, tags, and timestamp.
Markdown links connect pricing, privacy, support, and product documents.

Common mistakes

Copying entire HTML pages instead of clean Markdown summaries.
Missing canonical resource URLs.
Not separating legal pages from product pages.

Recommended next step

Start with the top traffic URLs, then add internal docs only after public pages are stable.

Website content bundle

bundle/
  index.md
  pages/
    home.md
    pricing.md
    privacy.md
  products/
    okf-validator.md
  support/
    contact.md

Example

API endpoint bundle

A developer relations team wants agents to explain endpoints, parameters, limits, and errors.

Field notes

Endpoint files describe one action per concept.
Reference files hold authentication and shared error details.
Cross-links keep repeated rules out of endpoint files.

Common mistakes

Putting every endpoint in one file.
Omitting error responses.
Letting samples drift from the live API reference.

Recommended next step

Generate a draft from OpenAPI, then manually review examples and warnings.

API endpoint bundle

bundle/
  index.md
  api/
    create-customer.md
    update-subscription.md
    list-invoices.md
  references/
    auth.md
    rate-limits.md
    error-codes.md

Example

Product documentation bundle

A docs team wants task pages, reference pages, and troubleshooting notes to stay readable by humans and agents.

Field notes

Concept files define product objects.
Task files explain step-by-step procedures.
Troubleshooting files capture symptoms, causes, fixes, and escalation.

Common mistakes

Blending concept, task, and troubleshooting content.
Skipping prerequisites.
Not documenting who owns the page.

Recommended next step

Map docs IA first, then create one OKF file for each durable topic.

Product documentation bundle

bundle/
  index.md
  concepts/
    workspace.md
    roles.md
  tasks/
    invite-user.md
    import-csv.md
  troubleshooting/
    csv-validation-errors.md

Example

Support playbook bundle

A support team wants agents to route cases, ask for the right evidence, and avoid unsupported promises.

Field notes

Playbooks define trigger, triage steps, boundaries, and escalation.
Policy files hold stable rules that many playbooks reference.
Tags separate refund, security, billing, and account topics.

Common mistakes

Writing agent actions that bypass human approval.
Forgetting negative cases where support must refuse.
Not listing escalation thresholds.

Recommended next step

Review each playbook with policy owners before production agent use.

Support playbook bundle

bundle/
  index.md
  playbooks/
    refund-request.md
    login-lockout.md
    billing-dispute.md
  policies/
    refund-policy.md
    account-security.md

Example

SaaS metrics bundle

A growth or finance team wants consistent definitions for ARR, churn, activation, and usage metrics.

Field notes

Metric files state formula, grain, exclusions, and owner.
Dashboard files explain where numbers appear and how they are filtered.
Table files document upstream data and freshness.

Common mistakes

Publishing a metric without numerator and denominator.
Not marking exclusions.
Using dashboard labels as definitions.

Recommended next step

Create metric OKF files before dashboard OKF files so the dashboard has source definitions.

SaaS metrics bundle

bundle/
  index.md
  metrics/
    arr.md
    logo-churn.md
    activation-rate.md
  dashboards/
    executive-overview.md
  tables/
    subscription-events.md

Example

Knowledge base bundle

An operations team wants a lightweight knowledge base that can be edited in Git and consumed by agents.

Field notes

Runbooks focus on repeatable actions.
Decision files capture why a choice was made.
Reference files hold supporting facts and links.

Common mistakes

Treating OKF as a file dump with no index.
Keeping outdated decisions without timestamps.
Mixing private credentials into agent-readable files.

Recommended next step

Add a review cadence and remove sensitive data before sharing the bundle.

Knowledge base bundle

bundle/
  index.md
  runbooks/
    deploy-checklist.md
    incident-triage.md
  decisions/
    why-static-export.md
  references/
    vendor-contacts.md

Source boundary

This guide is unofficial. It uses public draft references for orientation and adds practical examples for learning.