{"slug":"okf-open-knowledge-format","title":"okf-open-knowledge-format","summary":"Create, validate, and enrich Open Knowledge Format (OKF) bundles — the open spec for representing organizational knowledge as markdown files with YAML frontmatter. Use when the user mentions 'OKF', 'Open Knowledge Format', 'knowledge bundle', 'OKF bundle', 'create a knowledge bas","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-01T17:44:17.075018Z","repo":{"url":"https://github.com/fabricioctelles/skills","stars":96,"forks":8,"license":"Apache-2.0","updatedAt":"2026-09-22T12:40:47Z"},"bodyHtml":"
\n

name: okf-open-knowledge-format\ndescription: >\nCreate, validate, and enrich Open Knowledge Format (OKF) bundles — the open\nspec for representing organizational knowledge as markdown files with YAML\nfrontmatter. Use when the user mentions 'OKF', 'Open Knowledge Format',\n'knowledge bundle', 'OKF bundle', 'create a knowledge base for agents',\n'validate OKF', 'convert to OKF', 'enrich knowledge docs', 'agent-readable\nknowledge', 'LLM wiki', 'knowledge catalog', 'kcmd', or wants to structure\nknowledge as markdown files for AI agent consumption. Also use when the user\nhas a directory of markdown files and wants to make them interoperable or\nconformant with the OKF standard. Even for simple requests like 'make this\nfolder OKF conformant' — the skill has critical structural rules the agent\nneeds.\nmetadata:\nauthor: ft.ia.br\nversion: \"2.0\"\ndate: 2026-08-25\nrepository: https://github.com/fabricioctelles/skills\nlicense: Apache-2.0\ncategory: library-and-api-reference\nupstream: https://github.com/GoogleCloudPlatform/open-knowledge-format

\n

Open Knowledge Format (OKF)

\n

OKF is a vendor-neutral, open spec (v0.2, released by Google Cloud) for representing knowledge as a directory of markdown files with YAML frontmatter. No SDK required — if you can cat a file, you can read OKF.

\n

It formalizes the \"LLM Wiki\" pattern (Karpathy's gist) into an interoperable format: wikis written by different producers can be consumed by different agents without translation.

\n

v0.2 adds: provenance tracking (sources), trust signals (generated, verified), lifecycle management (status, stale_after), and Attested Computations — a new concept type for sanctioned, verifiable calculations.

\n

For the full spec, see:

\n\n

Design Principles

\n
    \n
  1. Minimally opinionated — Only type is required. The spec defines interoperability surface, not content model.
    2. \n
  2. Producer/consumer independence — Who writes and who reads are decoupled. Human-authored bundles feed agents; LLM-generated bundles are browsed by humans.
    3. \n
  3. Format, not platform — No cloud, SDK, or vendor dependency. Value comes from how many parties speak it.
    4. \n
  4. Trust is first-class — v0.2 makes provenance, verification, and freshness queryable from frontmatter.
    5. \n
\n
\n

Key Terminology

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
TermDefinition
BundleA directory tree of .md files. The unit of distribution (git repo, tarball, or subdirectory).
ConceptOne markdown file = one unit of knowledge (table, metric, playbook, API, etc.)
Concept IDFile path within the bundle, minus .md suffix. Example: tables/users.md → ID tables/users
FrontmatterYAML block between --- delimiters at file top.
BodyEverything after the frontmatter. Standard markdown.
LinkStandard markdown link expressing a relationship between concepts.
SourceA material a concept derives from, recorded in the sources frontmatter field.
ProvenanceThe set of sources a concept derives from.
ActorIdentity string: <producer>/<version> for agents, human:<id> for people, process:<id> for automation.
Trust tierLevel derived from verified: unverified, machine-confirmed, or human-reviewed.
Attested ComputationA concept (type: Attested Computation) carrying a sanctioned way to compute a value.
\n
\n

Quick Reference — Frontmatter Fields

\n

Core Fields (all concepts)

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldRequired?Description
typeYESKind of concept (free-form string, e.g. BigQuery Table, Metric, Playbook, Attested Computation)
titleRecommendedHuman-readable display name
descriptionRecommendedOne-sentence summary
resourceRecommendedURI identifying the underlying asset (omit for abstract concepts)
tagsOptionalYAML list for cross-cutting categorization
\n

Trust & Lifecycle Fields (v0.2)

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldDescription
generated{ by: <actor>, at: <ISO8601> } — Who/what created this content and when
verifiedList of { by: <actor>, at: <ISO8601> } — Who confirmed correctness
statusdraft | stable | deprecated — Default: stable
stale_afterISO 8601 datetime — Content is stale on/after this instant
\n

Provenance Fields (v0.2)

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldDescription
sourcesList of source entries (see below)
usage_window{ from, to } — Time range for usage_count signals
\n

Each sources entry:

\n\n

Attested Computation Fields (v0.2)

\n

For concepts with type: Attested Computation:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldDescription
runtimeREQUIRED. How to run it: bigquery, postgres, dbt, python, Looker
parametersList of { name, type, required } — Typed holes the agent fills
computationPath to computation file (if not inline in body)
executor{ resource, receipt: [...] } — How to run and what evidence to capture
attester{ resource } — Deterministic code that verifies the receipt
\n

Reserved Filenames

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FilePurposeHas frontmatter?
index.mdDirectory listing for progressive disclosureNO*
log.mdChange history, newest firstNO
\n

*Exception: bundle-root index.md MAY have frontmatter with okf_version: \"0.2\".

\n

Conventional Body Headings

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
HeadingWhen to use
# SchemaData assets — describe columns/fields
# ExamplesShow concrete usage (code blocks, queries)
# ComputationAttested Computation — the sanctioned code/query
\n
\n

Actor Convention

\n

Fields that record identity (generated.by, verified[].by, sources[].author) use:

\n\n

Trust tiers are derived from the human: prefix — human-verified > machine-confirmed > unverified.

\n
\n

Trust Tiers

\n

Consumers derive trust from the verified field:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ConditionTrust Tier
No verified keyUnverified
verified by non-human: actors onlyMachine-confirmed
verified by a human:<id> actorHuman-reviewed
\n

Trust tiers are advisory signals, not access control.

\n
\n

Create a Bundle

\n

When the user wants to create an OKF bundle from scratch:

\n

1. Determine scope and structure

\n

Ask: What knowledge are we capturing? (tables, metrics, APIs, playbooks, etc.)\nOrganize into a directory tree that makes sense for the domain.

\n

2. Create concept documents

\n

Each concept = one .md file. Minimal conformant example:

\n
---\ntype: Metric\n---\n\n# Monthly Recurring Revenue (MRR)\n\nSum of all active subscriptions normalized to a monthly amount.\n
\n

Full v0.2 example with provenance and trust:

\n
---\ntype: Metric\ntitle: Monthly Recurring Revenue\ndescription: Sum of all active subscription revenue normalized to monthly.\ntags: [revenue, saas, kpi]\nstatus: stable\ngenerated: { by: human:ftelles, at: 2026-08-25T10:00:00Z }\nverified: { by: human:finance-lead, at: 2026-08-25T14:00:00Z }\nstale_after: 2026-12-31T00:00:00Z\nsources:\n  - id: stripe-docs\n    resource: https://stripe.com/docs/billing/subscriptions\n    title: Stripe Subscription Billing\n    author: team:stripe-docs\n    last_modified: 2026-06-01T00:00:00Z\n---\n\n# Monthly Recurring Revenue (MRR)\n\n## Definition\n\nSum of all active subscriptions normalized to a monthly amount.[^stripe-docs]\nExcludes one-time fees and overages.\n\n## Formula\n\n`MRR = Σ(active_subscription_monthly_value)`\n\n## Related\n\n- [Churn Rate](./churn.md) uses MRR as denominator\n- [ARR](./arr.md) = MRR × 12\n\n[^stripe-docs]: Stripe Subscription Billing\n
\n

For more examples across domains, see references/examples.md.

\n

3. Cross-link concepts

\n

Use standard markdown links. Two forms:

\n\n

Links assert relationships. The kind of relationship is conveyed by surrounding prose, not by the link syntax. Broken links are explicitly permitted — they represent knowledge not yet written.

\n

4. Add provenance with footnotes (v0.2)

\n

When claims reference external sources, use sources in frontmatter and footnotes in body:

\n
sources:\n  - id: ga4-schema\n    resource: https://developers.google.com/analytics/bigquery/export-schema\n    title: GA4 BigQuery Export schema\n
\n
The `events_` table is sharded daily as `events_YYYYMMDD`.[^ga4-schema]\n\n[^ga4-schema]: GA4 BigQuery Export schema\n
\n

5. Generate index.md

\n

Place in any directory for progressive disclosure. No frontmatter. Format:

\n
# Metrics\n\n- [MRR](./mrr.md) - Monthly recurring revenue\n- [Churn](./churn.md) - Monthly churn rate\n- [NPS](./nps.md) - Net Promoter Score\n
\n

Entries should include the description from the linked concept's frontmatter.

\n

6. Generate log.md (optional)

\n

Chronological change history, newest first, ISO 8601 date headings:

\n
# Update Log\n\n## 2026-08-25\n- **Creation**: Added MRR, Churn, and NPS metrics.\n- **Creation**: Established directory structure.\n\n## 2026-08-20\n- **Initialization**: Bundle created.\n
\n

7. Declare version (optional)

\n

Bundle-root index.md may include frontmatter declaring the spec version:

\n
---\nokf_version: \"0.2\"\n---\n\n# My Knowledge Bundle\n\n- [Tables](./tables/) - Database tables\n- [Metrics](./metrics/) - Business KPIs\n
\n

8. Distribution

\n

A bundle can be distributed as:

\n\n

9. Verify conformance

\n

Three rules — all must pass:

\n
    \n
  1. Every non-reserved .md file has parseable YAML frontmatter
    2. \n
  2. Every frontmatter has a non-empty type field
    3. \n
  3. Reserved files (index.md, log.md) follow their defined structure when present
    4. \n
\n
\n

Create an Attested Computation (v0.2)

\n

Attested Computations are concepts that carry not just what a value means but a sanctioned way to compute it. Use them when you need verifiable, reproducible calculations.

\n

When to use

\n\n

Structure

\n
---\ntype: Attested Computation\ntitle: Revenue for fiscal year\ndescription: Recognized revenue for a fiscal year, per Finance's definition.\nstatus: stable\nruntime: bigquery\nparameters:\n  - { name: year, type: integer, required: true }\nexecutor:\n  resource: references/skills/run-on-bq.md\n  receipt: [job_id, executed_sql, result]\nattester:\n  resource: references/attesters/revenue.py\ngenerated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }\nverified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }\nstale_after: 2026-09-23T00:00:00Z\nsources:\n  - id: rev-policy\n    resource: https://wiki.acme/finance/revenue-recognition\n    title: Revenue recognition policy\n---\n\n# Computation\n\n    SELECT SUM(amount) AS revenue\n    FROM finance.recognized_revenue\n    WHERE fiscal_year = @year\n\nThe computation binds only the declared `parameters`, per the recognition\npolicy.[^rev-policy]\n\n[^rev-policy]: Revenue recognition policy\n
\n

Key rules

\n
    \n
  1. Agent fills parameters only — The agent supplies values for declared parameters, never edits the computation itself
    2. \n
  2. Computation can be inline or external — Use # Computation heading for inline, or computation: field for external file
    3. \n
  3. Executor produces receipt — Evidence the attester inspects
    4. \n
  4. Attester is deterministic — No LLM, just code that verifies the receipt
    5. \n
\n

Linking to computations

\n

Other concepts link to Attested Computations:

\n
---\ntype: Metric\ntitle: Revenue\n---\n\n# Definition\n\nRecognized revenue for a fiscal year, computed by \n[the revenue computation](../computations/revenue.md).\n
\n
\n

Validate a Bundle

\n

Preferred: okflint (when available)

\n

okflint is a dedicated Python linter for OKF bundles with 18 rules across 3 tiers (OKF core, profile, hygiene). If installed, always prefer it over the built-in bash script.

\n

Agent behavior: Before validating, check if okflint is installed (command -v okflint). If NOT installed, ask the user:

\n
\n

\"okflint (linter dedicado para OKF com 18 regras, profiles via manifesto e suporte a wikilinks) não está instalado. Quer que eu instale? Opções:

\n
    \n
  1. uv tool install okflint (recomendado, isolado)
    2. \n
  2. pip install okflint
    3. \n
  3. Seguir sem ele (validação básica com o script bash embutido)\"
    4. \n
\n
\n

If the user agrees to install:

\n
# Option 1: uv (recommended — installs isolated, no venv needed)\nuv tool install okflint\n\n# Option 2: pip (installs in current environment)\npip install okflint\n\n# Verify installation\nokflint --version\n
\n

After installation (or if already available):

\n
# Full validation with manifest (if okf-base.yaml exists)\nif [ -f okf-base.yaml ]; then\n  okflint validate --manifest okf-base.yaml ./bundle/\nelse\n  # Core OKF validation only (no manifest needed)\n  okflint validate ./bundle/\nfi\n
\n

okflint advantages over the built-in script:

\n\n

Fallback: built-in bash script

\n

When okflint is not installed, use scripts/validate.sh which checks the 3 core conformance rules plus v0.2 fields.

\n

When asked to validate, check the 3 conformance rules. Report:

\n
✅ PASS: 12/12 concept files have valid frontmatter with type field\n✅ PASS: index.md follows list structure (no frontmatter)\n✅ PASS: log.md uses ISO 8601 date headings, newest first\n\n⚠  WARNING: 3 files missing 'description' field (recommended)\n⚠  WARNING: 2 broken cross-links (permitted but worth noting)\nℹ  INFO: 5 files with trust fields (generated/verified)\nℹ  INFO: 2 Attested Computation concepts found\n
\n

For a script-based check, see scripts/validate.sh.

\n

Errors (conformance failures)

\n\n

Warnings (non-blocking, spec allows these)

\n\n

Consumers MUST NOT reject a bundle because of: missing optional fields, unknown type values, unknown frontmatter keys, broken links, or missing index files.

\n
\n

Enrich Concepts

\n

When the user has existing OKF concepts that need enrichment:

\n

Add schema section

\n

For data assets, add # Schema with a columns table:

\n
# Schema\n\n| Column | Type | Description |\n|--------|------|-------------|\n| `order_id` | STRING | Unique identifier |\n| `customer_id` | STRING | FK to [customers](/tables/customers.md) |\n
\n

Add examples section

\n

For APIs, queries, or tools, add # Examples with fenced code blocks showing usage.

\n

Add provenance (v0.2)

\n

Add sources to frontmatter and footnotes to body for per-claim attribution:

\n
sources:\n  - id: official-docs\n    resource: https://example.com/docs\n    title: Official Documentation\n    author: team:product-docs\n    last_modified: 2026-07-15T00:00:00Z\n
\n

Add trust signals (v0.2)

\n
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-08-25T10:00:00Z }\nverified: { by: human:domain-expert, at: 2026-08-25T14:00:00Z }\nstatus: stable\nstale_after: 2026-12-31T00:00:00Z\n
\n

