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