Managing skills

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

Stable releases use scoped registrations. They no longer move skills through the deprecated skill activate and skill deactivate commands.

Registration model

Register a skill at user, project, or local scope:

• reference keeps the source folder in place and records its canonical path.
• copy creates a Ratel-owned copy for the selected scope.

Project and local registrations never edit repository-owned skill metadata. The normal scope precedence applies when the same skill id appears more than once.

Discover and import skills

Inspect candidates from supported Claude Code and Codex locations:

ratel-local skill list --discovered
ratel-local skill list --discovered --project /path/to/project

Import interactively, or name candidates directly:

ratel-local skill import --scope user --mode reference
ratel-local skill import deploy-runbook --scope project --mode copy
ratel-local skill import --scope local --mode reference --dry-run

--dry-run previews the registration. --yes skips confirmation. When two hosts expose the same skill id, import keeps the first deterministic candidate and reports later duplicates as skipped.

Inspect registrations

# Effective catalog for the current context
ratel-local skill list

# Every registration, including shadowed or invalid entries
ratel-local skill list --configured

# Select a registered project explicitly
ratel-local skill list --configured --project /path/to/project

Add another scope for an effective skill:

ratel-local skill add-scope deploy-runbook \
  --scope project --mode reference

Remove a registration

Use remove-scope to stop using the selected registration without deleting an owned copy. Use remove when a Ratel-owned copy should also be deleted:

ratel-local skill remove-scope deploy-runbook --scope project
ratel-local skill remove deploy-runbook --scope project

Both commands confirm by default and support --dry-run and --yes.

Legacy migration and recovery

The daemon safely migrates verified legacy skill links to user-scoped references on startup. Ambiguous or externally changed entries are left untouched with diagnostics.

ratel-local doctor
ratel-local doctor --fix

doctor --fix performs the same recoverable migration for safe entries. Review its diagnostics before changing ambiguous paths manually.

Claude Code preload hook

Capability search is the pull path: the agent searches when it needs a playbook. The optional Claude Code UserPromptSubmit hook adds a push path for terse prompts.

ratel-local skill install-hook --scope user
ratel-local skill install-hook --scope project
ratel-local skill uninstall-hook --scope user

The hook invokes ratel-local skill preload-hook, ranks the effective skills for the prompt, and injects a pointer only when one skill clearly wins. It fails open and never blocks a prompt.

The executable resolves through RATEL_LOCAL_BIN, then PATH, then an interactive prompt. Installation is idempotent, revision-checked, and backed up.

Debug ranking

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

Use --format json for structured output, --min-score to drop weak hits, and repeat --dir only when you intentionally want to rank an explicit directory set instead of the effective scoped catalog.

Ranking uses the configured retrieval method. With default BM25 it stays model-free; semantic and hybrid behavior follows the selected retrieval scope.

Apply changes to an agent

Reconnect the affected agent after importing, adding, or removing a skill registration. Its next connection receives a new gateway generation with the updated catalog.

Next steps