Add cross-links

\n

Weave links into natural prose. Don't create a standalone \"links\" section — express relationships in context where they're meaningful.

\n

Fill recommended fields

\n

If title, description, tags are missing, add them. Derive values from body content when possible.

\n

Enrichment workflow reference

\n

The official enrichment agent follows this pattern — apply the same logic manually:

\n
    \n
  1. Start with metadata-only docs (just frontmatter + minimal body)
    2. \n
  2. Add schema/structure from source system
    3. \n
  3. Add sources from authoritative documentation
    4. \n
  4. Weave cross-links based on discovered relationships (FKs, shared tags, join paths)
    5. \n
  5. Generate index.md files for progressive disclosure
    6. \n
  6. Add generated and optionally verified for trust tracking
    7. \n
\n
\n

Migrate v0.1 to v0.2

\n

Breaking changes to address

\n
    \n

  1. timestamp → generated.at

    \n
    # v0.1\ntimestamp: 2026-05-28T22:53:05Z\n\n# v0.2\ngenerated: { by: human:author, at: 2026-05-28T22:53:05Z }\n
    \n
    2. \n

  2. # Citations → sources

    \n
    # v0.1 body\n# Citations\n[1] https://example.com/docs\n\n# v0.2 frontmatter\nsources:\n  - id: docs\n    resource: https://example.com/docs\n    title: Example Documentation\n
    \n
    3. \n
