okf-builder

An Agent Skills–compatible skill for working with OKF (Open Knowledge Format) v0.1 bundles — directories of markdown files with YAML frontmatter that capture knowledge (metadata, context, and curated insight around data and systems) in a form that is both human- and agent-friendly.

Compatible with: Claude Code, the Claude API Skills API, OpenClaw, and any other Agent Skills–compatible runtime.

📖 OKF spec: GoogleCloudPlatform/knowledge-catalog — okf/SPEC.md

What it does

okf-builder is a procedural playbook for an AI agent. It guides authoring, reading, indexing, logging, and validating OKF bundles without imposing a new schema, registry, or toolchain. Concretely it covers:

• Authoring concepts — picking a type, choosing a path, writing frontmatter, adding cross-links
• Reading & traversal — using index.md for progressive disclosure, tolerating unknown types and broken links
• Index generation — synthesizing index.md from directory contents + frontmatter
• Update logging — appending chronological entries to log.md
• Validation — checking the small set of hard conformance requirements from OKF §10

Repository layout

.
├── SKILL.md                 # The skill procedure (loaded by Agent Skills runtimes)
├── README.md                # This file
├── LICENSE                  # MIT
├── scripts/                 # Level 3 resources — deterministic, run via bash
│   ├── validate.sh              # Hard conformance check against OKF §10
│   ├── regenerate-index.sh      # Synthesize index.md from frontmatter
│   └── check-links.sh           # Find broken bundle-relative links
└── examples/
    └── example-bundle/      # A minimal valid OKF bundle produced by following the skill
        ├── index.md
        ├── log.md
        ├── services/
        │   ├── index.md
        │   └── inventory.md
        └── metrics/
            ├── index.md
            └── daily-active-users.md

Quick start (as a skill)

Claude Code

Drop the repo (or just the SKILL.md + scripts/) into ~/.claude/skills/okf-builder/. Claude Code discovers it automatically.

git clone https://github.com/eli-l/okf-builder.git ~/.claude/skills/okf-builder

Claude API

Upload via the Skills API (/v1/skills endpoints). The skill ships in the standard Agent Skills directory format.

OpenClaw

# from your openclaw workspace
mkdir -p skills
cp -R /path/to/this/repo skills/okf-builder

Triggers

The description frontmatter field lists the phrases that activate the skill. Key triggers:

• "create an OKF bundle" / "add a concept to "
• "validate this OKF bundle" / "is this conformant?"
• "regenerate index.md" / "synthesize an index from frontmatter"
• "log this change to log.md"
• "knowledge catalog", "knowledge base", "agent-readable wiki"

Quick start (the format, not the skill)

An OKF bundle is just a directory of .md files. The minimum viable concept:

---
type: Service
title: Inventory Service
description: Tracks stock levels and reservations for the warehouse.
resource: https://example.com/services/inventory
tags: [inventory, warehouse]
timestamp: 2026-06-14T06:00:00Z
---

# API

| Method | Path             | Purpose            |
|--------|------------------|--------------------|
| `GET`  | `/stock/{sku}`   | Current quantity.  |
| `POST` | `/reservations`  | Reserve N units.   |

Key rules:

• type is the only required frontmatter field
• index.md and log.md are reserved filenames at any directory level
• Prefer bundle-relative links (/services/inventory.md) for move-stability
• Consumers must tolerate unknown types, broken links, and missing optional fields

See SKILL.md for the full procedure, or examples/example-bundle/ for a working bundle.

The example bundle

examples/example-bundle/ contains a tiny but conformant OKF bundle — two concepts in two subdirectories, a root index.md (with okf_version: "0.1"), and a log.md with a couple of entries. You can copy it as a starting point for your own bundle.

Spec compliance

OKF v0.1

okf-builder targets OKF v0.1. The validation workflow (scripts/validate.sh) enforces only the hard requirements from spec §10:

• Every non-reserved .md file has parseable YAML frontmatter
• Every frontmatter has a non-empty type field
• index.md and log.md, when present, follow §6 / §7
• No concept uses a reserved filename

Everything else (missing optional fields, unknown types, broken links, etc.) is treated as soft guidance.

Agent Skills standard

This skill conforms to the Agent Skills format:

• ✅ name and description in YAML frontmatter, third-person, with trigger phrases
• ✅ Body under 500 lines
• ✅ Concise — assumes the agent is already capable
• ✅ Progressive disclosure: SKILL.md is the overview; scripts/ are Level 3 resources that run without entering the context window
• ✅ Consistent terminology throughout
• ✅ No time-sensitive information
• ✅ Concrete examples and copy-paste-runnable scripts

See Authoring best practices for the full standard.

Why markdown + YAML frontmatter?

OKF is intentionally close to several established patterns — Obsidian vaults, Hugo/Jekyll sites, LLM "wiki" repos, "metadata as code" catalogs. By using widely-supported, diff-friendly, tooling-free formats, OKF bundles stay:

• Readable by humans without tooling
• Parseable by agents without bespoke SDKs
• Diffable in version control
• Portable across tools, organizations, and time

License

MIT — see LICENSE.