Skills system

Skills are reusable, user-defined or community-built capabilities that extend your agent without recompiling Revka. A skill bundles markdown instructions, optional tool definitions (shell commands or HTTP calls), and metadata into a single directory on disk. Revka discovers skills at startup, injects them into the agent’s context, and exposes them to external MCP clients through three compact meta-tools instead of registering every skill as its own tool.

Use this page to understand the on-disk skill model, run skills over MCP, sync the community open-skills library, and configure autonomous skill creation and improvement. For installing, auditing, and testing skills from the command line, see revka skills, workflows & sop. For managing skills over HTTP, see the Agents, skills & teams API.

How skills work

A skill lives in its own directory under your workspace:

~/.revka/workspace/skills/
  release-notes/
    SKILL.toml      # or SKILL.md — the manifest (required)
    PROMPT.md       # optional external prompt content
    TEST.sh         # optional validation cases (see CLI page)

At startup Revka scans <workspace>/skills/ (and, when enabled, the open-skills directory) and loads every directory whose root contains a SKILL.md or SKILL.toml manifest. Each loaded skill contributes two things to the running agent:

• Prompt content — the markdown body or prompts array, injected so the agent knows when and how to use the skill.
• Tools — any [[tools]] entries, exposed to the agent as <skill_name>.<tool_name> (dot-separated). For example, a list_merged tool in the release-notes skill becomes release-notes.list_merged.

Note

The dot-separated naming (<skill>.<tool>) is distinct from the double-underscore convention (<server>__<tool>) used for external MCP server tools. Skill tools are native Revka tools, not proxied MCP tools.

Authoring a skill

A manifest can be written in either of two formats.

SKILL.toml

A structured manifest with a [skill] table and an optional [[tools]] array:

[skill]
name = "release-notes"
description = "Summarize merged PRs into release notes."
version = "1.0.0"             # defaults to "0.1.0" if omitted
author = "[email protected]"   # optional
tags = ["git", "writing"]    # optional
content_file = "PROMPT.md"   # optional: external markdown used as prompt content

# Optional embedded prompt content (ignored when content_file is set)
prompts = [
  "You write concise, accurate release notes.",
]

[[tools]]
name = "list_merged"
description = "List merged PRs since a tag."
kind = "shell"               # "shell" | "script" | "http"
command = "gh pr list --state merged --search 'merged:>{{since}}'"

# args is a string→string map of named template parameters
[tools.args]
since = "v1.0.0"

Field	Type	Default	Meaning
skill.name	string	— (required)	Unique skill name
skill.description	string	— (required)	Human-readable purpose
skill.version	string	"0.1.0"	Semantic version
skill.author	string	—	Optional author label
skill.tags	string[]	[]	Classification tags
skill.content_file	string	—	Path (relative to the manifest) to a markdown file used as prompt content; when set, the embedded prompts array is ignored
prompts	string[]	[]	Embedded prompt content injected into the agent
tools[]	table[]	[]	Tool definitions (see below)

SKILL.md

A markdown file with YAML front matter for metadata and the body as prompt content. Use this form for instruction-only (“markdown-only”) skills, or add a [[tools]]-style section for tools:

---
name: code-review-checklist
description: A reusable checklist for reviewing pull requests.
version: 1.0.0
tags: [review, quality]
---

When reviewing a pull request, walk through this checklist:

1. Does every changed line trace to the stated intent?
2. Are error paths and edge cases covered by tests?
3. Are there secrets, credentials, or PII in the diff?

A markdown-only skill has no tools — its entire value is the instructions in the body, which the agent reads and follows.

Tool kinds

Each [[tools]] entry declares a kind:

kind	What it does	Limits
"shell" / "script"	Executes a shell command via sh -c; supports {{arg_name}} template substitution	60s timeout, 1 MB output cap, runs in a sandboxed environment (safe vars only)
"http"	Performs a GET against a URL template	30s timeout, 1 MB response cap, only http:// and https:// URLs allowed

Field	Type	Meaning
name	string	Tool name; exposed to the agent as <skill_name>.<tool_name>
description	string	What the tool does
kind	string	"shell", "script", or "http"
command	string	The shell command, script, or URL to run; supports {{arg_name}} substitution
args	map	Optional string→string map of named template parameters

Caution

