Skip to content
Back to search

scaccogatto

MarketplaceWorks with Claude CodeGitHub

Claude Code plugins by scaccogatto.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/scaccogatto-okf-skills/badge.svg)](/listings/scaccogatto-okf-skills)

HTML

<a href="/listings/scaccogatto-okf-skills"><img src="/api/listings/scaccogatto-okf-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

| Channel | Command | Notes | |---|---|---| | Claude Code plugin | `/plugin marketplace add scaccogatto/okf-skills` then `/plugin install okf@scaccogatto` | Skills, subagents, Stop hook and MCP server. The full toolchain. | | Agent skills ([skills.sh](https://skills.sh/scaccogatto/okf-skills)) | `npx skills add scaccogatto/okf-skills` | Claude Code, Cursor, Codex and 20+ agents. Installs the okf, validate, visualize and backfill skills; backfill needs the plugin's subagents, see below. | | GitHub Action | `uses: scaccogatto/okf-skills@v1` | Validates a bundle in CI, no agent needed. | | MCP server | `uv run servers/okf_mcp.py .okf` | Any MCP host. Bundled with the plugin, nothing to configure there. | | Local development | `claude --plugin-dir /path/to/okf-skills` | No marketplace. |

The scripts need [`uv`](https://docs.astral.sh/uv/) (or `python3` with `pyyaml`). One repo serves both layouts: `.claude-plugin/` makes it a marketplace, `skills/<name>/SKILL.md` makes it skills.sh-discoverable, and scripts resolve through `${CLAUDE_SKILL_DIR}` so they run from either path. The backfill skill dispatches the two subagents in `agents/`, which live outside `skills/`, so backfill works from the plugin install only.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 19 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
  3. "name": "scaccogatto",
  4. "description": "Claude Code plugins by scaccogatto.",
  5. "owner": {
  6. "name": "Marco Boffo",
  7. "email": "chat@marcoboffo.me"
  8. },
  9. "plugins": [
  10. {
  11. "name": "okf",
  12. "source": "./",
  13. "description": "Author, maintain, backfill, validate, visualize and serve (MCP) Open Knowledge Format (OKF) bundles.",
  14. "category": "documentation",
  15. "keywords": ["okf", "knowledge", "markdown", "agents"],
  16. "license": "MIT"
  17. }
  18. ]
  19. }
README.md · README · 239 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. # okf: the Open Knowledge Format toolkit for Claude Code
  3. **Teach your coding agent to author, maintain, validate and visualize portable
  4. knowledge bundles: markdown your team and your agents both read.**
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-black.svg)](LICENSE)
  6. [![OKF spec](https://img.shields.io/badge/OKF-v0.2-6E56CF.svg)](https://github.com/GoogleCloudPlatform/open-knowledge-format)
  7. [![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-D97757.svg)](https://code.claude.com/docs/en/plugins)
  8. [![skills.sh](https://img.shields.io/badge/skills.sh-installable-22C55E.svg)](https://skills.sh/scaccogatto/okf-skills)
  9. [![okf: explore an OKF bundle as an interactive graph](docs/assets/demo.gif)](https://scaccogatto.github.io/okf-skills/)
  10. **[Open the live demo](https://scaccogatto.github.io/okf-skills/)**: a real bundle as an interactive graph. Click a node for the rendered concept, its derived trust tier and staleness, its sources and backlinks. Nothing leaves the page.
  11. </div>
  12. ---
  13. [**OKF**](https://github.com/GoogleCloudPlatform/open-knowledge-format) is an
  14. open, vendor-neutral format from Google Cloud ([announced June 2026](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing))
  15. that stores the knowledge around your systems as a directory of markdown files
  16. with YAML frontmatter. No schema registry, no runtime, no SDK: `cat` reads it,
  17. `git clone` ships it. v0.2 adds trust, provenance and staleness signals to the
  18. frontmatter, so an agent can tell a verified fact from a stale guess.
  19. **This repo is the Claude Code-native toolchain for it.** Claude learns to
  20. produce, maintain, consume, validate, visualize and backfill OKF bundles as part
  21. of how it already works, driven by the vendored spec and backed by a
  22. deterministic conformance checker. It ships four ways: a Claude Code **plugin**,
  23. **agent skills** for 20+ agents via skills.sh, a **GitHub Action** for repos with
  24. no agent, and a read-only **MCP server** for hosts whose agents cannot read files.
  25. This repo documents itself in OKF: its architecture and decisions live in
  26. [`.okf/`](.okf/), rendered as a [live self-graph](https://scaccogatto.github.io/okf-skills/self.html)
  27. and validated on every push.
  28. ## Install
  29. | Channel | Command | Notes |
  30. |---|---|---|
  31. | Claude Code plugin | `/plugin marketplace add scaccogatto/okf-skills` then `/plugin install okf@scaccogatto` | Skills, subagents, Stop hook and MCP server. The full toolchain. |
  32. | Agent skills ([skills.sh](https://skills.sh/scaccogatto/okf-skills)) | `npx skills add scaccogatto/okf-skills` | Claude Code, Cursor, Codex and 20+ agents. Installs the okf, validate, visualize and backfill skills; backfill needs the plugin's subagents, see below. |
  33. | GitHub Action | `uses: scaccogatto/okf-skills@v1` | Validates a bundle in CI, no agent needed. |
  34. | MCP server | `uv run servers/okf_mcp.py .okf` | Any MCP host. Bundled with the plugin, nothing to configure there. |
  35. | Local development | `claude --plugin-dir /path/to/okf-skills` | No marketplace. |
  36. The scripts need [`uv`](https://docs.astral.sh/uv/) (or `python3` with `pyyaml`).
  37. One repo serves both layouts: `.claude-plugin/` makes it a marketplace,
  38. `skills/<name>/SKILL.md` makes it skills.sh-discoverable, and scripts resolve
  39. through `${CLAUDE_SKILL_DIR}` so they run from either path. The backfill skill
  40. dispatches the two subagents in `agents/`, which live outside `skills/`, so
  41. backfill works from the plugin install only.
  42. ## Use it
  43. **Capture knowledge.** Ask Claude to "document the auth service in OKF", or:
  44. ```shell
  45. /okf:okf produce .okf
  46. ```
  47. **Backfill a repo that predates the bundle.** Event-sources git history and
  48. Claude session transcripts into concepts, with a deterministic extractor and an
  49. auditable map/reduce over subagents:
  50. ```shell
  51. /okf:backfill .
  52. ```
  53. **Validate** before committing. The checker is deterministic, §11 of the spec,
  54. not an eyeball pass. `--migrate` rewrites v0.1 constructs in place:
  55. ```shell
  56. /okf:validate .okf --strict
  57. uv run skills/validate/scripts/okf_validate.py .okf --strict # zero-config
  58. uv run skills/validate/scripts/okf_validate.py .okf --max-warnings 5
  59. ```
  60. **Gate it in CI** with the composite action. `@v1` tracks the latest release
  61. while the repo is pre-1.0; pin `@okf--v<version>` to freeze it. The step exposes
  62. the validator's JSON as the `report` output.
  63. ```yaml
  64. - uses: scaccogatto/okf-skills@v1
  65. with:
  66. bundle: .okf
  67. strict: "true" # or: max-warnings: "5"
  68. ```
  69. **Visualize** the graph as a self-contained `viz.html`
  70. ([live example](https://scaccogatto.github.io/okf-skills/)). Every concept gets
  71. a deep link (`viz.html#services/auth-api`), and each panel shows two derived
  72. badges: the §5.3 trust tier and staleness once `stale_after` has passed. OKF
  73. stores neither, so both are computed at render time. Above 1000 concepts the
  74. layout falls back to linear; `--layout cose` overrides, `--max-nodes N` refuses.
  75. ```shell
  76. /okf:visualize .okf
  77. uv run skills/visualize/scripts/okf_visualize.py .okf -o viz.html \
  78. --title "My project" --link "https://github.com/me/project"
  79. ```
  80. **Read a bundle over MCP.** Three read-only tools; nothing writes and no id
  81. resolves outside the bundle root. Inside Claude Code the server starts with the
  82. plugin on `./.okf` and appears as `mcp__plugin_okf_bundle__*`. For Claude Code
  83. it duplicates Read and Grep, and [the decision record](.okf/decisions/mcp-server.md)
  84. says so; it ships for the hosts that have nothing else.
  85. | Tool | Returns |
  86. |---|---|
  87. | `search_concepts(query, limit)` | Concept cards (`id`, `type`, `title`, `description`, `status`, `stale_after`); metadata hits rank above body hits. |
  88. | `read_concept(concept_id)` | One concept verbatim, frontmatter included. The id is the bundle path without `.md`. |
  89. | `get_neighbors(concept_id)` | `outgoing` and `incoming` cards from markdown links and bundle-internal `sources`. |
  90. Any other host: run `uv run servers/okf_mcp.py <bundle>` as a stdio server
  91. (a bundle path, else `$OKF_BUNDLE`, else `./.okf`).
  92. **Keep it up to date.** Two opt-in modes. *Soft:* paste
  93. [`templates/CLAUDE-okf.md`](templates/CLAUDE-okf.md) into your `CLAUDE.md` so
  94. Claude consults `.okf/` before a task and writes back after. *Enforced:* add
  95. `upkeep: enforced` to `.okf/index.md`'s frontmatter to arm the plugin's dormant
  96. `Stop` hook, which blocks finishing when tracked files changed but nothing under
  97. `.okf/` did. If the bundle documents git repos checked out inside the project,
  98. add `recursive: true` (or a depth, `recursive: 3`) so the hook finds them and
  99. counts their uncommitted changes too. Depth is how many directory levels below
  100. the project root a repo's directory may sit (`repos/app` is 2); `true` means 6. `OKF_HOOK=off` overrides any bundle. Details:
  101. [stop-hook concept](.okf/components/stop-hook.md).
  102. ## What's inside
  103. | Component | What it does |
  104. |---|---|
  105. | `skills/okf/` | Produce / maintain / consume bundles from the spec and templates; auto-triggers in repos that have one. `scripts/okf_init.py` scaffolds a starter bundle. |
  106. | `skills/validate/` | `scripts/okf_validate.py`: standalone §11 conformance checker, `--strict`, `--max-warnings`, `--json`, `--migrate`. |
  107. | `skills/visualize/` | `scripts/okf_visualize.py`: bundle to `viz.html`. |
  108. | `skills/backfill/` | Reconstruct a bundle from history. `scripts/okf_backfill_events.py` extracts events and emits capped diffs deterministically. |
  109. | `agents/` | `event-analyzer` (map, cheap tier) and `bundle-weaver` (reduce, the only writer) for the backfill. |
  110. | `servers/okf_mcp.py` | The read-only MCP server, wired by `.mcp.json`. |
  111. | `hooks/` | The dormant Stop hook, armed by `upkeep: enforced`. |
  112. | `action.yml` | Composite GitHub Action around the validator. |
  113. | `templates/CLAUDE-okf.md` | The soft-mode snippet. |
  114. | `skills/okf/reference/SPEC.md` | OKF v0.2, vendored verbatim: the source of truth. |
  115. | `examples/sample-bundle/` | The bundle behind the live demo. |
  116. | `benchmark/` | Three published experiments, protocols and runs. |
  117. ## How a bundle looks
  118. A concept's path is its id. The only hard rule is YAML frontmatter with a
  119. non-empty `type`; everything else is optional.
  120. ```
  121. .okf/
  122. ├── index.md # progressive disclosure (root carries okf_version)
  123. ├── log.md # ISO-dated lifecycle events, newest first
  124. ├── services/auth-api.md # one concept = one file
  125. └── decisions/use-okf.md
  126. ```
  127. ```markdown
  128. ---
  129. type: Service
  130. title: Auth API
  131. description: Issues and verifies short-lived access tokens.
  132. status: stable
  133. stale_after: 2026-12-31T00:00:00Z
  134. generated: { by: doc_agent/1.0, at: 2026-06-14T10:00:00Z }
  135. verified: { by: human:dana, at: 2026-06-20T09:00:00Z }
  136. sources:
  137. - id: auth-readme
  138. resource: https://github.com/acme/auth#readme
  139. last_modified: 2026-06-12T00:00:00Z
  140. ---
  141. # Endpoints
  142. Tokens live 15 minutes.[^auth-readme]
  143. [^auth-readme]: Auth service README
  144. ```
  145. **What v0.2 adds**, all optional, all in frontmatter. Normative detail in
  146. [`SPEC.md`](skills/okf/reference/SPEC.md).
  147. | Family | Fields | Answers |
  148. |---|---|---|
  149. | Provenance | `sources[]` with `author`, `usage_count`, `last_modified`, `usage_window` | Where did this come from, how credible is it? |
  150. | Trust | `generated: {by, at}`, `verified[]`, actor prefixes `human:` / `process:` / `agent/version` | Who wrote it, who confirmed it? |
  151. | Lifecycle | `status`, `stale_after` | Is it current, is it still true? |
  152. | Attestation | `type: Attested Computation` with `runtime`, `parameters`, `executor`, `attester` | Was this number produced the sanctioned way? |
  153. Upgrading from v0.1: the tools read both, flag the old forms as warnings, and
  154. `okf_validate.py --migrate` rewrites them in place.
  155. ## What has been measured
  156. Three experiments in [`benchmark/`](benchmark/), each published with its
  157. protocol, runs and the defects it exposed. None of them estimates what OKF is
  158. worth in a real repository, where prose and history already carry recency.
  159. - **Trust metadata** ([results](benchmark/trust/RESULTS.md), pre-registered): with
  160. v0.2 lifecycle fields present the consumer never asserted a superseded fact, and
  161. read the fields unprompted. The primary contrast is invalid under the protocol's
  162. own rule, because the control refused to answer rather than answering wrong.
  163. - **Write-side gate** ([results](benchmark/gate/RESULTS.md), pre-registered): a
  164. process gate and an expired `stale_after` each reduced stale answers, and the
  165. two are not distinguishable on 20 items. Ungated writers left docs untouched
  166. 57% of the time, which is where the metadata acts.
  167. - **Backfill map tier** ([results](benchmark/map-tier/RESULTS.md), engineering
  168. A/B, one run per arm): batching small events eight per call cut the map phase by
  169. a third; the cheap tier matched `sonnet` on commits once two instructions were
  170. made explicit.
  171. A third party measures a different claim, sufficiency:
  172. [`aws-samples/sample-okf-llm-wiki`](https://github.com/aws-samples/sample-okf-llm-wiki)
  173. scores EX 74.0 on BIRD mini_dev (500 text-to-SQL questions) from the bundle alone.
  174. ## Contributing
  175. Issues and PRs welcome. CI validates the manifests, both bundles, the action,
  176. the docs regeneration and the test suites on every push. Releases are automatic:
  177. bump `version` in `.claude-plugin/plugin.json`, add a `## [<version>]` section to
  178. `CHANGELOG.md`, and merging to `main` tags `okf--v<version>`. A PR touching the
  179. shipped surface (`.claude-plugin/`, `skills/`, `agents/`, `hooks/`, `servers/`,
  180. `templates/`, `action.yml`, `.mcp.json`) fails CI without both; one touching
  181. `skills/*/scripts/`, `agents/` or `hooks/` must also update `.okf/`. The
  182. `skip-version-check` label bypasses all three. This repo's bundle sets
  183. `upkeep: enforced`, so the Stop hook blocks finishing until the concept
  184. describing your change is updated; `OKF_HOOK=off` opts out. The details, and
  185. the local commands that mirror CI, are in [CONTRIBUTING.md](CONTRIBUTING.md).
  186. Report vulnerabilities privately, as [SECURITY.md](SECURITY.md) describes.
  187. ## Credits & license
  188. - The **Open Knowledge Format** specification is by the Google Cloud Data Cloud
  189. team, Apache-2.0, at [GoogleCloudPlatform/open-knowledge-format](https://github.com/GoogleCloudPlatform/open-knowledge-format)
  190. (the earlier copy under `knowledge-catalog/okf` is a frozen snapshot).
  191. `skills/okf/reference/SPEC.md` is vendored verbatim with attribution.
  192. - This plugin's own code and content: **MIT** © Marco Boffo ([@scaccogatto](https://github.com/scaccogatto)).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.