revka skills, workflows & sop

Three command groups cover the agent’s extensibility surface from the CLI: revka skills installs, audits, removes, and tests user-defined skill packages; revka workflows lists and seeds the built-in workflow YAML templates that ship with the binary; and revka sop lists, validates, and inspects Standard Operating Procedures defined on disk.

Use this page when you are managing capability packages and procedure definitions from the command line. Authoring is covered elsewhere — see Skills system for the skill model, Workflow YAML reference for full workflow schema, and SOP reference for the SOP syntax. Every command on this page runs offline; none require a running daemon.

revka skills

A skill is a user-defined or community-built capability stored under ~/.revka/workspace/skills/<name>/. Each skill directory carries a manifest (SKILL.md or SKILL.toml) and can define prompt content plus tools (shell or HTTP) that Revka injects into the agent at runtime.

Subcommand	Purpose
revka skills list	List all installed skills
revka skills install <source>	Install from a git URL or local path (audited first)
revka skills remove <name>	Remove an installed skill by name
revka skills audit <source>	Static security audit of a skill directory or installed skill name
revka skills test [<name>] [--verbose]	Run TEST.sh validation (all skills if name omitted)

List installed skills

revka skills list

Prints every skill discovered under the workspace skills/ directory (and, if enabled, the open-skills directory).

Install a skill

install accepts either a git remote URL or a local path:

# From a git remote (https://, http://, ssh://, or git@host:...)
revka skills install https://github.com/example/skill.git

# From a local directory
revka skills install /local/path/to/skill

Caution

install always runs the built-in security audit before accepting the skill. If the audit reports any finding, the skill is rejected. Run revka skills audit <source> first to preview findings, and see Security audit rules for what is blocked.

Remove a skill

revka skills remove my-skill

Removes the installed skill by name.

Audit a skill

audit runs the same static analysis that install uses, against either an installed skill name or a directory on disk — so you can vet a skill before installing it:

revka skills audit my-skill
revka skills audit /path/to/skill-dir

The audit scans every file in the skill directory depth-first and reports findings. A clean report means zero findings; any finding blocks installation.

Test a skill

test runs TEST.sh validation cases. Pass a skill name to test one skill, or omit it to test every installed skill:

revka skills test                 # all skills
revka skills test my-skill        # one skill
revka skills test my-skill --verbose

Flag	Meaning
--verbose	Show per-case command, expected vs. actual exit code, and output

Each line of a skill’s TEST.sh file is a test case in the form:

command | expected_exit_code | expected_output_pattern

The runner splits on | (a pipe surrounded by spaces) so that shell pipes inside the command are not mistaken for delimiters. Blank lines and lines beginning with # are ignored. The output pattern is matched as a regex when it contains regex metacharacters, otherwise as a substring.

# Example TEST.sh
revka --version | 0 | revka
revka doctor --help | 0 | Usage

SKILL.toml format

A skill manifest can be written as SKILL.toml (a structured manifest) or SKILL.md (YAML front matter plus a markdown body). The SKILL.toml form has 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 system prompt
tools[]	table[]	[]	Tool definitions (see below)

Each [[tools]] entry has:

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

Note

Tool execution details — shell/script run via sh -c (60s timeout, 1 MB output cap, sandboxed environment) and require approved: true; http does a GET against the URL template (30s timeout, 1 MB response cap, http/https only) — are documented in Skills system. Shell/script files inside a skill are blocked by default and must be opted into (see below).

Security audit rules

The audit is a deterministic static scan of the skill directory. The skill root must contain SKILL.md or SKILL.toml, or the audit fails. From there the scan blocks:

• Symlinks. Any symlink anywhere in the skill tree is rejected.
• Script files. Files with a script suffix — .sh, .bash, .zsh, .ksh, .fish, .ps1, .bat, .cmd — or any file whose shebang names a shell interpreter (sh, bash, zsh, ksh, fish, pwsh, powershell). A non-shell shebang (e.g. #!/usr/bin/env python3) is allowed.
• High-risk command patterns found in markdown bodies or in [[tools]].command / prompts strings: curl ... | sh, wget ... | sh, PowerShell iex/Invoke-Expression, rm -rf /, nc -e remote exec, dd if=, mkfs, and the classic fork bomb.
• Shell-chaining operators in a manifest tool command: &&, ||, ;, newlines, backticks, and $(.
• Manifest defects: invalid TOML, a [[tools]] entry missing command, or an empty shell/script command.
• Unsafe markdown links: absolute paths, ~/ paths, unsupported URL schemes, links to script files, remote markdown links (http/https/mailto ending in .md), or relative links that escape the skill root and resolve outside the shared skills directory.

Markdown/TOML files larger than 512 KB are flagged as too large for static audit. Cross-skill markdown references that stay within the shared skills root (e.g. ../other-skill/SKILL.md) are permitted, even if the target is not currently installed.

Caution

To allow script files inside skills, set skills.allow_scripts = true in ~/.revka/config.toml (or REVKA_SKILLS_ALLOW_SCRIPTS=1). This relaxes only the script-file block; symlinks, high-risk patterns, shell chaining, and unsafe links remain blocked.

Skills environment variables

These variables shadow the equivalent config.toml keys under [skills] without editing the file. Booleans accept 1/0/true/false/yes/no/on/off.

Variable	Config key	Meaning
REVKA_OPEN_SKILLS_ENABLED	skills.open_skills_enabled	Enable the open-skills community library
REVKA_OPEN_SKILLS_DIR	skills.open_skills_dir	Override the open-skills directory path
REVKA_SKILLS_ALLOW_SCRIPTS	skills.allow_scripts	Opt in to script files inside skills
REVKA_SKILLS_PROMPT_MODE	skills.prompt_injection_mode	Prompt injection mode: full or compact

Open Skills is an optional library synced from the besoeasy/open-skills GitHub repository on a 7-day interval. Synced skills are audited before loading exactly like installed skills, so scripts in them are blocked unless allow_scripts is set. The equivalent config block:

[skills]
open_skills_enabled = true
open_skills_dir = "~/.revka/open-skills"   # optional override
allow_scripts = false
prompt_injection_mode = "full"              # full | compact

revka workflows

Workflows are declarative YAML pipelines executed by the Operator MCP backend and stored in Kumiho. The CLI’s job here is narrow: list the workflow templates bundled with the binary, and seed them into your workspace.

Subcommand	Purpose
revka workflows list	List the built-in workflows bundled with this binary
revka workflows sync [--force]	Copy bundled workflow YAMLs into the workspace

revka workflows list
revka workflows sync
revka workflows sync --force

sync copies the bundled YAML templates into <workspace>/operator_mcp/workflow/builtins/. Without --force it is non-destructive — existing files are left untouched. Pass --force to overwrite. This is the directory the operator scans as its lowest-priority workflow source, so it is the right place to refresh shipped defaults after a Revka upgrade.

Flag	Meaning
--force	Overwrite workflow files that already exist on disk

Note

builtins/ is the lowest priority in workflow discovery; project .revka/workflows/ and user ~/.revka/workflows/ override it, with a Kumiho space as the final fallback. To author and run workflows, use the dashboard editor and the /api/workflows gateway endpoints. See Built-in workflows & orchestration patterns and the Workflows & Architect API.

revka sop

Standard Operating Procedures are deterministic, event-driven procedures defined as SOP.toml (metadata + triggers) and optional SOP.md (steps) files on disk, run by the Rust SopEngine. The CLI is read-and-validate only.

Subcommand	Purpose
revka sop list	List all loaded SOPs with their triggers and execution mode
revka sop validate [<name>]	Validate all SOPs, or one by name
revka sop show <name>	Show the detailed view of a single SOP

revka sop list
revka sop validate                 # validate every SOP
revka sop validate deploy-prod     # validate one SOP
revka sop show deploy-prod

revka sop list prints each SOP with its version, priority, description, mode, step count, triggers, and cooldown:

SOPs (3):
  deploy-prod v1.0.0 [high] — Deploy service to production
    Mode: supervised  Steps: 4  Triggers: webhook:/sop/deploy, manual
    Cooldown: 300s

revka sop validate exits non-zero when any SOP produces a warning, which makes it usable as a CI gate for procedure definitions.

Note

There is no revka sop run command. SOP runs are initiated through the sop_execute agent tool, or by a configured trigger — MQTT, webhook, cron, or peripheral signal. SOP agent tools are registered when [sop] sops_dir is set in config.toml; when omitted, the CLI defaults to <workspace>/sops but the agent tools remain inactive. For the full SOP.toml/SOP.md syntax, trigger types, and execution modes, see SOP reference.

Enabling SOPs

[sop]
sops_dir = "sops"                 # set this to activate SOP agent tools; defaults to <workspace>/sops
default_execution_mode = "supervised"

A minimal SOP on disk looks like:

~/.revka/workspace/sops/
  deploy-prod/
    SOP.toml    # metadata + triggers (required)
    SOP.md      # numbered procedure steps (optional)

SOP.toml

[sop]
name = "deploy-prod"
description = "Deploy service to production"
version = "1.0.0"
priority = "high"                 # low | normal | high | critical
execution_mode = "supervised"     # auto | supervised | step_by_step | priority_based | deterministic
cooldown_secs = 300
max_concurrent = 1

[[triggers]]
type = "webhook"
path = "/sop/deploy"

[[triggers]]
type = "manual"

Related pages

Skills system The skill model, SKILL.md vs SKILL.toml, tool kinds, and runtime injection.

Built-in workflows & patterns Shipped workflow templates and orchestration patterns.

SOP reference Full SOP.toml and SOP.md syntax, triggers, and execution modes.

Agents, skills & teams API Manage skills over HTTP with the gateway /api/skills endpoints.

Scheduling & SOP tools The sop_execute, sop_status, sop_approve, and sop_advance agent tools.

CLI overview & environment Global flags, config-dir resolution, and the full environment-variable reference.