okf-knowledge-base

# Open Knowledge Format (OKF) [OKF v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/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 `## YYYY-MM-DD: Summary`. - 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. - 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.