Skills & plugins
Guides

Skills & plugins

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#

LocationScope
~/.rayu/skills/<name>/SKILL.mdGlobal, all projects
~/.agents/skills/Global, shared with other agents
./.rayu/skills/<name>/SKILL.mdThis project
./.agents/skills/This project, shared
./.claude/skills/Compatibility with Claude Code
~/.claude/plugins, ~/.rayu/pluginsSkills shipped inside installed plugins
~/.rayu/commands/*.mdLegacy 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:

markdown
---
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.

FieldRequiredMeaning
nameyesThe command name; appears as /name
descriptionyesWhen to use it; the model matches on this
allowed-toolsnoComma-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.
  • /skills lists 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:

SkillWhat it does
optimizationDefine metrics, measure, attribute bottlenecks, prioritize macro-optimizations.
todo-planning-skillBuild thorough todo lists for long tasks, including verification steps.
firefox-browserDrive the user's Firefox with their logins intact.

Others are installed on demand from the official catalogs:

bash
npx skills add anthropics/skills --skill frontend-design --yes
npx skills add nvidia/skills --skill cuopt-developer --yes

The 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 turnIt applies when the task comes up
It is short and stableIt 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 →