The OKF agent skill

The okf agent skill is what turns a general coding agent into one that reads and writes the format with judgment. It carries the playbooks the agent follows to produce, maintain, search, and consume a bundle, and it ships inside the gem, so any skill-reading agent picks it up on install. The CLI computes what is true about a bundle; the skill decides what to do about it.

What it is

The gem carries a companion agent skill: a SKILL.md plus playbooks, reference files, and templates under lib/okf/skill/. Install it into any coding agent that reads skills and the agent becomes the OKF expert in your repository. It knows how to model concepts, keep a bundle in sync with the code, judge its curation quality, retrieve answers from it without reading it whole, and use it as context for real tasks.

Because the skill ships inside the gem, installing the gem already puts the skill on your machine, and the skill's CLI reference can never drift from the executable it was released with.

The skill carries the judgment; the okf CLI handles the mechanics. That split is the whole design.

Three lenses

The skill teaches the agent to judge a bundle by three separate questions and never conflate them:

Lens	Question	Tool	Nature
Legal	Is it conformant OKF (section 9)?	okf validate	Binary, tolerant
Good	Is it navigable, complete, fresh?	okf lint	Advisory, structural
True	Is it consistent and current?	The agent, reasoning over lint --json	Semantic, needs meaning

validate is forbidden by the spec from failing a bundle over broken links or missing optional fields; that is lint's job. And neither tool can judge contradictions or semantic staleness, the concept that parses fine but no longer matches reality. Only an agent reasoning over meaning can, and that third lens is where the skill earns its keep. The conformance model explains why the first two stay separate.

The division of labor

The CLI is the agent's eyes; the agent is the judgment.

• The agent shells out, never eyeballs, anything a verb computes: conformance, what exists, what links where, what is stale, the map. Every read verb takes --json, and the list views filter by type, area, and tag, so the agent asks the narrow question instead of paging through the bundle.
• The agent judges what the CLI cannot: contradictions, semantic staleness, whether a loose file is terminal by design, whether a singleton tag is a deliberate marker. Tool output is evidence, never a verdict.

The checks are deterministic and always run through the executable. The skill never lets the agent reason out conformance by hand.

The verbs

The skill routes eight verbs, each with its own playbook. In Claude Code they run as /okf:gem <verb>; used standalone, the skill infers the verb from your request.

Verb	What it does
orient	No arguments: read the bundle's state and recommend the highest-value next move, never auto-running one
search	Answer a question from the bundle, token-lean: map, finder, and only the winning bodies
produce	Create or extend a bundle from code, docs, or knowledge in people's heads
migrate	Adopt existing Markdown docs in place: frontmatter and reserved files added, bodies kept verbatim
maintain	Sync the bundle's content with reality after the code or docs change
consume	Use the bundle as context for a task, writing back what you learn
curate	Structural upkeep as the bundle stands: validate + lint + loose
doctor	Install and verify the CLI, then doctor the bundle

Any CLI verb works as an argument too: the skill runs it and interprets the output through the three lenses.

Which target

A verb needs a bundle, and since 1.9.0 the skill treats a name as a first-class way to say which one. A leading @ is a registry ref, not a path: @slug names a registered bundle and bare @ the registry default, so the skill routes straight to okf <verb> @slug instead of hunting for a directory. okf search takes several at once (@a @b, or @all). A plain path is used as given. Given no target at all and a working directory that carries no bundle, the next move is okf registry list rather than a search across sibling directories.

Pointed at a directory that holds Markdown but no bundle root, the skill does not grind through the conformance errors: it suggests migrate and lets you choose. The CLI's own error teaches the same grammar, so a mistyped path answers with @slug addressing instead of leaving you to find it.

The skill also stopped checking whether the CLI is installed. It used to spend a round on a presence probe before every task; now it runs the verb, and treats a shell "command not found" as the only signal to install. A line that begins error: is the CLI answering, a bundle or usage result to read, never a missing toolchain. The two exceptions are the verbs that exist to decide whether to install: orient and doctor.

Install it

Point the installer at your agent's config directory and the skill settles into its own skills/okf/ folder:

okf skill .claude     # Claude Code      -> .claude/skills/okf
okf skill .agents     # agent-agnostic   -> .agents/skills/okf

The destination is required; there is no default. The tree lands in <dest>/skills/okf, unless <dest> already ends in skills (then <dest>/okf) or in okf (used as-is). Pass --here to paste the tree straight into <dest>, wherever it is. The resolved directory must be empty unless you pass --force, so a customized skill is never clobbered. okf skill documents the full command.

Using Claude Code? The plugin carries this same canonical skill, plus the /okf:gem command and a post-edit curation hook.

The flywheel

The lifecycle is a flywheel, not phases. Produce seeds a bundle; consume reads it; maintain runs whenever reality drifts or whenever consuming teaches the agent something durable. That write-back reflex is what keeps a bundle alive instead of rotting into folklore: learn something while consuming, switch to maintain, record it.

Curation is continuous, not a phase. Curate settles structural debt whenever it accumulates, and with the plugin active, every edit inside a bundle gets validated and linted on the spot.