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 – Open Knowledge Format (OKF) 用の Claude Code プラグイン & スキルセット

概要 – Claude ベースのコーディングエージェント（Claude Code、Cursor、Codex など）が Open Knowledge Format (OKF) v0.2 で記述されたナレッジバンドルを生成、検証、保守、視覚化できるようにする、小さなオープンソースツールキットです。このリポジトリには、3つの Claude Code スキル（okf、validate、visualize）、Claude マーケットプレースプラグイン、CI ゲーティング用の GitHub Action、および自己完結型の HTML グラフレンダラーが含まれています。

重要性 – OKF は、Google が発表した、構造化されたナレッジを YAML front‑matter を持つプレーンテキストの Markdown ファイルとして保存する、ベンダーニュートラルな新しい方法です。仕様を Claude のワークフローに直接統合することで、開発者はドキュメント、設計決定、メトリクスなどを、エージェントが読み取り、更新、推論できる形式で保持しつつ、人間が編集可能でバージョン管理された状態を維持できます。

Key components

Component Role
/okf:okf skill プロンプトから OK‑OKF バンドルを生成または更新します（例：「OKF で認証サービスをドキュメント化する」）。
/okf:validate skill OKF v0.2 仕様に対して決定論的適合性チェッカーを実行します（厳格モードではビルドを失敗させる可能性があります）。
/okf:visualize skill バンドルを viz.html に変換します。これはインタラクティブでバックエンド不要のグラフであり、各ノードはレンダリングされた Markdown、信頼ティア、古さ、出所、バックリンクを表示します。
action.yml 任意のリポジトリに追加して CI でバンドルを自動的に検証できる複合 GitHub Action（Claude がインストールされていなくても可）。
templates/CLAUDE‑okf.md プロジェクトの CLAUDE.md に追加すると、タスク前に Claude がバンドルを自動的に消費し、変更後に更新を書き戻すようになるスニペット。
.okf/ directory (self‑documented) ライブデモおよびバリデーター/ビジュアライザーのドッグフーディングに使用されるサンプルバンドル。

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 – リポジトリをクローンし、claude --plugin-dir /path/to/okf-skills で Claude にその場所を指定します。

Typical workflow

  1. バンドルを Create / update する：
    /okf:okf produce .okf          # Claude writes markdown files under .okf
  2. コミット前に Validate する：
    /okf:validate .okf --strict    # fails on any spec violation
    （提供されている GitHub Action を介して CI で実行することも可能です。）
  3. ナレッジグラフを Visualise する：
    /okf:visualize .okf -o viz.html --title "My project" --link "https://github.com/me/project"
    任意のブラウザで viz.html を開きます – サーバーは不要です。ノードはディープリンク可能です（viz.html#services/auth-api）。
  4. Keep it fresh – .okf/index.md に upkeep: enforced を追加して、バンドルが更新されていない場合に Claude がタスクをブロックするようにするか、CLAUDE‑okf.md のソフトモードスニペットを使用して自動バックグラウンド更新を行います。

How it works under the hood

  • Spec‑driven – リポジトリには完全な OKF v0.2 仕様（skills/okf/reference/SPEC.md）がベンダリングされています。すべてのスキルは決定論的な動作を保証するためにこのファイルを読み取ります。
  • Zero‑config Python scripts – 検証と視覚化は純粋な Python スクリプト（okf_validate.py、okf_visualize.py）で、uv（またはプレーンな python3 + pyyaml）で実行されます。外部サービスは必要ありません。
  • Self‑contained graph – ビジュアライザーは、Markdown、計算された信頼ティア、古さバッジ、バックリンクデータを埋め込んだ単一の HTML ファイルを構築します。すべてクライアント側で計算されるため、デモページがデータをどこかに送信することはありません。
  • GitHub Action – action.yml はバリデータースクリプトをラップし、bundle と strict/max-warnings 入力を公開して、任意のリポジトリ（Claude がない場合でも）で OKF コンプライアンスを強制できるようにします。

Who might use this

  • すでに Claude Code を使用しており、エージェントが読み取り/書き込みできる構造化されたバージョン管理されたナレッジベースを求めているチーム。
  • CI でナレッジバンドルの品質をゲートしたい DevOps / ドキュメントエンジニア。
  • AI 拡張されたドキュメントパイプラインを試している 研究者や製品グループ。

License & credits

  • コードとコンテンツ：MIT License © Marco Boffo (@scaccogatto)。
  • OKF 仕様：Apache‑2.0、Google Cloud の Knowledge Catalog リポジトリから帰属表示付きでベンダリング。

Quick links

  • Live demo – https://scaccogatto.github.io/okf-skills/
  • OKF spec (v0.2) – skills/okf/reference/SPEC.md
  • GitHub Action – action.yml
  • Installation commands – 上記の Installation セクションを参照してください。

関連

  • プロジェクト
    Prorise-cool/Claude-Code-Multi-Agent

    Claude Code Multi‑Agent は、Anthropic の Claude Code プロジェクトに認識能力とエキスパートエージェント機能を追加するオープンソースフレームワークです。Python Hook システムとローカル実行の Ollama モデルを使用して、コードベースの種類を自動検出、ユーザーの意図を分析、300以上ものドメイン固有の「スキル」（バックエンド、フロントエンド、テスト、セキュリティなど）をロードし、自動ドキュメント（DEVELOPMENT.md、KNOWLEDGE.md、CHANGELOG.md）を強制します。リポジトリをクローンし、Ollama、モデル、uv をインストールした後、プロジェクトをリポジトリに配置するだけで、Claude Code は即座にコンテキストを把握し、適切なツールを提案し、`/backend‑specialist` や `/kiro/spec` のようなスラッシュコマンドで操作できます。 主な特徴： - ゼロ構成スタート；すべての設定は `.claude/settings.json` と `prompts.json` に保存。 - セッション開始、ユーザーのプロンプト、ツール使用などに応じて実行される Hooks で、プロジェクト検出、意図分析、ドキュメント更新を処理。 - Skills は `SKILL.md` ファイルで定義され、自動検出される。 - 外部 API を一切使わず、完全にローカルで動作。Git と統合可能。MIT ライセンス。 個人開発者や小さなチームが再現可能でオンプレミスの AI コーディングアシスタントを必要とする場合に最適です。

  • プロジェクト
    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.

  • プロジェクト
    himself65/trade-skills

    Open Knowledge Formatを使用した、32の落とし穴と事例を含むオプション取引知識ベースを提供するClaude Codeプラグイン

  • プロジェクト
    mhattingpete/claude-skills-marketplace

    Claude Code向けのプラグイン、スキル、エージェントの厳選マーケットプレイスで、ソフトウェア開発ワークフローを自動化し、トークン効率的な大規模操作用のローカル実行ランタイムを提供します。

  • プロジェクト
    coreyhaines31/makerskills

    makerskillsは、意思決定、リサーチ、ドメイン探し、個人/企業ナレッジベース、財務モデリング、コンテンツ作成などの創業者向けタスクのための、20個のドキュメント化された「スキル」（小規模でバージョン管理されたエージェントワークフロー）をまとめたClaude Codeプラグインです。プラグインをインストールして設定ディレクトリを指定し、スラッシュコマンド（例：`/decide`、`/paste`）でスキルを呼び出します。各スキルは`SKILL.md`ファイルで定義され、組み合わせが可能で、互いに呼び出すこともできます。このリポジトリは、ドキュメント、例、および明確なアーキテクチャを提供しており、`skillify`、`toolify`、`loopify`を使用してワークフローを拡張またはスケジュールしながら、個人のデータをリポジトリの外に保持します。