# OKF (https://openknowledge.ai/docs/plugins/okf) Keep a project portable to Google's Open Knowledge Format with advisory rules, agent-readable schemas, an optional index generator, and a companion skill. The **OKF** project plugin checks whether a knowledge base stays portable to [Google's Open Knowledge Format](https://github.com/GoogleCloudPlatform/open-knowledge-format/blob/main/SPEC.md) v0.2. Findings are advisory warnings and never block a save or an agent edit. > **Beta.** Off until a project enables it. The [Open Knowledge Format starter pack](https://openknowledge.ai/docs/workflows/supporting-open-knowledge-format) enables it while creating an OKF-ready bundle. ## Turn on the plugin Open **Settings → This project → Plugins** and switch on **OKF**. The setting lands in the project's `.ok/config.yml`, so committing it gives every collaborator the same checks. Changes apply immediately, with no restart and no Save button. The plugin's settings page then holds its controls: a recommended agent skill, optional generated indexes, and one switch per rule. ## Install the agent skill The plugin recommends **Open Knowledge Format guidance** (`okf-knowledge-base`), a project skill that helps agents choose document types, preserve provenance, and avoid inventing unsupported metadata. Click **Install skill** to add it. The [starter pack](https://openknowledge.ai/docs/workflows/supporting-open-knowledge-format) installs the same skill, so it may already be present. In that case the page shows **Already in project** and leaves the existing copy untouched. The skill is optional. The plugin's checks are the same with or without it. ## Maintain generated indexes **Maintain index.md** creates and maintains a navigation file in every folder that contains Markdown, listing that folder's documents by type and linking its subfolders. Generated indexes are machine-owned: OpenKnowledge rewrites them as documents change, so manual edits are replaced. Titles, descriptions, folder labels, and type headings render as literal Markdown text; the generated Markdown source backslash-escapes ASCII punctuation in those values. Control characters in those values are replaced with the Unicode replacement character. Parser-reserved Private Use Area code points U+E005–U+E009 and U+E100–U+E103 are also replaced with the Unicode replacement character. Type groups compare single-line, NFC-normalized labels, so whitespace- or normalization-equivalent values share a section while punctuation-distinct values remain separate. Turning the setting on shows a disclosure before any files are written. In a Git project it also adds a scoped `.gitattributes` rule (`merge=union`). A local or CLI merge then combines concurrent index changes instead of conflicting. A merge run on GitHub or GitLab ignores `.gitattributes`, so index changes there can still conflict and need resolving by hand. After a merge across a layout change the combined file can list a document twice until the index is next rebuilt. If another attribute already controls those paths, index maintenance pauses and the plugin page explains what to resolve. Turning it off stops rebuilds and removes the Git rule, but leaves the generated files in place. ## Tune the rules Every rule is on while the plugin is enabled unless you switch it off. Findings report under source `okf` with the rule id as the code (`okf/no-wiki-links`). There are no automatic fixes because each finding needs a content decision. ### Rule reference | Group | Rule | What it checks | | ------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Document structure | `no-wiki-links` | Flags `[[wiki-links]]` outside code because other OKF consumers may render them literally | | Document structure | `log-shape` | Requires real ISO `YYYY-MM-DD` headings in newest-first order in `log.md` | | Document structure | `index-shape` | Requires navigation lists under section headings and links in every `index.md` entry | | Document structure | `reserved-casing` | Flags reserved `Index.md` or `Log.md` filenames that are not lowercase | | Frontmatter | `frontmatter-required` | Requires a non-empty `type` on every non-reserved document | | Frontmatter | `frontmatter-recommended` | Validates the shape of optional `title`, `description`, `resource`, and `tags` fields | | Frontmatter | `frontmatter-provenance` | Validates optional `sources`, `usage_window`, `generated`, `verified`, `status`, and `stale_after` metadata, including the [timestamp shape](https://openknowledge.ai/docs/plugins/okf#provenance-timestamps) | | Frontmatter | `frontmatter-computation` | Requires `runtime` on documents typed `Attested Computation` | | Frontmatter | `frontmatter-reserved-index` | Disallows frontmatter on `index.md`, except at the bundle root | | Frontmatter | `frontmatter-root-index` | Checks the bundle root's quoted `okf_version` value | | Project | `project-no-mdx` | Flags `.mdx` files because OKF consumers scan for `.md` | Reserved filenames match exactly and case-sensitively: `5-index.md` and `notes-log.md` are ordinary documents that need a `type`, and `reserved-casing` catches `Index.md` and `Log.md`. ### Provenance timestamps Every timestamp-valued provenance key is an ISO 8601 datetime carrying an explicit UTC offset, not a calendar date: `stale_after: 2026-12-31T00:00:00Z`. That covers `generated.at`, each `verified[].at`, `stale_after`, each `sources[].last_modified`, and both bounds of a `usage_window`, whether the window is written beside `sources` or inside one entry. A datetime with no offset (`2026-12-31T00:00:00`) is flagged too, so adding a time is not enough on its own. Other OKF consumers may not agree yet. Upstream revised this part of the spec in place under the same v0.2 label, so a checker pinned to the earlier reading still expects a bare `YYYY-MM-DD` for `stale_after` and will flag a document written to the rule above. The declared `okf_version` is `0.2` under both readings, so it cannot tell them apart. Check the consumer you are targeting before treating either spelling as portable. Log entry headings are the exception, and they are governed by a different rule: `log.md` uses plain `YYYY-MM-DD`, checked by `log-shape`. ### Where rules run | Rules | Surfaces | | ------------------------------- | ------------------------------------------------------------------- | | Document structure, Frontmatter | Editor (live), Problems panel → **This doc**, `ok lint`, MCP `lint` | | Project | Problems panel → **Project**, `ok audit`, MCP `audit` | Project rules need the whole file tree, which is why they run only on project-scope surfaces. ## Generated schema files While a frontmatter rule is enabled, OpenKnowledge writes its JSON Schema under `.ok/okf/` so agents can read the exact field contract rather than guess: ```text .ok/okf/required.schema.json .ok/okf/recommended.schema.json .ok/okf/provenance.schema.json .ok/okf/computation.schema.json .ok/okf/reserved-index.schema.json .ok/okf/root-index.schema.json ``` The directory mirrors the rule switches: toggling a rule off deletes its schema, and disabling the plugin removes them all. The files are generated and gitignored. The plugin validates from its own compiled copy and never reads them back, so editing one changes nothing. Tune the rule switches instead. Agent reads advertise the governing schemas through the same channel as [Frontmatter schemas](https://openknowledge.ai/docs/advanced/content-rules/frontmatter). ## Configuration The settings above map to the project config: ```yaml contentRules: okf: enabled: true generate: index: true rules: no-wiki-links: false ``` Omit a rule to leave it on, or set it to `false` to silence only that rule. Unknown rule ids are ignored for forward compatibility, so check the spelling if a disabled rule keeps reporting. Generated indexes stay off unless `generate.index` is explicitly `true`. See the [configuration reference](https://openknowledge.ai/docs/reference/configuration) for the surrounding file shape. ## What the plugin writes | Path | When | Ownership | | ----------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------- | | `.ok/config.yml` | You change a plugin setting | Project configuration, committed when you want to share it | | `.ok/okf/*.schema.json` | The matching frontmatter rule is enabled | Generated and gitignored. Deleted when the rule or plugin is switched off | | `**/index.md` | You opt into generated indexes | Generated. Manual edits are replaced | | `.gitattributes` | Generated indexes are enabled in a Git project | OpenKnowledge manages only its scoped rule | | Project skill directory | You install the recommended skill or seed the OKF pack | Editable project skill | ## See also - [Supporting the Open Knowledge Format](https://openknowledge.ai/docs/workflows/supporting-open-knowledge-format): start a project with the OKF starter pack - [Content rules overview](https://openknowledge.ai/docs/advanced/content-rules/overview): where warnings appear and how editor, CLI, and agent surfaces agree - [Frontmatter schemas](https://openknowledge.ai/docs/advanced/content-rules/frontmatter): validate frontmatter against your own JSON Schema files - [Skills Studio](https://openknowledge.ai/docs/features/skills): project skill installation and editing