Managing skills with the CLI

Ratel Local serves skills through the same catalog as tools. The agent finds them with search_capabilities and loads a winner with get_skill_content.

Tools, MCP & Skills owns the concept and retrieval model. This page covers the ratel-mcp skill commands that move folders and edit host settings.

Ratel Local loads <dir>/<name>/SKILL.md from its configured skill directories. Set them with skills.dirs; otherwise it uses ~/.ratel/skills.

Frontmatter name and description are required. tags, triggers, and stacks are optional. Author-defined triggers join the indexed tags.

Every CLI move is recorded in ~/.ratel/skill-manifest.json, so it can be reversed.

skill activate

ratel-mcp skill activate [--dry-run] [--yes]

Moves native skill folders from ~/.claude/skills and ~/.codex/skills into ~/.ratel/skills. Each move is recorded in the manifest.

Ratel Local then serves those skills on demand instead of having the agent load all of them in every session.

Claude Code is scanned first. A skill id found in both agents is taken from Claude Code and skipped for Codex.

ratel-mcp skill activate --dry-run

would activate deploy-runbook
would activate debugging-checklist

Without --dry-run, the command confirms before moving. With nothing to do, it prints no skills to activate (nothing new in ~/.claude/skills).

A name already in the managed folder is skipped, never overwritten. The manifest is written atomically after each move.

Activation always moves skills to ~/.ratel/skills. Keep that directory in skills.dirs if you replace the default with custom directories.

Run it after installing Ratel Local. Run it again whenever you add native skills.

skill list

ratel-mcp skill list

Prints the manifest: one line per managed skill with where it came from.

Ratel manages 2 skill(s):
  deploy-runbook  (from /Users/you/.claude/skills/deploy-runbook)
  debugging-checklist  (from /Users/you/.claude/skills/debugging-checklist)

With an empty manifest it prints Ratel manages no skills (run `ratel-mcp skill activate`). Use it before deactivating skills or whenever you want to check what Ratel Local serves.

skill install-hook / skill uninstall-hook

ratel-mcp skill install-hook [--scope user|project] [--yes]
ratel-mcp skill uninstall-hook [--scope user|project]

search_capabilities is the pull path: the agent finds a skill when it searches.

install-hook adds a push path for Claude Code. Its UserPromptSubmit hook runs skill preload-hook on every prompt and injects a pointer when one skill clearly wins.

ratel-mcp skill install-hook --scope user

It appends a hooks.UserPromptSubmit entry to the settings file:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          { "type": "command", "command": "ratel-mcp skill preload-hook", "timeout": 10 }
        ]
      }
    ]
  }
}

The binary path resolves through $RATEL_MCP_BIN, then PATH, then an interactive prompt. Installation is idempotent and backs up the settings file before editing.

Invalid settings JSON is refused rather than overwritten. uninstall-hook removes only entries carrying the skill preload-hook marker.

Run install-hook once, right after your first activate.

skill preload-hook

ratel-mcp skill preload-hook [--limit N] [--min-score X]

Claude Code runs this hook entrypoint on every prompt. You rarely invoke it yourself.

It reads prompt, cwd, and session_id from stdin, then ranks skills against the prompt. It fires only for a clear lexical lead or a near-tie where exactly one skill matches the detected project stack.

Otherwise it stays silent.

On a hit it writes the standard hook output to stdout:

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Ratel: project-relevant skill(s) may apply to this task. Before writing code, load the relevant one(s) with the `get_skill_content` tool and follow them:\n- deploy-runbook — How to deploy: env vars, preview vs production, rollbacks.  →  get_skill_content(\"deploy-runbook\")"
  }
}

Each skill is nudged at most once per session. Dedupe state lives under ~/.ratel/skill-preload/.

Project-stack detection is cached at ~/.ratel/skill-signal-cache.json. Dependency manifest changes invalidate it.

The hook fails open. Errors inject nothing and never block the prompt.

skill suggest

ratel-mcp skill suggest --prompt "<text>" [--cwd <dir>] [--dir <path>]... [--limit N] [--min-score X] [--format json]

Runs the preload hook's ranking as a standalone debugging tool.

Ranking uses BM25 over each skill's name, description, and tags. The project stack from --cwd multiplies a matching skill's score by 1.6× and can reorder the results. The preload hook applies a separate clear-winner check before it injects a pointer.

Without --dir, suggest reads skills.dirs only from ~/.ratel/config.json, then falls back to ~/.ratel/skills. It does not merge project or local config. Pass each project-specific directory explicitly with repeatable --dir to compare the same corpus that a project gateway serves.

ratel-mcp skill suggest --prompt "build a login form" --cwd . --limit 3

auth-flows  (score 2.31)  How to add authentication: sessions, OAuth, form validation.

No hits prints no matching skills. With --format json, each hit includes skillId, description, score, and stackMatch. A true stackMatch means the ordering boost applied.

skill deactivate

ratel-mcp skill deactivate [--dry-run] [--yes]

Restores each manifest-recorded skill to its source agent folder, then clears its manifest entry. Skills created directly in ~/.ratel/skills stay put.

Occupied destinations and missing sources are skipped, never overwritten. --dry-run and --yes behave as in activate.

Run it when you want an agent to own its skills natively again, or to hand a skill back before editing it in place.

A typical loop

1. ratel-mcp skill activate — move native skills behind the pull path: search_capabilities → skills → get_skill_content.
2. ratel-mcp skill install-hook — add the push path, so terse prompts still get a pointer to the single best skill.
3. ratel-mcp skill suggest --prompt "..." — dry-run ranking, then tune the skill's description, tags, or triggers.
4. ratel-mcp skill list / ratel-mcp skill deactivate — inspect what's managed, and reverse any move.

Ratel Local also ships a browser UI with the same manage/stop-managing actions, bulk operations, and a new-skill form. See Browser UI.

Next steps