open-knowledge-format

name

open-knowledge-format

description

Author, validate, index, and visualize Open Knowledge Format (OKF) knowledge bundles — directories of markdown files with YAML frontmatter that both humans and AI agents read. Use this whenever the user wants to build, enrich, browse, or convert a knowledge base / knowledge bundle / "OKF" for a dataset, codebase, paper, API, or domain; capture durable knowledge as portable markdown; or produce a knowledge graph that an agent can consume. Triggers on "OKF", "open knowledge format", "knowledge bundle", "knowledge catalog", "build a knowledge base for X", "enrich/document this dataset as markdown".

Open Knowledge Format (OKF)

OKF is an open, vendor-neutral format for representing knowledge — the metadata, context, and curated insight that surrounds data, systems, papers, and domains. A bundle is just a directory of markdown files with YAML frontmatter. No schema registry, no central authority, no required tooling: if you can cat a file you can read it, if you can git clone a repo you can ship it.

This skill replicates the producer/consumer tooling from Google Cloud's OKF reference implementation (the knowledge-catalog repo) as a Claude-Code-native plugin: instead of a Gemini/ADK enrichment agent, you are the enrichment agent, and the bundled Python scripts give you deterministic validation, indexing, and visualization.

Read the full normative spec at ${CLAUDE_PLUGIN_ROOT}/skills/open-knowledge-format/SPEC.md before authoring a bundle for the first time, or when in doubt about a rule. This file is the working playbook; SPEC.md is the source of truth.

The model in one minute

• Bundle — a directory tree of markdown files. The unit of distribution.
• Concept — one markdown file = one unit of knowledge (a table, an API, a metric, a paper, a method, a playbook…).
• Concept ID — the file path minus .md. concepts/gxd.md → concepts/gxd.
• Frontmatter — YAML block at the top, delimited by ---. The only required field is type. title, description, resource, tags, timestamp are recommended.
• Body — markdown after the frontmatter. Favor structure (headings, tables, lists, fenced code) over prose.
• Link — a normal markdown link from one concept to another. Links make the bundle a graph, not just a tree. The kind of relationship lives in the surrounding prose, not the link.
• Reserved files — index.md (progressive-disclosure directory listing, no frontmatter) and log.md (chronological change history). Never use these names for concepts; the tooling generates index.md for you.

When to use this skill

Use it whenever the user wants to capture, exchange, or browse knowledge as portable files: build a knowledge base for a dataset/codebase/paper/API/domain, "enrich" or document something as markdown, or turn an existing bundle into a browsable graph. If the user names "OKF" or "knowledge bundle", this is definitely the skill.

Authoring workflow (you are the enrichment agent)

1. Scope the bundle. Decide the root directory and a directory layout that fits the domain. Layout is free-form — organize by whatever grouping is natural (tables/, datasets/, references/; or paper/, concepts/, methods/, references/). Subdirectories group related concepts.

2. Gather source material. Read the dataset schema, the codebase, the paper, the API docs — whatever the knowledge is about. Use web fetches for external sources. Capture concrete facts (field names, formulas, equations, results, citations), not hand-waving.

3. Write one concept per file. For each concept, write a .md file with:

   • Frontmatter: always type; add title, description (ONE tight sentence — it is reused verbatim in index.md), tags (YAML list), resource (canonical URI when the concept maps to a real asset/paper), and leave timestamp out (validation tolerates it; set it if you want an explicit ISO-8601 value).
   • Body: a short prose description first, then structural sections. Conventional headings (use when applicable): # Schema, # Examples, # Citations. Domain-specific headings are encouraged (# Method, # Results, # Definition, # Relationships, …).

4. Cross-link as you write. When prose references another concept, link to it. Prefer absolute bundle-relative links beginning with / (e.g. [GXD](/concepts/gxd.md)) — they are stable when files move and the bundled viewer rewires them to in-app navigation. Relative links (../concepts/x.md) also work. Only link to concepts that exist (or will exist) in the bundle; don't invent targets. One link per mention per section is enough — don't over-link, and don't link inside headings or fenced code.

5. Cite sources. When the body makes claims from external material, list them under a trailing # Citations heading, numbered: [1] [Title](https://…). Cite only sources you actually used; never invent URLs. External works worth treating as first-class nodes get their own concept under references/ with type: Reference and resource set to the source URL — then cross-link to them.

6. Generate indexes. Run the index command/script so every directory gets a progressive-disclosure index.md. Never hand-write index.md; it is generated from concept frontmatter.

7. Validate. Run the validate command/script. Fix HARD errors (missing type, unparseable frontmatter). Warnings (missing recommended fields, broken cross-links, missing index) are soft — address them when they represent real gaps, but a bundle with broken links is still conformant (links may point at not-yet-written knowledge).

8. Visualize (optional). Generate the self-contained viz.html to browse the bundle as an interactive force-directed graph.

Frontmatter template

---
type: <Concept type>            # REQUIRED, e.g. "Paper", "Method", "Metric", "Reference", "BigQuery Table"
title: <Human-readable name>    # recommended
description: <One sentence>      # recommended — reused verbatim in index.md
resource: <Canonical URI>        # when the concept maps to a real asset (omit for abstract ideas)
tags: [<tag>, <tag>]            # recommended
timestamp: <ISO 8601>           # optional last-modified time
---

type values are not registered anywhere — pick descriptive, self-explanatory strings. Consumers tolerate unknown types. You MAY add any extra frontmatter keys; consumers preserve and ignore unknown ones.

Conformance rules (what validation enforces)

A bundle is conformant (OKF v0.1) when:

1. Every non-reserved .md file has a parseable YAML frontmatter block.
2. Every frontmatter block has a non-empty type.
3. index.md / log.md follow their conventional structure when present.

Everything else is soft guidance. Consumers MUST NOT reject a bundle for missing optional fields, unknown types, unknown extra keys, broken links, or missing index files.

Bundled tooling

All scripts are pure Python (only dependency: PyYAML) under ${CLAUDE_PLUGIN_ROOT}/scripts/. Invoke directly with python3:

Script	Purpose
okf_validate.py <bundle> [--strict] [--json]	Conformance check (errors + warnings).
okf_index.py <bundle>	(Re)generate index.md in every directory.
okf_visualize.py <bundle> [--out f.html] [--name "T"]	Self-contained interactive HTML graph viewer.
okf_lib.py	Importable library (parse/serialize/validate/paths/index).

The slash commands /okf:create, /okf:index, /okf:validate, and /okf:visualize wrap these for convenience.

Quality bar

• Be concrete: real field names, real formulas/equations (fenced or inline), real results, real citations. Never invent data, fields, or URLs.
• One sentence descriptions. They drive the whole index.md experience.
• Structural markdown over prose walls.
• Cross-link generously but meaningfully — the graph is the point.
• No preamble or reasoning narration inside document bodies; bodies must be clean markdown ready for direct human/agent consumption.