okf-knowledge-base

inkeep/open-knowledge-skills

Master Open Knowledge Format v0.2 for creating and maintaining portable, agent-readable knowledge bundles.

What is okf-knowledge-base?

This skill provides comprehensive guidance on the Open Knowledge Format (OKF) v0.2 specification—a portable format using Markdown files with YAML frontmatter for structuring knowledge. Use it when authoring, reviewing, or maintaining OKF bundles, responding to okf plugin warnings, or deciding on types, provenance, links, indexes, and logs.

Explains OKF core rules: bundle structure, frontmatter requirements, reserved files (index.md, log.md), and link conventions
Guides authoring decisions: choosing stable types, recording provenance with sources and verification, avoiding false structure
Covers provenance best practices: ISO 8601 timestamps with UTC offsets, claim-level citations, separation of authorship and verification
Provides bundle maintenance workflows: reading indexes, following relevant links, updating concepts, adding dated log entries
Documents the optional okf plugin: write-time warnings, schema validation, link checking, and optional index generation

How to install okf-knowledge-base

npx skills add https://github.com/inkeep/open-knowledge-skills --skill okf-knowledge-base

Prerequisites

OpenKnowledge MCP server configured in your agent host
Familiarity with Markdown and YAML frontmatter syntax
Optional: okf plugin installed for continuous conformance feedback

Claude Code

Cursor

Windsurf

Cline

How to use okf-knowledge-base

1.Review the OKF v0.2 specification and core rules for bundle structure, frontmatter, and reserved files
2.Plan your bundle: decide on concept boundaries, stable types, and provenance sources before authoring
3.Create or update .md files with parseable YAML frontmatter (at minimum, a non-empty type field)
4.Use standard Markdown links for portable relationships between concepts
5.Record provenance: populate sources, generated, verified, and stale_after fields with ISO 8601 timestamps and UTC offsets
6.Run the okf plugin (if enabled) to check for structure, link, and conformance issues
7.Add dated log.md entries (YYYY-MM-DD format) after durable changes to the bundle
8.Maintain index.md files; if using optional index generation, never edit machine-generated indexes

Use cases

Good for

Creating a new OKF bundle to document a domain or product with portable, agent-readable knowledge
Reviewing an existing bundle for conformance with v0.2 structure, frontmatter, and provenance standards
Responding to okf plugin warnings about broken links, missing frontmatter, or reserved-file violations
Migrating legacy knowledge to OKF v0.2, converting old timestamps and citations to the new provenance format
Maintaining a bundle's index.md and log.md files with accurate, dated entries reflecting changes

Who it's for

Knowledge engineers and documentation teams building agent-readable knowledge bases
AI agents (Claude Code, Cursor) with OpenKnowledge MCP server configured
Technical writers and content maintainers updating OKF bundles
Teams adopting portable, standardized knowledge formats for cross-tool compatibility

okf-knowledge-base FAQ

What is the minimum required frontmatter for an OKF concept?

Every non-reserved .md file must have parseable YAML frontmatter with a non-empty string type field. No other field is always required; title, description, and tags are optional and should only be included if they add real information.

How should I format timestamps in OKF metadata?

Write every provenance timestamp as an ISO 8601 datetime with an explicit UTC offset (e.g., 2026-12-31T00:00:00Z). This applies to generated.at, verified[].at, stale_after, and sources[].last_modified. Log.md entry headings use plain YYYY-MM-DD dates instead.

What are reserved filenames in OKF?

index.md and log.md are reserved at every directory level. Use lowercase filenames. An index.md normally has no frontmatter; only the root index may declare okf_version: "0.2". A log.md is newest-first with entry headings starting with ISO dates.

How do I record provenance and sources?

Use sources to list external references with id, url, and last_modified. Use generated to record who produced content (with human: or process: prefixes) and verified to record who confirmed it. Join claim-level citations with matching sources[].id and Markdown footnotes.

What does the okf plugin do?

