scaccogatto/okf-skills

The OKF toolkit for Claude Code — author, maintain, validate & visualize Open Knowledge Format bundles. Plugin, agent skills, and a GitHub Action.

📚 okf‑skills – Claude Code plugin & skill set for the Open Knowledge Format (OKF)

What it is – A small open‑source toolkit that lets Claude‑based coding agents (Claude Code, Cursor, Codex, etc.) produce, validate, maintain and visualise knowledge bundles written in the Open Knowledge Format (OKF) v0.2. The repo ships three Claude Code skills (okf, validate, visualize), a Claude marketplace plugin, a GitHub Action for CI gating, and a self‑contained HTML graph renderer.

Why it matters – OKF is a new Google‑announced, vendor‑neutral way to store structured knowledge as plain‑text markdown files with YAML front‑matter. By integrating the spec directly into Claude’s workflow, developers can keep documentation, design decisions, metrics, etc. in a format that agents can read, update and reason over, while still being human‑editable and version‑controlled.

Key components

Component Role
/okf:okf skill Generates or updates an OK‑OKF bundle from prompts (e.g. “document the auth service in OKF”).
/okf:validate skill Runs a deterministic conformance checker against the OKF v0.2 spec (strict mode can fail the build).
/okf:visualize skill Turns a bundle into viz.html, an interactive, backend‑free graph where each node shows rendered markdown, trust tier, staleness, provenance and backlinks.
action.yml Composite GitHub Action that can be added to any repo to automatically validate a bundle in CI, even without Claude installed.
templates/CLAUDE‑okf.md Snippet that, when added to a project’s CLAUDE.md, makes Claude automatically consume the bundle before tasks and write back updates after changes.
.okf/ directory (self‑documented) Example bundle used for the live demo and for dog‑fooding the validator/visualiser.

Installation & quick start

# As a Claude Code marketplace plugin
/plugin marketplace add scaccogatto/okf-skills
/plugin install okf@scaccogatto

# Or as a generic Claude skill via skills.sh (works for Cursor, Codex, etc.)
npx skills add scaccogatto/okf-skills

Local development – clone the repo and point Claude to it with claude --plugin-dir /path/to/okf-skills.

Typical workflow

  1. Create / update a bundle:
    /okf:okf produce .okf          # Claude writes markdown files under .okf
  2. Validate before committing:
    /okf:validate .okf --strict    # fails on any spec violation
    (Can also be run in CI via the provided GitHub Action.)
  3. Visualise the knowledge graph:
    /okf:visualize .okf -o viz.html --title "My project" --link "https://github.com/me/project"
    Open viz.html in any browser – no server needed. Nodes are deep‑linkable (viz.html#services/auth-api).
  4. Keep it fresh – add upkeep: enforced to .okf/index.md to make Claude block a task if the bundle wasn’t updated, or use the soft‑mode snippet in CLAUDE‑okf.md for automatic background updates.

How it works under the hood

  • Spec‑driven – The repository vendors the full OKF v0.2 spec (skills/okf/reference/SPEC.md). All skills read this file to ensure deterministic behaviour.
  • Zero‑config Python scripts – Validation and visualisation are pure Python scripts (okf_validate.py, okf_visualize.py) that run with uv (or plain python3 + pyyaml). No external services are required.
  • Self‑contained graph – The visualiser builds a single HTML file that embeds the markdown, computed trust tier, staleness badge and backlink data. Everything is computed client‑side, so the demo page never sends data anywhere.
  • GitHub Action – action.yml wraps the validator script, exposing bundle and strict/max-warnings inputs, allowing any repo (even without Claude) to enforce OKF compliance.

Who might use this

  • Teams that already use Claude Code and want a structured, version‑controlled knowledge base that agents can read/write.
  • DevOps / documentation engineers looking to gate knowledge‑bundle quality in CI.
  • Researchers or product groups experimenting with AI‑augmented documentation pipelines.

License & credits

  • Code and content: MIT License © Marco Boffo (@scaccogatto).
  • OKF specification: Apache‑2.0, vendored from Google Cloud’s Knowledge Catalog repository with attribution.

Quick links

Related

  • Project
    Prorise-cool/Claude-Code-Multi-Agent

    Claude Code Multi‑Agent is an open‑source framework that gives Anthropic’s Claude Code project awareness and expert‑agent capabilities. It uses a Python Hook system and a locally‑run Ollama model to automatically detect the codebase type, analyse user intent, load 300+ domain‑specific “Skills” (backend, frontend, testing, security, etc.), and enforce automatic documentation (DEVELOPMENT.md, KNOWLEDGE.md, CHANGELOG.md). After cloning, installing Ollama, a model, and uv, you drop your project into the repo and Claude Code instantly knows its context, suggests appropriate tools, and can be driven with slash commands like `/backend‑specialist` or workflow commands such as `/kiro/spec`. Key points: - Zero‑config start; all configuration lives in `.claude/settings.json` and `prompts.json`. - Hooks run on session start, user prompt, tool use, etc., handling project detection, intent analysis, and doc updates. - Skills are defined by `SKILL.md` files and are auto‑discovered. - Works entirely locally (no external API), integrates with Git, and is MIT‑licensed. Ideal for developers or small teams who want a reproducible, on‑premise AI coding assistant.

  • Project
    sangrokjung/claude-forge

    A professional equipment pack for Claude Code that adds specialist agents, safety hooks, and automated workflows to transform the terminal AI into a full-scale development kit.

  • Project
    himself65/trade-skills

    A Claude Code plugin that provides an options-trading knowledge base featuring 32 pitfalls and case studies using the Open Knowledge Format.

  • Project
    mhattingpete/claude-skills-marketplace

    A curated marketplace of plugins, skills, and agents for Claude Code that automates software engineering workflows and provides a local execution runtime for token-efficient bulk operations.

  • Project
    coreyhaines31/makerskills

    makerskills is a Claude Code plugin that bundles 20 documented “skills” – small, versioned agent workflows for founder tasks such as decision‑making, research, domain hunting, personal/company knowledge bases, financial modeling, and content creation. Install the plugin, set a config directory, and invoke skills via slash commands (e.g., `/decide`, `/paste`). Skills are composable, each defined in a `SKILL.md` file, and can call one another. The repo provides docs, examples, and a clear architecture that keeps personal data out of the repo while letting users extend or schedule workflows with `skillify`, `toolify`, and `loopify`.