The Problem

Project knowledge fragments across wikis, code comments, and memory stores, forcing agents to rediscover context every session. OKF provides a single, versioned, diffable home for curated knowledge alongside code, but the toolkit itself shows signs of structural strain that increase cognitive load for anyone extending or maintaining it.

What This Does

okf-skills is a Claude Code-native toolkit for authoring, maintaining, validating, and visualizing Open Knowledge Format bundles. The repository contains 77 files across Markdown (47), Python (4), JSON (2), YAML (2), and HTML (2). It ships as both a Claude Code plugin and installable skills.sh package. The .okf/ directory documents the architecture, decisions, and skills themselves in OKF format, with CI validating the self-documenting bundle on every push. Skills live in skills/okf/, skills/validate/, and skills/visualize/, each with their own scripts and SKILL.md files. A benchmark directory contains measured agent performance data comparing bundles with and without .okf/ present.

How It Is Wired

Execution starts at main in skills/okf/scripts/okf_init.py:77, which reaches 33 function(s) and is called from 1 place. The internal call graph contains 123 resolved call edges between self-functions. run_check is the most widely called function (20 call sites), followed by concept (16) and only (15). Key entry-point-to-workflow paths: main -> migrate [filesystem via path.read_text]. skills/okf/scripts/okf_init.py defines humanize, frontmatter, build_index, build_log, build_concept. skills/validate/scripts/okf_validate.py defines err, warn, split_frontmatter, _read_text, check_computation and is called from 3 other files. skills/visualize/scripts/okf_visualize.py defines json_for_script, split_frontmatter, link_targets, resolve, read_sources and is called from 2 other files. The code touches 12 function(s) that read or write files outside the process. check_concept -> err occurs x4, check_links -> resolve x4, and test_computation_paths_that_point_nowhere_warn -> run_check x3.

Measured findings (static analysis, 6 total):

  • [HIGH/cognitive_load] Deep nesting x3 in skills/validate/scripts/okf_validate.py, skills/visualize/scripts/okf_visualize.py, and tests/test_okf_validate.py — max indentation depth 8 makes control flow hard to follow. Fix: flatten with early returns/guard clauses.
  • [MEDIUM/clarity] Duplicated code blocks in skills/validate/scripts/okf_validate.py and skills/visualize/scripts/okf_visualize.py — 4 repeated 6-line blocks across 2 files. Fix: extract shared helpers.
  • [MEDIUM/cognitive_load] High branching density x2 in the same 2 files — 144 branch points over 448 lines. Fix: decompose decision-heavy logic; consider table/strategy dispatch.

Code health audit (3 findings, 0 critical):

  • [HIGH] Pin third-party GitHub Actions to commit SHA — .github/workflows declares astral-sh/setup-uv@v5; tags can move, risking secrets running with whatever the owner last pushed.
  • [MEDIUM] Declare least-privilege permissions for GITHUB_TOKEN — 1 workflow declares no permissions; token inherits repository default, allowing injected steps to push commits or mint releases.
  • [LOW] Set timeout-minutes on workflow jobs — 1 workflow declares no job timeout; wedged step runs to six-hour platform default.

How To Use It

Setup: Install the Claude Code plugin via /plugin install okf@scaccogatto or add the skills package with npx skills add scaccogatto/okf-skills (documented in README and action.yml). The repo has no Dockerfile; build relies on the Makefile and GitHub Actions CI.

Configuration: No environment variables or keys are required for basic operation. The OKF spec lives at skills/okf/reference/SPEC.md and skills/okf/reference/APACHE-2.0.txt.

Running it: The entry point is skills/okf/scripts/okf_init.py — specifically the main function at line 77. This initializes the OKF bundle, builds the index, and renders the self-documenting graph. CI on every push validates the .okf/ bundle via the conformance checker in skills/validate/scripts/okf_validate.py.

Real-World Use

A team maintaining a codebase adds an .okf/ directory alongside their repository to capture curated knowledge about architectural decisions, APIs, and troubleshooting guides. Editors and agents use the okf_init skill to generate the initial bundle structure, okf_validate to ensure conformance on each PR, and okf_visualize to produce an interactive graph (hosted at https://scaccogatto.github.io/okf-skills/) showing links, trust tiers, and staleness. When a developer updates a markdown file with YAML frontmatter, the validation pipeline catches broken links, invalid date formats, and trust violations before merge, and the visualization updates automatically to reflect the changed graph.

Code Health & Issues

The static analysis identified 3 code health findings across the repository. The high-severity finding concerns unpinned GitHub Actions in .github/workflows — astral-sh/setup-uv@v5 should be pinned to a 40-character commit SHA to prevent secrets from running with unintended action versions. The medium-severity finding requires adding permissions: contents: read at the top of the CI workflow and widening per-job only where needed. The low-severity finding requests adding timeout-minutes to each workflow job to prevent wedged steps from overlapping on the two-hourly schedule beyond the six-hour platform default. Beyond these, the repository has no structural red flags: tests and CI are present, license is declared, no committed secrets were found, and a lockfile is absent (expected for a Python project using uv).

The Bottom Line

okf-skills delivers a practical, vendor-neutral format for versioned project knowledge with good tooling for validation and visualization, but the codebase shows measurable cognitive-load issues from deep nesting and duplicated blocks that should be addressed before onboarding new contributors. The Action pinning and permission declarations are the most urgent SDLC fixes. Teams already invested in Claude Code and OKF bundles will find immediate value; others should evaluate whether the format's structured markdown approach aligns with their knowledge-management needs.

Clone: https://github.com/moses-y/okf-skills (verbatim)