feat(okf): add Open Knowledge Format plugin with author and refactor skills (#77)

Add the `okf` plugin for the Open Knowledge Format (OKF) v0.1 — a
vendor-neutral format representing knowledge as markdown files with YAML
frontmatter.

- skills/okf: author, init, and validate OKF bundles; bundles the OKF v0.1
  SPEC.md as an offline reference and a stdlib-only validate_okf.py.
- skills/okf-refactor: convert existing notes/docs/catalog exports into a
  conformant, cross-linked OKF bundle.
- Register in Claude and Codex marketplace manifests.

Co-authored-by: duyetbot <duyetbot@users.noreply.github.com>

Author: duyet

.agents/plugins/marketplace.json

@@ -267,6 +267,18 @@
         "authentication": "ON_INSTALL"
       },
       "category": "Productivity"
+    },
+    {
+      "name": "okf",
+      "source": {
+        "source": "local",
+        "path": "./okf"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
     }
   ]
 }

.claude-plugin/marketplace.json

@@ -108,6 +108,11 @@
       "name": "kb",
       "source": "./kb",
       "description": "Knowledge base maintenance skills. Consolidate, dedupe, prune, refresh, and forget notes in a markdown KB."
+    },
+    {
+      "name": "okf",
+      "source": "./okf",
+      "description": "Open Knowledge Format (OKF) tooling. Author, initialize, validate, and refactor knowledge into vendor-neutral OKF v0.1 bundles: markdown files with YAML frontmatter."
     }
   ]
 }

marketplace.json

@@ -186,6 +186,14 @@
       "version": "1.0.0",
       "type": "skill",
       "category": "productivity"
+    },
+    {
+      "name": "okf",
+      "id": "okf@duyet-claude-plugins",
+      "description": "Open Knowledge Format (OKF) tooling. Author, initialize, validate, and refactor knowledge into vendor-neutral OKF v0.1 bundles: markdown files with YAML frontmatter.",
+      "version": "1.0.0",
+      "type": "skill",
+      "category": "productivity"
     }
   ],
   "metadata": {

okf/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "okf",
+  "version": "1.0.0",
+  "description": "Open Knowledge Format (OKF) tooling. Author, initialize, validate, and refactor knowledge into vendor-neutral OKF v0.1 bundles: markdown files with YAML frontmatter.",
+  "author": {
+    "name": "duyet",
+    "url": "https://github.com/duyet"
+  },
+  "homepage": "https://github.com/duyet/codex-claude-plugins",
+  "repository": "https://github.com/duyet/codex-claude-plugins",
+  "license": "MIT"
+}

okf/.codex-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "okf",
+  "version": "1.0.0",
+  "description": "Open Knowledge Format (OKF) tooling. Author, initialize, validate, and refactor knowledge into vendor-neutral OKF v0.1 bundles: markdown files with YAML frontmatter.",
+  "author": {
+    "name": "duyet"
+  },
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Open Knowledge Format",
+    "shortDescription": "Author, validate, and refactor knowledge into OKF v0.1 bundles (markdown + YAML frontmatter).",
+    "developerName": "duyet",
+    "category": "productivity",
+    "capabilities": ["Skill"],
+    "links": {
+      "homepage": "https://github.com/duyet/codex-claude-plugins"
+    }
+  }
+}

okf/README.md

