Skip to content

Your First OKF Bundle in 5 Minutes

You’ll walk out of here with a working OKF bundle. The example: a knowledge package about SaaS metrics — MRR, churn, and NPS. Three interconnected concepts, an index, a log. The kind of thing an AI agent can read, navigate, and use to give you real answers.

What’s a bundle? Ten seconds.

A folder with .md files. Each file is a concept. Every concept has YAML frontmatter with at least a type field. Done. That’s OKF.

No SDK, no schema registry, no build step. If cat works, OKF works.

Final structure

This is what we’re putting together:

saas-metrics/
├── index.md          ← lists what's in the bundle
├── log.md            ← change history
├── mrr.md            ← concept: Monthly Recurring Revenue
├── churn.md          ← concept: Churn Rate
└── nps.md            ← concept: Net Promoter Score

Flat. No subfolders. For a small bundle, you don’t need more.

Step 1 — Create the folder

mkdir saas-metrics && cd saas-metrics

Step 2 — First concept: MRR

Create mrr.md:

---
type: Metric
title: MRR — Monthly Recurring Revenue
description: Normalized monthly recurring revenue. The financial heartbeat of any SaaS.
tags: [revenue, saas, finance]
timestamp: 2026-06-13T10:00:00Z
---

MRR is the sum of all recurring revenue normalized to one month. Excludes one-time fees, services, or one-off discounts.

# Formula

MRR = Σ (monthly value of each active subscription)


# Variations

| Type | What it measures |
|------|-----------------|
| New MRR | Revenue from new customers |
| Expansion MRR | Upgrades and add-ons |
| Contraction MRR | Downgrades |
| Churned MRR | Revenue lost to cancellations — see [churn](./churn.md) |

# Relationship to other concepts

- Churn hits MRR directly. Details at [churn rate](./churn.md).
- [NPS](./nps.md) is a leading indicator: NPS dropping today = MRR dropping in 60–90 days.

# Citations

[1] [SaaS Metrics 2.0 — David Skok](https://www.forentrepreneurs.com/saas-metrics-2/)

Notice the cross-links — [churn](./churn.md) and [NPS](./nps.md). Relative links between concepts at the same level. That’s the OKF knowledge graph.

Step 3 — Second concept: Churn

Create churn.md:

---
type: Metric
title: Churn Rate
description: Percentage of customers (or revenue) lost over a given period.
tags: [retention, saas, health]
timestamp: 2026-06-13T10:00:00Z
---

Churn is the metric nobody wants to look at but everybody needs. It measures how fast you're losing customers or revenue.

# Formulas

**Logo churn (customers):**

Churn Rate = (customers lost in period / customers at start of period) × 100


**Revenue churn:**

Revenue Churn = churned MRR / MRR at start of month × 100


Revenue churn is more honest. One enterprise customer canceling hurts more than ten freemium accounts.

# Benchmarks

| Stage | Acceptable monthly churn |
|-------|-------------------------|
| Early-stage | < 5% |
| Growth | < 3% |
| Scale | < 1% |

# Relationship to other concepts

- Churn destroys [MRR](./mrr.md). Negative net MRR = company dying slowly.
- [NPS](./nps.md) detractors (0–6) are churn candidates. Track the correlation.

# Citations

[1] [What is Good SaaS Churn Rate — Lenny Rachitsky](https://www.lennysnewsletter.com/p/what-is-good-retention-rate)

Step 4 — Third concept: NPS

Create nps.md:

---
type: Metric
title: NPS — Net Promoter Score
description: Score from -100 to 100 measuring likelihood of product recommendation.
tags: [satisfaction, saas, product]
timestamp: 2026-06-13T10:00:00Z
---

NPS asks one thing: "from 0 to 10, how likely are you to recommend us?" Simple, imperfect, but universally comparable.

# Formula

NPS = % promoters (9-10) − % detractors (0-6)


Passives (7–8) don't enter the calculation. They exist but they're invisible. Like that colleague who never comments on code reviews.

# Segmentation

| Group | Score | Meaning |
|-------|-------|---------|
| Promoters | 9–10 | Evangelists. They bring referrals. |
| Passives | 7–8 | Satisfied but vulnerable to competitors. |
| Detractors | 0–6 | [Churn](./churn.md) risk. Can generate negative noise. |

# Relationship to other concepts

- Detractors become churn. Correlate NPS by cohort with [churn rate](./churn.md).
- Falling NPS is an early warning of [MRR](./mrr.md) impact.

# Citations

[1] [The One Number You Need to Grow — HBR](https://hbr.org/2003/12/the-one-number-you-need-to-grow)

Step 5 — index.md

The index is your bundle’s table of contents. No frontmatter — reserved file. Just lists contents with links and short descriptions.

Create index.md:

# SaaS Metrics Bundle

Core metrics for SaaS companies.

## Metrics

* [MRR — Monthly Recurring Revenue](./mrr.md) - Normalized monthly recurring revenue
* [Churn Rate](./churn.md) - Percentage of customers/revenue lost per period
* [NPS — Net Promoter Score](./nps.md) - Recommendation score (-100 to 100)

Step 6 — log.md

The log is your changelog. Most recent entries first. Grouped by ISO 8601 date.

Create log.md:

# Bundle Update Log

## 2026-06-13

* **Creation**: Initial bundle with three core SaaS metrics.
* **Creation**: Added [MRR](./mrr.md) with formulas and variations.
* **Creation**: Added [Churn Rate](./churn.md) with benchmarks by stage.
* **Creation**: Added [NPS](./nps.md) with segmentation and correlations.

Quick validation

Your bundle is OKF v0.1 conformant if:

  1. ✅ Every .md that isn’t index.md or log.md has parseable YAML frontmatter
  2. ✅ Every frontmatter has a type field filled in
  3. ✅ index.md and log.md follow the structure defined in the spec

Those three checks. That’s it. The rest (title, description, tags, timestamp) is recommended but won’t break conformance.

What you just built

A navigable knowledge graph. Any agent that understands markdown + YAML can:

  • List concepts via index.md
  • Understand each concept’s kind via type
  • Navigate relationships via cross-links
  • Check history via log.md

You don’t need anything beyond a text editor and git. No database, no API, no vendor lock-in. Knowledge stays as portable as a repo.

Next steps

  • Add subfolders when the bundle grows (operational/, financial/, product/)
  • Put resource: in frontmatter when a metric has a real dashboard attached
  • Version with git — each commit is a snapshot of knowledge state
  • Run the validator at okf.md to check conformance

Actual time spent: probably under 5 minutes. If it took longer, blame your editor, not the format.