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'sskills/. 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: forkwithagent: 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);@fileinlines a file. Long references go in other files of the directory, read when needed. - Check:
oklm agent skills validate DIR; theskill-creatorskill walks you through writing one./skillsshows them, their tokens in the prompt and their problems;/skill-doctortheir 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 ageneratecallback, 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.