okf-knowledge-base
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.
git clone --depth 1 https://github.com/inkeep/open-knowledge /tmp/okf-knowledge-base && cp -r /tmp/okf-knowledge-base/packages/server/assets/skills/packs/okf ~/.claude/skills/okf-knowledge-baseSKILL.md
# Open Knowledge Format (OKF) [OKF v0.2](https://github.com/GoogleCloudPlatform/open-knowledge-format/blob/main/SPEC.md) 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.
How to work in a Codebase Wiki project (the `codebase-wiki` starter pack): an agent-authored, source-grounded wiki of the surrounding codebase. Read when the project has a `wiki/` knowledge base with `architecture/`, `modules/`, `flows/`, `concepts/`, and `guides/` sections plus `wiki/OVERVIEW.md`, or when asked to generate or refresh a wiki of this codebase. Carries the per-folder rules and freshness + log discipline, summarizes the audience/depth knobs and source-reference convention, and bundles the full generate/refresh procedure in `references/`. Complements the platform `open-knowledge` skill; does not replace it.
Promote existing research into a stable-status canonical article under `articles/` in a Knowledge Base project (the `knowledge-base` starter pack). Read when a decision has actually been made and the team wants the source-of-truth written down, or when asked to consolidate, canonicalize, promote research, or supersede an older article. Carries the decision-confirmation gate, the `supersedes:` chain that keeps the evidence trail intact, and the canonical voice. Does not conduct new research — that is the sibling `research-with-sources` skill.
Frame a new design proposal (RFC-shape) under proposals/ — problem before solution, named beneficiary and observable change, real alternatives, honest drawbacks, and a live open-questions backlog. Read when asked to frame a proposal, write an RFC, propose a design, pitch a change, draft a PRD-style design doc, or open a design proposal for review. Do NOT read to record a decision after it is accepted (use record-a-decision), to write an implementation spec (use write-a-spec), to write a postmortem (use write-a-postmortem), or to review or critique an existing design (use review-a-design).
How to work in a Knowledge Base project (the `knowledge-base` starter pack). Read when the project has the three-layer source-grounded layout — `external-sources/` → `research/` → `articles/` — or when asked how this project is organized. Carries the layer model, per-folder rules, status flows, and log discipline so this guidance does NOT live inside template bodies or log.md. The three procedures live elsewhere: ingest in the platform `open-knowledge` skill, research and consolidate as their own sibling skills in this pack. Complements the platform `open-knowledge` skill; does not replace it.
How to work in a Plain Notes project (the `plain-notes` starter pack): a flat notes/ folder plus a daily/ journal. The 'I just want to write' layout. Read when the project has these folders, OR when asked to jot a note, capture a quick thought, or write today's journal entry. Carries the linking habit and daily-entry behavior so templates and folder descriptions stay minimal. Complements the platform `open-knowledge` skill; does not replace it.
Authoritative agent-runtime contract for working inside an OpenKnowledge project — a markdown-CRDT knowledge base exposed over MCP. Use whenever reading, listing, searching, editing, or linting any `.md` or `.mdx` file in the project, and before any `mcp__open-knowledge__*` tool call (`exec`, `search`, `write`, `edit`, `lint`, and the rest). Installed by `ok init`, so its presence means this is an OpenKnowledge project and it governs every markdown file here. Covers the read/write tool surface, grounding and linking rules, folder/template conventions, the live browser preview, and the rule that OK's MCP tools — never native file tools — handle in-scope markdown.
Read when the user asks what OpenKnowledge is, wants to install it on a repository, wants to open or preview a single markdown file that is not part of an OpenKnowledge project, wants to share an OpenKnowledge project with collaborators, asks whether OpenKnowledge supports a particular capability, or asks how `ok init` / `ok cowork` / OK Desktop set up a project. Do NOT load to perform OpenKnowledge reads/writes — the runtime guidance for editing markdown inside an initialized OK project ships as a separate project-local skill installed into each detected agent's skills dir (for example `.claude/skills/open-knowledge/`) whenever `ok init` runs.
Use when the user wants to create, author, write, or design a new Agent Skill (a SKILL.md) — for OpenKnowledge or for their editors — including requests like 'help me write a skill', 'make a skill that…', 'turn this workflow into a skill', or improving an existing skill's triggering and discipline. Also use when capturing reusable agent guidance that should live as an installable skill rather than a one-off prompt. Covers choosing scope (project vs global), authoring inside a plugin or skills-distribution repo (write in the repo's own layout, never install), the SKILL.md frontmatter contract, progressive-disclosure structure, evaluating the skill, and installing it into the user's editors.