OKLMdocumentation v1.0.3
On this page

Extending the OKLM agent

Every way to add to oklm agent: skills and prompt commands, sub-agent types, hooks, MCP servers, plugins, declared services, and the library API for programs that embed the agent. The details are in agent-extensions.md and the other parts of harness.md.

Status: maintained.

Skills

A skill is a directory holding a SKILL.md: a header the model always sees and instructions it reads only when a task matches.

---
name: release-notes
description: Write the release notes of a version from its commits. Use when the user asks for release notes or a changelog.
argument-hint: [version]
allowed-tools: Bash(git log:*), Read, Write(CHANGELOG.md)
---
1. git log --oneline PREVIOUS..$ARGUMENTS ...
  • Where: .oklm/skills/NAME/ (the project's, committed), ~/.config/oklm/skills/NAME/ (yours), a plugin's skills/. A project skill wins over yours; yours over a built-in.
  • Header: name (kebab-case), description (what and when: the model chooses from it alone), argument-hint, allowed-tools (allowed without asking while it runs), disable-model-invocation: true (only you start it, as /NAME), user-invocable: false (only the model), context: fork with agent: TYPE (it runs as a sub-agent), model.
  • Body: $ARGUMENTS (or $0, $1...) takes the arguments; !`command` puts a command's output in (through the permissions); @file inlines a file. Long references go in other files of the directory, read when needed.
  • Check: oklm agent skills validate DIR; the skill-creator skill walks you through writing one. /skills shows them, their tokens in the prompt and their problems; /skill-doctor their use.

Prompt commands

A single Markdown file in .oklm/commands/ (or ~/.config/oklm/commands/) is a command named after the file (deploy.md is /deploy, a sub-directory a namespace: frontend/component.md is /frontend:component), the same header and body as a skill.

Sub-agent types

A Markdown file in .oklm/agents/ (or ~/.config/oklm/agents/):

---
name: db-expert
description: Answers questions about the database schema and queries.
tools: Read, Grep, Glob, Bash(psql:*)
skills: [database]
---
You know this project's database...

The model starts it with the Agent tool (subagent_type); /agents lists and writes them.

Hooks

The hooks setting: commands run on events, the event as JSON on their standard input; exit 2 (or {"decision": "block"}) blocks, a JSON answer can approve, change a call's input or add context.

{"hooks": {
  "PreToolUse": [{"matcher": "Edit|Write", "hooks": [{"type": "command", "command": "./scripts/lint.sh", "timeout": 60}]}],
  "ProcessExit": [{"matcher": "service", "hooks": [{"type": "command", "command": "notify-send \"service ended\""}]}]
}}

Events: SessionStart, SessionEnd, UserPromptSubmit, PreToolUse, PostToolUse, Notification, Stop, SubagentStop, PreCompact, ProcessStart, ProcessExit, MonitorEvent, WorktreeCreate (makes the worktree instead of git: given name, base and path, prints the path it made), WorktreeRemove (path, branch: removes what WorktreeCreate made), CommandRun, DirectoryAdded, ServiceReady (a declared service passed its readiness probe: name, id, pid, ports, probe; matched on the name).

MCP servers

oklm agent mcp add github --transport http --header "Authorization: Bearer \${GITHUB_TOKEN}" https://api.example.com/mcp
oklm agent mcp add fs --scope project -- npx -y @modelcontextprotocol/server-filesystem .

Or mcpServers in the settings, .mcp.json in the project (approved once), --mcp-config FILE. Their tools are mcp__SERVER__TOOL (rules: mcp__SERVER), their resources @SERVER:URI, their prompts /mcp__SERVER__PROMPT. /mcp shows them.

Plugins

A plugin bundles the above in one directory:

NAME/
  .oklm-plugin/plugin.json   {"name": "NAME", "version": "1.0.0", "description": "..."}
  commands/                  /NAME:COMMAND
  skills/SKILL/SKILL.md      NAME:SKILL
  agents/                    NAME:AGENT
  hooks/hooks.json           {"hooks": {...}}; ${OKLM_PLUGIN_ROOT} is the plugin's directory
  .mcp.json                  {"mcpServers": {...}}

oklm agent plugin install DIR|GIT-URL|NAME@MARKETPLACE; a marketplace is a directory or repository with a marketplace.json listing plugins ({"plugins": [{"name", "source", "description"}]}), added with oklm agent plugin marketplace add NAME DIR|GIT-URL. A .claude-plugin manifest is read too.

Declared services

.oklm/services.json describes the project's long-lived processes, their dependencies, ports, readiness and monitors; see processes.md.

The library

Programs embedding the agent link liboklm and use include/oklm/harness/:

  • oklm_agent_new() with a model (or a generate callback, or an HTTP backend), oklm_agent_send(), oklm_agent_steer();
  • oklm_tool_ctx_add_tool() adds a tool of the program's own, decided by the rules by its name; oklm_hooks_add_callback() a hook as a C function;
  • oklm_headless_* writes JSON and stream-json results;
  • oklm_mcp_*, oklm_services_*, oklm_jobs_*, oklm_events_* give the MCP client, the services, the jobs and the events to a program of its own.