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 編寫的知識包。該儲存庫提供了三個 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`	複合式 GitHub Action，可以新增到任何儲存庫中，以在 CI 中自動驗證包，即使未安裝 Claude 也可以。
`templates/CLAUDE‑okf.md`	程式碼片段，當新增到專案的 `CLAUDE.md` 時，會讓 Claude 在任務前自動使用該包，並在更改後寫回更新。
`.okf/` directory (self‑documented)	用於現場演示和對驗證器/視覺化器進行 dog‑fooding 測試的範例包。

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

Create / update 一個包：

/okf:okf produce .okf          # Claude writes markdown files under .okf

在提交前Validate：
```
/okf:validate .okf --strict    # fails on any spec violation
```
（也可以透過提供的 GitHub Action 在 CI 中執行。）
Visualise 知識圖表：
```
/okf:visualize .okf -o viz.html --title "My project" --link "https://github.com/me/project"
```
在任何瀏覽器中開啟 viz.html – 無需伺服器。節點支援深層連結（viz.html#services/auth-api）。
Keep it fresh – 將 upkeep: enforced 新增到 .okf/index.md 中，如果包未更新，則使 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 – 視覺化器建構了一個單一的 HTML 檔案，其中嵌入了 Markdown、計算出的信任層級、過時徽章和反向連結資料。所有內容都在客戶端計算，因此演示頁面永遠不會將資料發送到任何地方。
GitHub Action – action.yml 包裝了驗證器腳本，公開了 bundle 和 strict/max-warnings 輸入，允許任何儲存庫（即使沒有 Claude）強制執行 OKF 合規性。

Who might use this

已經使用 Claude Code 的團隊，想要一個結構化、版本控制且代理程式可讀寫的知識庫。
DevOps / 文件工程師，希望在 CI 中對知識包的質量進行閘道控制。
研究人員或產品團隊，正在嘗試 AI 增強的文件管線。

License & credits

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 部分。