Bootstrap an Opinionated Knowledge Base

okf-schema provides okfkb CLI entry point (alias to okf-schema kb) that scaffolds and manages a specific kind of OKF bundle: an opinionated knowledge base designed for agent-driven findings traceability. This guide walks through creating, populating, and integrating one into a project.

Prerequisites

Install okf-schema:

uv tool install okf-schema

Verify the okfkb entry point is available:

okfkb --help

Step 1 — Scaffold the KB

okfkb init my-project/knowledge/

This creates the canonical layout inside my-project/knowledge/:

knowledge/
├── _schema/          # 10 bundled JSONSchema files
├── concepts/
├── experiments/
├── findings/         # ← where new-finding writes files
├── guides/
├── hypotheses/
├── outcomes/
├── principles/
├── reference/
├── structures/
├── index.md          # table of contents
└── log.md            # chronological changelog

If the directory already exists and is non-empty, use --force:

okfkb init my-project/knowledge/ --force

Step 2 — Record your first Finding

A Finding is an immutable, dated observation. Use new-finding to generate a schema-valid file:

okfkb new-finding my-project/knowledge/ \
  --title "Redis eviction rate spikes under load" \
  --confidence medium \
  --context "Observed during load test at 800 RPS; eviction_ratio hit 0.94."

This writes findings/2026.07.04-14.30-redis-eviction-rate-spikes-under-load.md with all required OKF frontmatter pre-filled.

Open the file and complete the Observation, Evidence, and Implications sections.

# Optional: add tags for better searchability
okfkb new-finding my-project/knowledge/ \
  --title "TLS handshake timeout" \
  --confidence high \
  --context "mTLS timeout under IPv6 on GKE cluster." \
  --tags "tls,network,timeout"

Step 3 — Refresh index and validate

After adding files, update the cross-link index and check conformance:

okf-schema update --path my-project/knowledge/
okf-schema validate --strict --path my-project/knowledge/

  • update (alias to okf-schema index + okf-schema lint) scans all markdown files, computes backlinks, updates index.md, and normalises YAML frontmatter.

  • validate --strict checks all files against the bundled schemas.

Step 4 — Install KB tooling into your project

install-skills deploys the bundled record-finding and consolidate-knowledge-base agent skills, plus the knowledge-base.guidelines.md guideline, into the project’s .agents/ directory:

okfkb install-skills my-project/

It also creates or patches my-project/AGENTS.md with a reference to the installed guideline, so coding agents pick it up automatically.

Typical workflow

day 1   okfkb init knowledge/
day 2+  okfkb new-finding knowledge/ --title "..." --confidence medium --context "..."
        # edit the generated file to fill in Observation / Evidence / Implications
        okfkb update --path knowledge/
        okfkb validate --strict --path knowledge/
        git add knowledge/ && git commit -m "docs: record finding ..."

Next steps