Shell and script tools are medium-risk because they run user-defined code. They require approved: true (or supervised/autonomous mode) before they execute. Script files inside a skill (.sh, .ps1, shebang shell files) are blocked entirely unless you set skills.allow_scripts = true. See the security model and the CLI security audit rules.

Running skills via MCP meta-tools

Exposing every skill as a separate MCP tool would balloon a client’s tool list — a workspace can easily hold 50+ skills. Instead, Revka’s MCP server registers three compact meta-tools that let any external client (Claude Desktop, Claude Code, Codex, and so on) discover and run all your skills. These tools appear in the extended tool registry.

skills_list

Lists every visible skill. Takes no parameters.

// tools/call → skills_list
{}

Returns a JSON array of skill summaries:

[
  {
    "id": "release-notes",
    "name": "release-notes",
    "description": "Summarize merged PRs into release notes.",
    "version": "1.0.0",
    "tags": ["git", "writing"],
    "tool_count": 1,
    "location": "workspace"
  }
]

skills_describe

Returns the full body and metadata for a single skill, including its tools array.

// tools/call → skills_describe
{ "skill_id": "release-notes" }

skills_execute

Runs a skill’s sub-tool, or returns the body for a markdown-only skill.

// tools/call → skills_execute
{
  "skill_id": "release-notes",
  "tool": "list_merged",          // optional; defaults to the first [[tools]] entry
  "arguments": { "since": "v2.0.0" }
}

• If tool is omitted, the skill’s first [[tools]] entry runs.
• For a markdown-only skill, skills_execute returns the markdown body verbatim so the calling LLM can follow the instructions directly.

Note

These three tools register only when the in-process MCP server is running. They are part of the extended registry, alongside the productivity integration tools. See Revka as an MCP server for the registry tiers and how external CLIs discover the server via ~/.revka/mcp.json.

The read_skill tool

When the agent runs in compact prompt mode (prompt_injection_mode = "compact"), skill bodies are not pre-injected into the system prompt — only the skill names appear. The built-in read_skill tool loads a single skill’s source file on demand by name:

Parameter	Type	Meaning
name	string (required)	The exact skill name as listed in <available_skills>

// tool call → read_skill
{ "name": "release-notes" }

It returns the full file content (markdown or TOML). This keeps the system prompt small on low-context models while still letting the agent pull in a skill’s full instructions exactly when it needs them.

Open Skills

Open Skills is an optional community library synced from the besoeasy/open-skills GitHub repository. When enabled, Revka syncs the repository to a local directory on a 7-day interval and merges those skills into the agent’s visible skill set alongside your workspace skills.

[skills]
open_skills_enabled = true
open_skills_dir = "~/.revka/open-skills"   # optional override
allow_scripts = false                       # keep scripts blocked

Caution

Synced open skills are run through the same static security audit as installed skills before they load. Script files in them remain blocked unless you set allow_scripts = true. Only relax this if you trust the source.

The [skills] config

The [skills] section in ~/.revka/config.toml controls skill loading, the community library, and the autonomous create/improve behavior. Every key also has an environment-variable override.

[skills]
open_skills_enabled = false        # opt-in community library
open_skills_dir = "~/open-skills"
prompt_injection_mode = "full"     # "full" (inline) or "compact" (on-demand)
allow_scripts = false              # allow script files in skills

[skills.skill_creation]
enabled = false                    # auto-create skills from successful tasks
max_skills = 500                   # LRU eviction limit
similarity_threshold = 0.85        # dedup threshold

[skills.skill_improvement]
enabled = true                     # auto-improve skills after successful use
cooldown_secs = 3600               # min interval between improvements per skill

Key	Default	Env override	Meaning
open_skills_enabled	false	REVKA_OPEN_SKILLS_ENABLED	Enable the open-skills community library
open_skills_dir	~/open-skills	REVKA_OPEN_SKILLS_DIR	Local path for synced open skills
prompt_injection_mode	"full"	REVKA_SKILLS_PROMPT_MODE	full (inline) or compact (on-demand via read_skill)
allow_scripts	false	REVKA_SKILLS_ALLOW_SCRIPTS	Allow .sh/.ps1/shebang shell files in skills
skill_creation.enabled	false	—	Auto-create skills from successful multi-step tasks
skill_creation.max_skills	500	—	Cap on auto-generated skills; oldest evicted (LRU)
skill_creation.similarity_threshold	0.85	—	Embedding similarity above which a new skill is skipped as a duplicate
skill_improvement.enabled	true	—	Auto-improve a skill after it is used successfully
skill_improvement.cooldown_secs	3600	—	Minimum interval between improvements for the same skill

