{"id":51438561,"url":"https://github.com/scaccogatto/okf-skills","last_synced_at":"2026-07-05T09:30:26.037Z","repository":{"id":365778208,"uuid":"1269151566","full_name":"scaccogatto/okf-skills","owner":"scaccogatto","description":"Open Knowledge Format (OKF) for Claude Code — author, maintain \u0026 validate portable markdown knowledge bundles for AI agents. Dual: Claude Code plugin + skills.sh.","archived":false,"fork":false,"pushed_at":"2026-06-18T20:00:41.000Z","size":36,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-18T22:04:59.267Z","etag":null,"topics":["agent-skills","ai-agents","claude-code","claude-code-plugin","claude-skills","knowledge-management","markdown","okf","open-knowledge-format","skills-sh"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scaccogatto.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-14T11:15:31.000Z","updated_at":"2026-06-18T20:00:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/scaccogatto/okf-skills","commit_stats":null,"previous_names":["scaccogatto/okf-skills"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/scaccogatto/okf-skills","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scaccogatto%2Fokf-skills","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scaccogatto%2Fokf-skills/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scaccogatto%2Fokf-skills/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scaccogatto%2Fokf-skills/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scaccogatto","download_url":"https://codeload.github.com/scaccogatto/okf-skills/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scaccogatto%2Fokf-skills/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35150062,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","ai-agents","claude-code","claude-code-plugin","claude-skills","knowledge-management","markdown","okf","open-knowledge-format","skills-sh"],"created_at":"2026-07-05T09:30:25.294Z","updated_at":"2026-07-05T09:30:26.013Z","avatar_url":"https://github.com/scaccogatto.png","language":"Python","funding_links":[],"categories":["Popular repos"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 📚 okf — the Open Knowledge Format toolkit for Claude Code\n\n**Teach your coding agent to author, maintain, validate, and *visualize* portable\nknowledge bundles — markdown your team and your agents both read.**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-black.svg)](LICENSE)\n[![OKF spec](https://img.shields.io/badge/OKF-v0.1-6E56CF.svg)](skills/okf/reference/SPEC.md)\n[![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-D97757.svg)](https://code.claude.com/docs/en/plugins)\n[![skills.sh](https://img.shields.io/badge/skills.sh-installable-22C55E.svg)](https://skills.sh/scaccogatto/okf-skills)\n[![PRs welcome](https://img.shields.io/badge/PRs-welcome-3B82F6.svg)](#contributing)\n\n### ▶ [**Open the live demo**](https://scaccogatto.github.io/okf-skills/) — a real OKF bundle as an interactive graph\n\n[![okf — explore an OKF bundle as an interactive graph](docs/assets/demo.gif)](https://scaccogatto.github.io/okf-skills/)\n\n*Click any node → rendered markdown, typed metadata, and \"Links to / Cited by\" backlinks. No backend, nothing leaves the page.*\n\n\u003c/div\u003e\n\n---\n\n\u003e [**OKF**](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing)\n\u003e is an open, vendor-neutral format (announced by Google Cloud, June 2026) that\n\u003e represents knowledge — the context and curated insight around your systems — as\n\u003e a directory of markdown files with YAML frontmatter. No schema registry. No\n\u003e runtime. No SDK. If you can `cat` a file you can read it; if you can `git clone`\n\u003e a repo you can ship it.\n\nThis is the **Claude Code-native** OKF toolchain. It teaches Claude to **produce**,\n**maintain**, **consume**, **validate**, and **visualize** OKF bundles as a normal\npart of how it already works — driven by the *verbatim* spec, backed by a\ndeterministic conformance checker, with a self-contained graph renderer. Ships as\na **Claude Code plugin** and as **agent skills** (Cursor, Codex, and 20+ agents).\n\n## Why knowledge-as-code (and where OKF fits)\n\nProject knowledge lives scattered across wikis, code comments, and people's heads;\nagents re-discover it from scratch every session. OKF gives it one durable,\ndiffable, portable home — versioned next to the code it describes. It is\n**complementary** to the rest of your context stack, not a replacement:\n\n| | **OKF bundle** (this) | `CLAUDE.md` | Claude auto-memory | Wiki / Notion |\n|---|:---:|:---:|:---:|:---:|\n| Purpose | curated **knowledge** | standing **instructions** | implicit notes | human docs |\n| Portable across agents/tools | ✅ plain md + yaml | ⚠️ Claude-specific | ❌ per-agent store | ⚠️ export needed |\n| Versioned with code in git | ✅ | ✅ | ❌ | ❌ |\n| Typed \u0026 queryable | ✅ frontmatter | ❌ prose | ❌ | ⚠️ |\n| Graph of linked concepts | ✅ | ❌ | ❌ | ⚠️ |\n| Curated \u0026 reviewed in PRs | ✅ | ✅ | ❌ implicit | ⚠️ |\n| Scales past the context window | ✅ progressive disclosure | ❌ loaded wholesale | ⚠️ | n/a |\n\nUse `CLAUDE.md` for *how to behave*, auto-memory for *what the agent picked up*,\nand an OKF bundle for *what the team knows* — shared, structured, and shippable.\n\n\u003e 🪞 **This repo documents itself in OKF.** The architecture, skills, and decisions\n\u003e behind okf-skills live in [`.okf/`](.okf/) — explore them as a\n\u003e [**live self-graph**](https://scaccogatto.github.io/okf-skills/self.html). CI\n\u003e validates that bundle on every push (dogfooding the conformance checker).\n\n## What's inside\n\n| Component | What it does |\n|-----------|--------------|\n| `/okf:okf` skill | Produce / maintain / consume bundles, applying the spec and templates. Auto-triggers when a repo has an OKF bundle. |\n| `/okf:validate` skill | Deterministic §9 conformance check (not an eyeball pass). |\n| `/okf:visualize` skill | Render a bundle to a self-contained interactive HTML graph (`viz.html`). |\n| `skills/validate/scripts/okf_validate.py` | Standalone, zero-config validator (`uv run`, PyYAML via PEP 723). |\n| `skills/visualize/scripts/okf_visualize.py` | Standalone bundle→`viz.html` renderer (Cytoscape + marked via CDN). |\n| `skills/okf/reference/SPEC.md` | The OKF v0.1 spec, vendored verbatim — the source of truth. |\n| `templates/CLAUDE-okf.md` | Snippet that turns on automatic consume/maintain in your project. |\n| `examples/sample-bundle/` | The conformant bundle behind the [live demo](https://scaccogatto.github.io/okf-skills/) — code, data, decisions, runbooks, metrics. |\n\n## Install\n\n**As a Claude Code plugin** (one-plugin marketplace):\n\n```shell\n/plugin marketplace add scaccogatto/okf-skills\n/plugin install okf@scaccogatto\n```\n\n**As agent skills via [skills.sh](https://skills.sh/scaccogatto/okf-skills)** (Claude Code, Cursor, Codex, and 20+ agents):\n\n```shell\nnpx skills add scaccogatto/okf-skills            # installs the okf, validate \u0026 visualize skills\n```\n\n**Local development** (no marketplace):\n\n```shell\nclaude --plugin-dir /path/to/okf-skills\n```\n\nBoth layouts coexist in this single repo: `.claude-plugin/` makes it a plugin\nmarketplace; `skills/\u003cname\u003e/SKILL.md` makes it skills.sh-discoverable. The scripts\nlive inside their skills and are referenced via `${CLAUDE_SKILL_DIR}`, so they work\nidentically in either install path.\n\nRequires [`uv`](https://docs.astral.sh/uv/) for the scripts (or `python3` + `pyyaml`).\n\n## Use it\n\n**Capture knowledge** — ask Claude to \"document the auth service in OKF\", or run:\n\n```shell\n/okf:okf produce .okf\n```\n\n**Validate** before committing:\n\n```shell\n/okf:validate .okf --strict\n# or directly:\nuv run skills/validate/scripts/okf_validate.py .okf --strict\n```\n\n**Visualize** the knowledge graph — a self-contained `viz.html` that opens in any\nbrowser ([live example](https://scaccogatto.github.io/okf-skills/)):\n\n```shell\n/okf:visualize .okf\n# or directly, with a title and a back-link to your repo:\nuv run skills/visualize/scripts/okf_visualize.py .okf \\\n  -o viz.html --title \"My project\" --link \"https://github.com/me/project\"\n```\n\nEvery concept gets a shareable deep link — open `viz.html#services/auth-api` and the\ngraph loads with that concept already selected.\n\n**Turn on automatic upkeep (soft mode).** This plugin ships *no hooks* by design.\nTo have Claude consult `.okf/` before tasks and write knowledge back after changes,\npaste [`templates/CLAUDE-okf.md`](templates/CLAUDE-okf.md) into your project's\n`CLAUDE.md` (or `~/.claude/CLAUDE.md` for all projects).\n\n## How a bundle looks\n\n```\n.okf/\n├── index.md                  # progressive disclosure (root carries okf_version)\n├── log.md                    # ISO-dated change history, newest first\n├── services/\n│   ├── index.md\n│   └── auth-api.md           # one concept = one file; path is its ID\n├── datasets/orders-db.md\n├── decisions/use-okf.md\n├── runbooks/payment-failures.md\n└── metrics/checkout-conversion.md\n```\n\nEach concept needs only one thing to be conformant: YAML frontmatter with a\nnon-empty `type`. Everything else is optional and tolerated when missing.\n\n```markdown\n---\ntype: Service\ntitle: Auth API\ndescription: Issues and verifies short-lived access tokens.\nresource: https://github.com/acme/auth\ntags: [auth, platform]\ntimestamp: 2026-06-14T10:00:00Z\n---\n\n# Endpoints\n| Method | Path     | Description                |\n|--------|----------|----------------------------|\n| `POST` | `/token` | Exchange creds for a JWT.  |\n```\n\n## Repository layout\n\n```\nokf-skills/\n├── .claude-plugin/{plugin.json, marketplace.json}\n├── skills/okf/{SKILL.md, reference/SPEC.md, templates/}\n├── skills/validate/{SKILL.md, scripts/okf_validate.py}\n├── skills/visualize/{SKILL.md, scripts/okf_visualize.py}\n├── examples/sample-bundle/      # the live-demo bundle\n├── docs/                        # GitHub Pages: the live interactive demo\n├── templates/CLAUDE-okf.md\n└── .github/workflows/ci.yml\n```\n\n## Contributing\n\nIssues and PRs welcome — new templates, producers for more sources, validator and\nvisualizer improvements. CI validates the plugin manifest and the example bundle on\nevery push.\n\n## Credits \u0026 license\n\n- The **Open Knowledge Format** specification is by the Google Cloud Data Cloud\n  team, released under Apache-2.0. `skills/okf/reference/SPEC.md` is vendored\n  verbatim from the [reference repository](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf)\n  with attribution.\n- This plugin's own code and content: **MIT** © Marco Boffo ([@scaccogatto](https://github.com/scaccogatto)).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscaccogatto%2Fokf-skills","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscaccogatto%2Fokf-skills","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscaccogatto%2Fokf-skills/lists"}