\n

Migration script pattern

\n
# For each .md file:\n# 1. Extract timestamp, convert to generated\n# 2. Parse # Citations, convert to sources\n# 3. Add footnotes in body for citations\n\n# Consumers MAY fall back to legacy fields when v0.2 fields absent\n
\n

Backward compatibility

\n

v0.2 consumers SHOULD:

\n\n
\n

Convert Sources to OKF

\n

For detailed conversion guides, see references/conversion.md.

\n

Quick rules

\n

Notion export: Properties → frontmatter. Remove UUID suffixes from filenames. Convert Notion links → relative markdown links.

\n

Obsidian vault: Convert [[wikilinks]] → [title](./file.md). Ensure type field exists. Move inline #tags to frontmatter.

\n

CSV/spreadsheet: Each row = one concept. Map columns to frontmatter fields. First column = filename.

\n
\n

Guardrails

\n
    \n
  1. NEVER invent data. If you don't know the correct type, ask. If you don't have schema info, leave it out. No fabricated URLs or column names.
    2. \n
  2. Preserve unknown fields. OKF explicitly allows extension. Don't delete fields you don't recognize.
    3. \n
  3. Don't impose taxonomy. Type values are free-form strings. Suggest descriptive values but never reject a bundle for having unexpected types.
    4. \n
  4. Broken links are OK. The spec explicitly permits them — they represent not-yet-written knowledge.
    5. \n
  5. Minimal by default. Generate only type (required) + recommended fields that are warranted. Don't pad with empty values.
    6. \n
  6. Ask before assuming. If the domain is unclear, ask what types and structure make sense.
    7. \n
  7. Respect trust hierarchy. Only mark as verified by human: if actually human-reviewed. Don't fabricate verification.
    8. \n
  8. Computation integrity. Never edit the computation in an Attested Computation concept — only fill parameters.
    9. \n