@@ -0,0 +1,61 @@
+# okf
+
+Tooling for the **Open Knowledge Format (OKF)** — a vendor-neutral way to represent
+knowledge as plain markdown files with YAML frontmatter, organized in a directory
+hierarchy. A bundle is just a directory: version-controllable, portable, lock-in
+free, and readable by humans, LLMs, and any tool that speaks markdown (Obsidian,
+Notion, MkDocs, a static file server, a search index, a graph viewer).
+
+Spec: [OKF v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+— bundled verbatim at `skills/okf/reference/SPEC.md` so the agent is grounded
+offline.
+
+## Skills
+
+- **okf** — author, initialize, and validate OKF bundles. Scaffolds the correct
+  layout, writes concept docs with proper frontmatter, generates `index.md` /
+  `log.md`, and ships `validate_okf.py` for OKF v0.1 conformance checks.
+- **okf-refactor** — convert existing knowledge (loose notes, wikis, README/docs,
+  a catalog/metadata export, a database schema) into a conformant OKF bundle:
+  one concept per file, cross-linked into a knowledge graph, with generated indexes.
+
+## Install
+
+```bash
+/plugin marketplace add duyet/codex-claude-plugins
+/plugin install okf@duyet-claude-plugins
+```
+
+Alternative ([skills.sh](https://skills.sh)):
+
+```bash
+npx skills add duyet/codex-claude-plugins
+```
+
+## Usage
+
+```text
+# Initialize a fresh bundle
+okf init an OKF bundle at ./bundles/my_catalog
+
+# Author a concept
+okf add a BigQuery Table concept for the orders table
+
+# Validate conformance
+python3 skills/okf/scripts/validate_okf.py ./bundles/my_catalog
+
+# Refactor existing knowledge into OKF
+okf-refactor convert ./notes into an OKF bundle at ./bundles/notes
+```
+
+## What conformance means (OKF v0.1)
+
+1. Every non-reserved `.md` file has parseable YAML frontmatter.
+2. Every frontmatter block has a non-empty `type`.
+3. Reserved files (`index.md`, `log.md`) follow their structure and carry no
+   frontmatter — except the bundle-root `index.md`, which may declare
+   `okf_version: "0.1"`.
+
+Consumers are required to tolerate unknown types, unknown keys, broken links, and
+missing indexes — so producing OKF is forgiving, and these skills aim to produce
+the disciplined, well-linked end of that spectrum.

okf/skills/okf-refactor/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: okf-refactor
+description: Refactor existing knowledge into an Open Knowledge Format (OKF) bundle — convert loose notes, docs, READMEs, wikis, or a catalog/metadata export into markdown concept files with YAML frontmatter, index.md, and a knowledge graph. Use when migrating existing knowledge to OKF, normalizing a notes folder, or exporting a catalog to OKF.
+---
+
+# okf-refactor — convert existing knowledge into an OKF bundle
+
+## Goal
+
+Take knowledge that already exists in some other shape — a folder of loose
+markdown notes, a wiki, README/docs, a data-catalog export, a database schema, a
+JSON/CSV metadata dump — and emit a conformant **OKF v0.1** bundle: a directory of
+one-concept-per-file markdown docs with YAML frontmatter, navigable `index.md`
+files, and a cross-linked knowledge graph.
+
+This skill depends on the **okf** skill for the format itself. Read
+`../okf/reference/SPEC.md` (the bundled OKF v0.1 spec) before refactoring — it is
+the source of truth. Use `../okf/scripts/validate_okf.py` to check the result.
+
+## Inputs and outputs
+
+- **Input** (`<src>`): a directory, file set, or export to read FROM. Treat it as
+  immutable ground truth — never edit the source in place.
+- **Output** (`<out>`): the bundle directory to write TO. New, separate from `<src>`.
+
+Confirm both paths before writing. If `<out>` is omitted, default to
+`./bundles/<name>` and state the choice.
+
+## The refactor pass (run in order; plan before writing)
+
+1. **Survey the source.** Inventory every item of knowledge and its natural
+   boundaries. Identify what each "thing" is (a table, an endpoint, a concept, a
+   runbook) — that becomes a concept's `type`. Note relationships between things
+   (foreign keys, "see also", parent/child) — those become cross-links.
+
+2. **Design the taxonomy = the directory layout.** Group concepts into top-level
+   directories by `type` or domain (`tables/`, `datasets/`, `references/`,
+   `concepts/`, `playbooks/`…). Start flat; nest only when a level earns it.
+   Directories are the coarse taxonomy; frontmatter `tags` carry cross-cutting
+   facets.
+
+3. **Map each source item to one concept doc.** Atomic — one concept per file,
+   `<group>/<slug>.md`, kebab-case stable slug. Never pack two concepts into one
+   file; split multi-topic source notes.
+
+4. **Write frontmatter for each concept.** Always set a non-empty `type`. Derive
+   `title` and `description` (one line — this is what indexes show). Set
+   `resource` to the canonical URI when the item has one. Map source metadata to
+   `tags` and `timestamp`. Preserve any source-specific metadata as extra
+   frontmatter keys (consumers tolerate unknown keys) rather than dropping it.
+
+5. **Write the body.** Move structured fields under `# Schema` (prefer a table),
+   runnable usage under `# Examples`, and sources under `# Citations`. Keep prose
+   tight; favor structural markdown. Do not invent facts not present in the source.
+
+6. **Wire the graph.** Convert every relationship into an inline markdown link
+   using **absolute bundle-relative** paths (`[orders](/tables/orders.md)`).
+   Ensure no concept is fully orphaned — each should link, or be linked by, at
+   least one other where a real relationship exists.
+
+7. **Mint reference docs.** External authoritative sources cited by many concepts
+   become standalone `references/<slug>.md` concept docs (with their own `type`,
+   e.g. `Reference`), linked from `# Citations`.
+
+8. **Generate indexes.** Write an `index.md` per navigable directory (no
+   frontmatter; group under `#` sections; copy each bullet's description from the
+   linked concept). Write the bundle-root `index.md` with `okf_version: "0.1"`
+   frontmatter linking the top-level groups.
+
+9. **Seed `log.md`.** At the root, record an `## <YYYY-MM-DD>` entry noting the
+   `* **Initialization**: Refactored from <source>.` Use the real current date.
+
+10. **Validate.** Run `validate_okf.py <out>`. Fix every error. Broken
+    cross-links are warnings (the spec tolerates them) — resolve the ones you can,
+    report the rest.
+
+## Fidelity rules
+
+- **Lossless of meaning.** Restructuring may drop redundant words, never facts.
+  If the source has metadata with no obvious home, keep it as a custom frontmatter
+  key rather than discarding it.
+- **No invention.** Don't fabricate descriptions, schemas, or links the source
+  doesn't support. Mark genuine gaps plainly instead of guessing.
+- **Source stays immutable.** All writes land in `<out>`; `<src>` is read-only.
+- **Idempotent-ish.** Re-running against the same source should converge on the
+  same bundle, not accumulate duplicates.
+
+## Report
+
+After the pass, summarize: number of concepts emitted (by `type`/group), index and
+reference docs created, cross-links wired, and any unresolved gaps or broken links
+the source left dangling. Then show the bundle tree.
+
+## Checklist
+
+- [ ] Confirmed `<src>` (read-only) and `<out>` (new) paths.
+- [ ] Read ../okf/reference/SPEC.md before refactoring.
+- [ ] One concept per file; multi-topic notes split; stable kebab-case slugs.
+- [ ] Every concept has a non-empty `type`, plus `title` + `description`.
+- [ ] Relationships wired as absolute bundle-relative links; no true orphans.
+- [ ] Root index.md has `okf_version: "0.1"`; per-directory indexes generated.
+- [ ] log.md seeded with the initialization entry (real date).
+- [ ] validate_okf.py run; errors fixed; remaining broken links reported.
+- [ ] No facts invented; source-specific metadata preserved as custom keys.