26. Skills & plugins#
A skill is a reusable procedure Rayu loads only when it is needed. Instead of
putting a long workflow into RAYU.md and paying for it on every turn, you write
it once as a skill and invoke it with /skill-name.
Where skills live#
| Location | Scope |
|---|---|
~/ | Global, all projects |
~/.agents/skills/ | Global, shared with other agents |
. | This project |
./.agents/skills/ | This project, shared |
./.claude/skills/ | Compatibility with Claude Code |
~/.claude/plugins, ~/.rayu/plugins | Skills shipped inside installed plugins |
~/.rayu/commands/*.md | Legacy single-file commands, read-only |
Later sources win. Project skills are resolved freshly from the session's working directory, so editing a skill takes effect without restarting the daemon, and two sessions in different repositories never see each other's project skills.
Anatomy of a skill#
A skill is a directory with a SKILL.md:
---
name: release-check
description: Verify a release before tagging. Use when the user asks to cut a release.
allowed-tools: bash, read, agentgrep
---
# Release check
1. `cargo build --locked --release` must succeed.
2. `cargo test --locked -p rayucode-message-types` must pass.
3. `rayu version` must print the version being released.
4. Report pass/fail per step; do not fix anything.Only the frontmatter is read at startup. The body loads when the skill runs, which is the point: fifty skills cost almost nothing until one is used.
| Field | Required | Meaning |
|---|---|---|
name | yes | The command name; appears as /name |
description | yes | When to use it; the model matches on this |
allowed-tools | no | Comma-separated or YAML list restricting the tools this skill may use |
Invoking skills#
- Type
/and the skill appears in the command menu alongside built-in commands. - Ask in plain language and the model invokes it when the description matches.
/skillslists what is loaded, its description and path, plus the catalog Rayu endorses but you have not installed yet.
The skill_manage tool is the programmatic path: it can list, reload, and read
skills, and reload_all refreshes the registry after you add files. That matters
in a long session, because the tool list and skill list in the system prompt were
captured at session start.
Endorsed skills#
/skills also shows a curated list of skills Rayu recommends but does not bundle.
Two are bundled in the repository and appear as installed when you run from a
RayuCode checkout:
| Skill | What it does |
|---|---|
optimization | Define metrics, measure, attribute bottlenecks, prioritize macro-optimizations. |
todo-planning-skill | Build thorough todo lists for long tasks, including verification steps. |
firefox-browser | Drive the user's Firefox with their logins intact. |
Others are installed on demand from the official catalogs:
npx skills add anthropics/skills --skill frontend-design --yes
npx skills add nvidia/skills --skill cuopt-developer --yesThe NVIDIA CUDA-X entries mirror https://github.com/NVIDIA/skills; the
Anthropic entry comes from https://github.com/anthropics/skills. After
installing, run skill_manage reload_all (or restart the session) so the registry
picks them up.
Plugins#
A plugin packages skills together with commands, agents and MCP servers, so a team
can distribute a workflow as one unit. Plugins are installed as directories under
~/.rayu/plugins or ~/.claude/plugins; the loader scans both roots and registers
the skills/<name>/SKILL.md entries it finds.
There is no rayu plugin subcommand in v3. Install a plugin by placing its
directory in the plugin root, or by pointing your existing Claude Code plugin
install at it, then reload the registry.
Choosing between a skill and an instruction file#
Use an instruction file (AGENTS.md, RAYU.md) | Use a skill |
|---|---|
| It must apply to every turn | It applies when the task comes up |
| It is short and stable | It is a multi-step procedure |
It is a rule ("never use unwrap") | It is a workflow ("cut a release like this") |
Long instruction files get less attention per line. Moving procedures into skills is usually the single biggest quality improvement for a busy repository.
Next#
Next: MCP servers →