\n
\n

Serve via Google Cloud Knowledge Catalog

\n

Google Cloud's Knowledge Catalog natively ingests OKF bundles and serves them to agents. This is the enterprise path — optional but powerful.

\n

kcmd CLI (Metadata as Code)

\n

kcmd is a bidirectional sync tool between OKF-like local metadata and Knowledge Catalog. Think \"git for metadata.\"

\n
# Initialize from BigQuery dataset\nkcmd init --bigquery-dataset <project>.<dataset>\n\n# Pull current state from catalog\nkcmd pull\n\n# Push local changes\nkcmd push --dry-run\nkcmd push\n
\n

Also ships as an MCP server for agent integration:

\n
{\n  \"mcpServers\": {\n    \"kc-mac\": {\n      \"command\": \"kcmd\",\n      \"args\": [\"mcp\", \"--path\", \"/path/to/root\"]\n    }\n  }\n}\n
\n

MCP tools: pull, push, list-entries, lookup-entry, modify-entry.

\n

Reference Enrichment Agent

\n

The official enrichment agent (Python, ADK, Gemini) auto-generates OKF bundles from BigQuery metadata. Two-pass architecture:

\n
    \n
  1. BQ pass — one OKF doc per table/view from metadata
    2. \n
  2. Web pass — LLM crawls seed URLs and for each page decides to:\n\n
    3. \n
\n

Controls: --web-seed-file, --web-max-pages, --web-allowed-host, --no-web.

\n

Visualizer

\n

The reference agent includes a visualize subcommand that renders any OKF bundle as a self-contained interactive HTML file:

\n
python -m reference_agent visualize --bundle ./bundles/<name>\n
\n

Features:

\n\n

When to mention this to users: If they're enriching BigQuery datasets, point them to the reference agent. If they want enterprise catalog integration, point to kcmd.

\n
\n

Output Format

\n

When creating a bundle, present results as:

\n
    \n
  1. Directory tree showing the full structure
    2. \n
  2. Each file's content in fenced code blocks
    3. \n
  3. Conformance check confirming the bundle passes the 3 rules
    4. \n
  4. Trust summary (v0.2) showing verified/unverified counts
    5. \n
\n
saas-metrics/\n├── index.md\n├── log.md\n├── metrics/\n│   ├── index.md\n│   ├── mrr.md\n│   ├── churn.md\n│   └── nps.md\n└── computations/\n    └── mrr-calculation.md\n
\n

Then show each file, then confirm:

\n
Bundle is OKF v0.2 conformant ✅\n- 4 concept files\n- 1 Attested Computation\n- 3 human-verified, 1 unverified\n- 0 stale concepts\n
\n","files":[{"path":"references/conversion.md","sizeBytes":4230,"isText":true},{"path":"references/examples.md","sizeBytes":15780,"isText":true},{"path":"references/spec-v01.md","sizeBytes":15046,"isText":true},{"path":"references/spec-v02.md","sizeBytes":37743,"isText":true},{"path":"scripts/validate.sh","sizeBytes":8539,"isText":true},{"path":"SKILL.md","sizeBytes":22916,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-14T07:23:14.736567Z","sha256":"7918655FDC2CCA91DFFE8B3EA6A4D9DF2B32BB4913D58A9E0B33D9B5AB7367C1","sizeBytes":38689},"review":null,"source":{"repositoryUrl":"https://github.com/fabricioctelles/skills","path":"skills/okf-open-knowledge-format","license":"Apache-2.0","commit":"3b8da2cc1d5d13da7142560433b46b7ec3fc6988","subtreeSha":"B9C39DA717FB745A98A2D840E661965CB22330C95B9F56B6CEE29FC1908DF1A7","lastSyncedAt":"2026-09-26T23:11:53.149345Z"},"reviewedAt":"2026-09-14T07:23:32.838126Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/fabricioctelles/skills/tree/main/skills/okf-open-knowledge-format"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install fabricioctelles-skills@llmmart"},{"target":"git","command":"git clone https://github.com/fabricioctelles/skills.git"}]}