Tip

Set prompt_injection_mode = "compact" on low-context or local models. It keeps the system prompt small by listing only skill names and loading bodies on demand through read_skill.

Skill creation and improvement

When skill_creation.enabled = true, Revka can autonomously create a new skill after a successful multi-step task, capturing the procedure for reuse. New skills are deduplicated against existing ones by embedding similarity (similarity_threshold, default 0.85), and the library is bounded by max_skills (default 500) with LRU eviction of the oldest auto-generated skills.

When skill_improvement.enabled = true (the default), Revka improves existing skills after they are used successfully, refining their instructions over time. A cooldown_secs (default 3600) prevents a single skill from being rewritten more than once per interval.

Both behaviors are opt-in-tunable and safe to leave at their defaults: improvement on, creation off.

Skill Management (operator)

Beyond disk-based skills, the Operator MCP maintains a versioned skill store in Kumiho graph memory. Operator skills are stored as SKILL.md artifacts under <memory_project>/Skills/ and carry effectiveness scores, so the system prompt builder can rerank skills by recency-weighted success. The operator exposes these MCP tools:

Tool	Purpose
capture_skill	Capture or update a skill as a Kumiho revision artifact
list_skills	List skills from Kumiho (optionally including legacy disk skills)
load_skill	Load a skill’s SKILL.md content by name or kref (tag defaults to "published")
get_skill_effectiveness	Rolling success rate from recorded outcomes
record_skill_outcome	Record whether a skill use succeeded or failed
search_clawhub	Search the ClawHub marketplace
install_from_clawhub	Install a community skill by slug
browse_clawhub	List trending ClawHub skills

Caution

Use capture_skill to persist a skill — not memory_store. capture_skill writes a proper SKILL.md revision artifact; memory_store writes a generic memory bundle and will not be recognized as a skill.

The "published" tag marks the current active version of a skill. Skill effectiveness scoring (record_skill_outcome → get_skill_effectiveness) feeds back into prompt construction so well-performing skills surface first.

ClawHub marketplace

ClawHub is the skill marketplace for browsing and installing community skills. Anonymous browsing and installing work without a token; a token is only needed for publishing.

[clawhub]
enabled = true
api_url = "https://clawhub.ai"
api_token = "clh_..."    # only needed for publishing

The dashboard surfaces ClawHub under its Skills view, backed by the gateway endpoints GET /api/clawhub/search, GET /api/clawhub/trending, GET /api/clawhub/skills/{slug}, and POST /api/clawhub/install/{slug}. See the Skills, tools & integrations dashboard pages.

Managing skills over HTTP

The Revka dashboard’s skills UI is backed by the /api/skills gateway endpoints (all require bearer auth). Skills are stored as items of kind "skill" in the <memory_project>/Skills Kumiho space, with the content held as a SKILL.md artifact pointing at ~/.revka/workspace/skills/<slug>.md.

Method + path	Purpose
GET /api/skills	List skills; query params: include_deprecated, q (fulltext), page, per_page (max 50)
GET /api/skills/:kref	Fetch a single skill with full content
POST /api/skills	Create a skill; body { name, description, content, domain, tags? } → 201 with { skill }
PUT /api/skills/:kref	Update a skill (creates a new revision)
POST /api/skills/deprecate	Enable/disable a skill; body { kref, deprecated: bool }
DELETE /api/skills/:kref	Permanently delete a skill

The :kref is the path after kref://, for example CognitiveMemory/Skills/my-skill.skill. Responses are served from a 30-second in-process cache that is invalidated on any write. Full request and response shapes are documented on the Agents, skills & teams API page.

Related pages

revka skills, workflows & sop Install, audit, test, and remove skills from the command line.

Revka as an MCP server The in-process MCP server, registry tiers, and discovery file.

Agents, skills & teams API Full /api/skills request and response shapes.

Operator MCP The orchestration sidecar that hosts capture_skill and ClawHub tools.

Skills, tools & integrations The dashboard Skills view and ClawHub browser.

Security model Why shell skill tools need approval and how the audit works.