The optional plugin provides write-time warnings and audits for structure, frontmatter, reserved files, links, and .mdx use. It checks conformance without blocking writes. Schema files in .ok/okf/ define precise field contracts. Optional index generation maintains index.md files (machine-owned, never edit).

Full instructions (SKILL.md)

Source of truth, from inkeep/open-knowledge-skills.

name: okf-knowledge-base description: "Open Knowledge Format (OKF) v0.2 guidance. Use when creating, reading, reviewing, or maintaining an OKF bundle; responding to OpenKnowledge okf plugin warnings; or choosing types, provenance, links, indexes, or logs." compatibility: "Any agent host with the OpenKnowledge MCP server configured. The optional okf plugin provides continuous conformance feedback."

This skill may live inside an OKF bundle, so it carries the required type.

type: Document metadata: plugin: "okf" author: "Inkeep" repository: "https://github.com/inkeep/open-knowledge-skills"

Open Knowledge Format (OKF)

OKF v0.2 is a portable format for agent-readable knowledge: Markdown files, YAML frontmatter, and standard links. The /open-knowledge skill governs tool use; this skill covers OKF semantics.

Core rules

A bundle is a directory tree of .md files. Each non-reserved file is one concept; its path without .md is its ID.
Every concept needs parseable frontmatter with a non-empty string type. No other field is always required.
Types are an open vocabulary. Consumers must accept unfamiliar types and metadata.
Use standard Markdown links for portable relationships. Broken links and a missing index are allowed.
index.md and log.md are reserved at every level. Use lowercase filenames.
An index.md normally has no frontmatter; only the root index may declare okf_version: "0.2".
A log.md is newest-first; entry headings begin with an ISO date — ## YYYY-MM-DD: Summary (the summary after the date is optional; a bare ## YYYY-MM-DD is equally conformant).
OKF consumers read .md, not .mdx.

Authoring judgment

Make each concept the smallest useful link or citation target. Choose a stable, descriptive type; Document is only a generic fallback.
Do not invent facts, relationships, resources, sources, verification, or history. Missing knowledge is better than false structure.
Use title, description, resource, and tags only when they add real information.
Record provenance in sources. Join claim-level citations with matching sources[].id and Markdown footnotes.
Keep authorship and verification separate: generated says who produced content; verified says who confirmed it. Use exact lowercase human: and process: prefixes when applicable.
Write every provenance timestamp as an ISO 8601 datetime with an explicit UTC offset (stale_after: 2026-12-31T00:00:00Z), never a bare date and never an offsetless time. This covers generated.at, verified[].at, stale_after, sources[].last_modified, and both usage_window bounds. A log.md entry heading is different: it stays a plain YYYY-MM-DD date.
Treat status: deprecated and expired stale_after values as trust signals, not validation errors.
For type: Attested Computation, follow the declared runtime and parameters. Do not rewrite the sanctioned computation.

Read and maintain a bundle

Start with the nearest index.md, inspect frontmatter, then follow only relevant links.
Prefer current, verified sources, but tolerate unknown types and incomplete links.
If the bundle conflicts with an assumption, trust the bundle; if it is missing or inconsistent, say so.
Write durable discoveries back to the relevant concept and authored enumerations.
Add a truthful dated log.md entry after durable changes when the bundle uses a log.
Read legacy timestamp and body citations, but prefer v0.2 generated.at and sources when updating a concept. Never invent provenance while migrating.

OpenKnowledge's `okf` plugin

The optional project plugin provides continuous portability feedback without blocking writes:

Write-time warnings and project audits check structure, frontmatter, reserved files, links, and .mdx use.
.ok/okf/*.schema.json contains the precise field contracts. Read these generated files instead of guessing; do not edit them.
Deterministic lint findings establish conformance. Agent judgment still establishes whether metadata is true and useful.
Optional index generation maintains index.md files. Generated indexes are machine-owned: never edit them, because OpenKnowledge replaces their contents.
log.md remains authored, not generated.

The plugin is off by default and each rule can be disabled. Its value is early warning when OpenKnowledge-native content would be misread by another OKF consumer.