okf-gem

okf-gem (okf on RubyGems or Docker) gives your project's knowledge one durable home in your repo, in Markdown your team and your agents both read: the decisions and the reasoning an agent cannot re-derive from the code, versioned beside the code they explain.

One install carries the whole workflow, and that is the point of a single gem:

• an Agent Skill, so your agent writes and curates the knowledge instead of you;
• a CLI and Ruby library, so it stays correct: validated, linted, and searchable in milliseconds;
• a Graph, so anyone can see the shape of what the team knows, live or as one static file you can host anywhere.

The package is Agent Skill + CLI/Lib + Graph. It runs 100% local, adds no service to your stack, and does not define a new place to keep knowledge: it gives you leverage over the Markdown you already have.

Why OKF

Project knowledge (why a service exists, what a metric really measures, the reasoning a schema encodes) lives scattered across wikis, code comments, and whoever happened to be in the room, and an agent re-derives it every session. OKF gives it one durable, diffable home, versioned next to the code it describes and read from the same file by people and agents alike. OKF is an open, vendor-neutral format (Google Cloud, 2026); this gem is the Ruby-native way to work with it.

Knowledge already has several homes near an agent, and each holds a different thing. None of the others is built for curated, durable team knowledge:

The last two rows are this gem's job. Scaling past one context window is progressive disclosure — okf index reads the map, okf search pulls only the concepts a task needs, so the bundle is never loaded whole. And drift never hides here: the other homes have no detector, but okf validate and lint turn a bundle's drift into findings you can gate on in CI.

What a bundle looks like

A bundle is just a directory; each concept is one Markdown file whose path is its id. This repo documents itself in OKF, so the tree below is real:

.okf/
├── index.md                       # progressive-disclosure map (root carries okf_version)
├── log.md                         # ISO-dated change history, newest first
├── overview.md
├── format/frontmatter.md
├── model/graph.md
└── capabilities/graph-server.md   # one concept = one file

The only hard requirement is YAML frontmatter with a non-empty type; everything else is optional and tolerated when missing. A concept (here the real capabilities/graph-server.md, body trimmed) reads:

---
type: Capability
title: Interactive graph server (server)
description: A self-contained HTML knowledge graph served over HTTP, and a mountable Rack app.
resource: okf/lib/okf/server/app.rb
tags: [server, graph, rack, diagram]
timestamp: 2026-07-11T12:00:00Z
---

# Overview

`okf server` boots an interactive view of the [graph](../model/graph.md) …

That bundle is this gem's own documentation. Clone the repo and run okf server .okf to browse it as an interactive graph.

Try it in four steps

From zero to your first bundle.

1. Get the okf command. Two ways in; either one puts okf on your PATH.

gem install okf                                        # with Ruby
curl -fsSL https://docker.okfgem.com/install.sh | sh   # no Ruby? Docker

2. Install the skill. Teach your agent the format — Claude Code, or any other agent.

okf skill .claude   # or: okf skill .agents

3. Start an agent session where your project lives.

claude

4. Make your first bundle. Two ways in, by what you already have: docs keep every word, code gets written up for you.

/okf migrate <path-to-your-docs>            # have docs? adopted in place, bodies verbatim
/okf produce based on <path-to-your-code>   # only code? the skill authors the concepts

[!TIP] Once you have a bundle, run /okf maintain in the agent session to keep it in sync as the code changes, and okf server <folder> to explore it as a graph. In Claude Code, the plugin adds a post-edit curation hook that runs validate + lint for you.

The package, end to end:

What the gem does, and which verb does it. This table is the map; the docs are the manual.