| name | okf-knowledge-format |
| description | Author and validate knowledge as OKF (Open Knowledge Format) bundles — a directory of markdown files with YAML frontmatter, where every concept is one .md file with a REQUIRED `type` field, reserved index.md/log.md files, bundle-relative cross-links, and a permissive conformance model. Use when standing up or maintaining a knowledge bundle/catalog, writing or normalizing a concept document's frontmatter, deciding how to structure markdown knowledge for agents to consume, or checking a corpus against OKF conformance. The canonical spec is vendored under reference/SPEC.md and refreshed from GitHub via scripts/update-spec.sh. |
| version | 0.5.0 |
| metadata | {"type":"skill","layer":"procedural","tags":["documentation","knowledge-format","okf","frontmatter","metadata","conformance"]} |
OKF — Open Knowledge Format
Represent knowledge as an OKF bundle: a directory tree of UTF-8 markdown files with YAML frontmatter, designed to be read by humans, written by agents, and exchanged across organizations with no required tooling. "If you can cat a file, you can read OKF." This skill is the repo's standard for how knowledge markdown is structured — frontmatter shape, reserved files, cross-links, and conformance.
The authoritative rules live in the vendored spec at reference/SPEC.md (OKF v0.1). This SKILL.md is the operational summary; when a detail is ambiguous, open reference/SPEC.md and follow it.
Provenance — not ours. OKF is a published, vendor-neutral standard from Google Cloud Platform (OKF v0.1, 2026-06-12), not a format coined in this repo. We adopt and vendor it (reference/SPEC.md is refreshed from upstream via scripts/update-spec.sh). Source: GOOGLE CLOUD PLATFORM, Open Knowledge Format — Specification v0.1 — full citation in ../../references/prior-art-landscape.md.
Hard rules (these define conformance — §9)
- Every non-reserved
.md file has a parseable YAML frontmatter block delimited by --- on its own line at the top and a closing ---.
- Every frontmatter block has a non-empty
type field. type is the only required field. Everything else is optional.
- Reserved filenames are reserved.
index.md (directory listing, §6) and log.md (update history, §7) must follow their defined structure and must not be used for concept documents.
index.md carries no frontmatter — the sole exception is the bundle-root index.md, which MAY declare okf_version: "0.1" (§11).- Consume permissively. Never reject a bundle for missing optional fields, unknown
type values, unknown extra keys, broken cross-links, or a missing index.md. OKF stays useful as bundles grow and get partially agent-generated.
When to invoke
- Standing up a new knowledge bundle/catalog, or organizing existing markdown knowledge into one.
- Writing a concept document or normalizing its frontmatter → start from
templates/concept.md.
- Adding or regenerating a directory
index.md → templates/index.md; or a log.md → templates/log.md.
- Deciding how to cross-link concepts, cite sources, or name a
type.
- Checking a corpus for OKF conformance (the four hard rules above).
- Refreshing the vendored spec from upstream →
scripts/update-spec.sh (see "Keeping the spec current").
Core model (§2)
| Term | Meaning |
|---|
| Knowledge Bundle | Self-contained directory tree of knowledge docs — the unit of distribution (git repo, archive, or subdir). |
| Concept | One unit of knowledge = one markdown document. May describe a tangible asset (table, API) or an abstract idea (metric, process). |
| Concept ID | The file path within the bundle minus .md. tables/users.md → tables/users. |
| Frontmatter | YAML metadata block at the top of the file. |
| Body | Everything after the frontmatter. |
| Link | A markdown link asserting a relationship; its kind comes from surrounding prose, not the link. |
| Citation | A link to an external source backing a claim. |
Frontmatter fields (§4.1)
---
type: <Type name>
title: <Display name>
description: <One-sentence summary># Recommended — feeds index/search/previews
resource: <Canonical URI>
tags: [<tag>, <tag>]
timestamp: <ISO 8601 datetime>
---
type values are not centrally registered — pick descriptive, self-explanatory strings; consumers treat unknown types as generic concepts.- Producers MAY add any extra keys; consumers SHOULD preserve unknown keys and never reject on them.
Conventional body headings (§4.2)
There are no required body sections. Favor structural markdown (headings, tables, lists, fenced code) over prose. Use these headings when applicable: # Schema (asset columns/fields), # Examples (usage, often code blocks), # References (external sources, §8).
Bundle structure (§3)
bundle/
├── index.md # optional directory listing (progressive disclosure)
├── log.md # optional update history
├── <concept>.md # a concept at the root
└── <subdir>/
├── index.md
└── <concept>.md
Directory layout is domain-independent — organize concepts however the knowledge wants. Reserved files (index.md, log.md) may appear at any level.
Cross-linking (§5)
- Absolute (bundle-relative), recommended: start with
/, stable across moves — [customers](/tables/customers.md).
- Relative: standard markdown paths —
[other](./other.md).
- A link is an untyped directed relationship; the kind (joins-with, depends-on, references) lives in the prose. Broken links are tolerated (not-yet-written knowledge).
References (§8)
List external sources under a trailing # References heading, numbered. Links MAY be absolute URLs, bundle-relative paths, or paths into a references/ subdirectory that mirrors external material as first-class concepts.
Procedure
Author a concept
- Copy
templates/concept.md. Set a non-empty, descriptive type (hard rule 2).
- Fill recommended fields (
title, description, and resource if it maps to a real asset). Add tags/timestamp if useful.
- Write the body in structural markdown; use
# Schema/# Examples where they fit. Cross-link with bundle-relative /… paths.
- Add a
# References section for any externally-sourced claim.
Maintain a directory
- Keep
index.md listing the directory's concepts, descriptions mirroring each concept's frontmatter description (templates/index.md).
- If the scope tracks history, append a dated entry to
log.md (newest first, ISO 8601 dates — templates/log.md).
- Declare
okf_version: "0.1" in the bundle-root index.md frontmatter only.
Check conformance
Walk the four hard rules: every non-reserved .md has parseable frontmatter; every block has non-empty type; reserved files follow §6/§7; root index.md is the only index.md with frontmatter.
Keeping the spec current
The spec is vendored (verbatim) at reference/SPEC.md with provenance in reference/SPEC.source.md. To pull the latest from GitHub:
skills/okf-knowledge-format/scripts/update-spec.sh
skills/okf-knowledge-format/scripts/update-spec.sh v0.2
The script overwrites reference/SPEC.md, rewrites reference/SPEC.source.md (URL, ref, retrieval time, sha256), and reports whether the content changed. If it changed, review the diff and reconcile the Hard rules / field tables above before committing — this SKILL.md must not drift from the vendored spec. The vendored copy is the offline source of truth; the script is the only sanctioned way to update it.
Notes
type is the single point of required structure. When unsure whether something belongs in frontmatter or body: identifying/routing metadata → frontmatter; explanation and evidence → body.- OKF references domain schemas (Avro, Protobuf, OpenAPI) rather than replacing them — link out, don't inline a competing schema.
- Relationship to living-docs: that skill governs a repo's internal doc system (ADR/PRD/BDR/constitution) and its no-drift discipline; OKF is the portable, exchange-oriented format for knowledge bundles. Use OKF when the knowledge is a catalog meant to be consumed by agents or shared across orgs; use living-docs conventions for in-repo decision/requirement records. They compose: a living-docs
docs/context/ or research corpus can be authored as an OKF bundle so its frontmatter and indexing are spec-conformant.
