Skip to content
okf-cli
GitHub

Agent onboarding: MCP server, skill and okf prime

After this page your agent calls okf through MCP tools or the shell: one okf install registers the skill and the MCP server, and okf prime teaches the agent the catalogue in one call.

This page covers the MCP server for a markdown knowledge base, the Claude Code setup, okf prime and the agent skill. Output below comes from okf 0.2.5.

One command: okf install

okf install registers okf with every agent and shell it finds on the machine. It needs no catalogue. Without flags it prints a plan and changes nothing.

  1. Preview the plan.

    Terminal
    okf install

  2. Read the plan. A line marked BLOCKED stops the apply and makes the command exit 1, even for a plan.

  3. Apply it.

    Terminal
    okf install --apply

  4. Open a new shell and restart your agents.

A second --apply changes nothing. In a throwaway home directory:

okf install --apply --only opencode,kimi,hermes (second run)
$ okf install --apply --only opencode,kimi,hermes | tail -3
  unchanged hermes    mcp_servers.okf in ~/.hermes/config.yaml


nothing to do: already up to date
[exit 0]

--only narrows the run to a comma-separated list of agents (claude, omp, codex, opencode, kimi, openclaw, hermes) and shells (zsh, bash, fish). --uninstall --apply removes what install created. Details: okf install.

An agent counts as detected when its binary is on PATH or its configuration directory exists.

MCP server

The server is a thin wrapper: each tool runs the okf binary with --json and returns the data and warnings of the envelope. Correctness stays in the binary.

  • 21 tools. Every tool takes root (catalogue path; default: search upward from the server’s working directory, then ~/.config/okf/config.toml) and use_global. Passing both fails with invalid_input.
  • Binary lookup order: $OKF_BIN, then bin/okf or go/bin/okf next to mcp/, then okf on PATH.
  • A result longer than OKF_MCP_MAX_CHARS (default 120000) is an error that asks the caller to narrow the call.
  • Not exposed as tools: verify, migrate, archive, merge-tags, normalize-tags, remove-tags, registry convert, fix-*, rewrite-path, visualize, recent and the ctx write verbs.
  • okf_reindex has no check argument, so the tool writes. This comes from the tool signature in mcp/okf_mcp.py; no MCP call was run.

Where okf install puts the entry:

The plan runs the Claude Code CLI:

okf install --only claude (plan line)
create    claude          run: claude mcp add --scope user --transport stdio okf -- uv run --with 'mcp<2' <keg>/mcp/okf_mcp.py

The skill goes to ~/.claude/skills/okf. Without claude on PATH, install merges mcpServers into ~/.claude.json.

<keg> is the package root: the Homebrew prefix or the clone. To register the server by hand, use the same uv run --with 'mcp<2' <path>/okf_mcp.py command in your agent’s MCP configuration.

Skill

The okf skill in skills/okf teaches an agent the commands and the OKF v0.2 rules. SKILL.md says it operates catalogues with the command line tool or its okf_* MCP tools. It alone is enough for search only. Flags, previews and provenance rules live in its references/ files (context bundles, create a bundle, maintain a catalogue, migrate to v0.2, write concepts).

okf install copies the skill from a package, or links it from a source tree:

Agent Skill directory
Claude Code ~/.claude/skills/okf
Codex, omp, opencode, Kimi Code ~/.agents/skills/okf (shared)
Hermes ~/.hermes/skills/okf
OpenClaw ~/.openclaw/skills/okf

--uninstall keeps the shared directory while another agent still reads it.

okf prime

okf prime is the first call of an agent session. One call prints the usage guide, the command directory by purpose, and the state of the catalogue: root, bundle and concept counts, whether the search indexes exist, the tag vocabulary and the context bundles.

okf --root <catalogue> prime --compact (excerpt)
## This catalogue


root: <catalogue>
bundles: 4 · concepts: 24
fts index: absent — `find` degrades to a substring scan; run `build-index`
semantic index: absent — `find` runs its lexical arm only
tag vocabulary: closed — 11 tags in TAGS.md; check a new one with `tags --validate`, adopt it with `tags --register`
ctx bundles: 3 — cooking · legacy · onboarding — `ctx show <slug>` lists one
root docs: SPEC.md · TYPES.md · PROPERTIES.md · TAGS.md


## Bundles


- _ctx (3 concepts)
- handbook (10 concepts)
- kc-gov (2 concepts)
- recipes (9 concepts)
  • --compact lists bundles as name and count. --full adds types and tags per bundle. --check-semantic runs the exact semantic coverage check instead of only reporting whether the index exists.
  • --json prints an envelope whose data holds guide, commands, find, state and bundles. Over MCP the same call is okf_prime.
  • When the semantic index is partial, the state text names cli/embeddings/build_tagvec.py, which a Go install does not ship (known issue erpf). Ignore the script name; okf build-tagvec --produce is the Go command.

llms.txt and llms-full.txt

The site publishes two plain-text files for agents that read the web:

  • llms.txt: an index of all pages with title, URL and description.
  • llms-full.txt: the text of every page in one file.

Reference

okf installPlan, apply, uninstall, --only.
okf primeOptions and output shape.
JSON output and exit codesThe envelope the MCP tools return.
Known limitationsfs8c, erpf and more.