Skills

A skill is a directory under <profile>/skills/<slug>/ containing one of:

• SKILL.toml — preferred. Structured metadata + optional tool definitions parsed and exposed to the LLM as callable functions.
• SKILL.md — fallback. The whole file content is included in the agent’s prompt; no section parsing.

If both exist, SKILL.toml wins.

SKILL.toml schema

name = "deploy-checker"
description = "Validates deployment readiness before release."
 
# Optional metadata
version = "0.1.0"
author = "Your Name"
tags = ["devops", "release"]
 
# Optional tools — exposed to the LLM as callable functions
[[tools]]
name = "run_checks"
description = "Run the pre-deploy validator script"
kind = "shell"
command = "./scripts/pre-deploy.sh"
 
[[tools]]
name = "check_url"
description = "Check that a URL returns 200"
kind = "http"
method = "GET"
url = "https://my-app.example.com/health"
 
# Optional prompt content — prepended to the system prompt when this skill is active
[[prompts]]
content = """
- Always run pre-deploy checks before approving a release
- Report any failing checks with specific remediation steps
- If checks pass, summarize the deployment plan in 3 bullets
"""
 
# Optional install recipes — fetched by `rantaiclaw skills install-deps <name>`
[[install_recipes]]
kind = "brew"
package = "jq"
 
[[install_recipes]]
kind = "npm"
package = "wrangler"

[[match]] auto-load blocks are not part of the current SkillManifest — the loader ignores them. Skill activation is driven by inclusion in the agent’s skill set, not by message-pattern matching at parse time.

Tool kinds (executable)

When a skill defines [[tools]], only two kinds are executable via SkillToolAdapter (src/tools/skill_tool.rs):

Other kinds (template, builtin, etc.) return "Unsupported skill tool kind". Constraints:

• 120-second timeout
• 1MB output cap
• Skill tools are exposed to the LLM with the prefix skill_<skill>_<tool> (underscores)

Install-recipe kinds

[[install_recipes]] entries declare external dependencies the skill needs. They run when the user invokes rantaiclaw skills install-deps <name>:

The runtime never auto-installs deps; the user has to opt in by running install-deps.

SKILL.md (markdown) — what actually happens

If you only ship a SKILL.md, the loader at src/skills/mod.rs::load_skill_md:

• Uses the directory name as the skill’s name.
• Extracts the first non-heading non-blank line as the skill’s description.
• Stuffs the entire file content into the skill’s first prompt block.

It does not parse ## Description, ## Tools, ## Instructions, ## Match, ## Metadata, or ## Permissions sections. Those headers are prompt convention for the LLM, not loader-enforced schema. Specifically:

• A ## Tools block with kind: builtin items is not parsed as runtime tool definitions. The LLM reads the prose; the runtime does not register callable tools from it.
• For real LLM-callable skill tools, write SKILL.toml instead.

A typical SKILL.md is fine for narrative skills (a persona overlay, a domain checklist, instructions the LLM follows in plain language) but cannot expose structured tools.

Skill discovery order

The loader searches in priority order (src/skills/mod.rs):

1. open-skills repo at ~/open-skills/ (or RANTAICLAW_OPEN_SKILLS_DIR), only if [skills].open_skills_enabled = true
2. Profile-level at <workspace_dir>/../skills/
3. Workspace-level at <workspace_dir>/skills/

On name collision, profile-level wins. Bundled built-in skills (the starter pack) are not searched at runtime — they’re materialized into the active profile during setup.

The paths ~/.local/share/rantaiclaw/skills/ and /usr/local/share/rantaiclaw/skills/ are not searched.

Prompt-injection modes

[skills]
mode = "Full"      # default — embeds full skill prompt + tools inline in system prompt
# or
mode = "Compact"   # only name + description + path; agent reads file on demand

Compact mode saves tokens for agents with many skills installed.

Auto-sources

[skills]
open_skills_enabled = true
open_skills_url = "https://github.com/besoeasy/open-skills"
# Auto-pulls every 7 days into ~/open-skills/
 
skillforge_enabled = false
skillforge_min_score = 0.7
skillforge_scan_interval_hours = 24
# Auto-discovers skills from GitHub + ClawHub, scores them, proposes integrations

Installing skills

rantaiclaw skills list
rantaiclaw skills show <name>
rantaiclaw skills install <git-url>
rantaiclaw skills install <local-path>
rantaiclaw skills remove <name>
rantaiclaw skills update <slug>        # re-pull one installed ClawHub skill at its latest version
rantaiclaw skills update --all         # re-pull every installed ClawHub skill
rantaiclaw skills inspect <slug>       # ClawHub metadata + security scan, before installing

install clones a git repo or copies a local directory into <profile>/skills/<slug>/.

update re-pulls ClawHub-installed skills at their latest version (local-path / git skills are skipped — git pull or re-install those manually). inspect hits ClawHub’s public API to show metadata + a security scan for a slug without installing it. Both subcommands are defined by SkillCommands in src/main.rs.

Skill tools available to the agent

Beyond the human-facing CLI, the agent can manage skills mid-conversation through built-in tools. They are ordinary tools subject to the normal approval/autonomy gates:

Agent-authored skills (author_skill)

Added in v0.6.77.

Ask the agent “make me a skill that does X” and the author_skill tool (src/tools/author_skill.rs) scaffolds a brand-new skill for you. It writes a loader-valid SKILL.md into the active profile’s skills/<slug>/ directory, where the loader picks it up on the next turn (restart channel runtimes to pick it up immediately).

• Only name + description are required. If you omit instructions, the tool fills in sensible defaults, so even a minimal call produces a complete, valid skill. Optional tools (built-in tool names the skill relies on), tags, and overwrite are also accepted.
• The slug is sanitized from the name to a filesystem-safe [a-z0-9-] form — path traversal (.., /) is impossible by construction.
• It never overwrites an existing skill unless you pass overwrite: true.
• It is approval-gated — in Supervised mode you are prompted before the file is written, mirroring the skills_install flow.

Skills are data, not compiled code: an authored skill’s “tools” are references to the agent’s existing built-in tools (shell, web_search, file_read, …), exactly what the SKILL.md loader expects. For structured, LLM-callable skill tools, hand-write a SKILL.toml instead.

Publishing to ClawHub

ClawHub is RantAIClaw’s package registry for community skills. Publishing today is HTTP-driven through clawhub.ai; there is no rantaiclaw skills publish CLI subcommand yet.