- R-CLI
- Skills and Discovery
R-CLI
Skills and Discovery
Load reusable workflows from your repo, your personal library, or skills.sh, and let the agent find new ones on demand.
Skills are reusable instructions for specific workflows — a review checklist, a deploy runbook, a house style guide. They are not loaded automatically; you choose which ones a session uses.
Open the skill picker
/skills
The skills picker has Repo, Personal, and skills.sh tabs.
The picker has three tabs. Use ← and → to switch tabs when the search box is empty, or type to search across all fields.
| Tab | Source | Scope |
|---|---|---|
Repo | <cwd>/.agents/skills/<name>/SKILL.md | Shared with everyone working in the project |
Personal | ~/.agents/skills/<name>/SKILL.md | Yours, available in every project |
skills.sh | Public skill directory | Installed into the repo or your personal library on demand |
Repo skills are discovered by walking up from your working directory to the repository root, so a .agents/skills/ folder in any ancestor directory is picked up too.
If a repo skill and a personal skill share a name, the repo one wins in the auto-loaded catalog. Selecting the personal entry in /skills replaces it for that session.
Invoke a loaded skill
Once a skill is loaded, reference it with `--- title: “Skills and Discovery” description: “Load reusable workflows from your repo, your personal library, or skills.sh, and let the agent find new ones on demand.”
Skills are reusable instructions for specific workflows — a review checklist, a deploy runbook, a house style guide. They are not loaded automatically; you choose which ones a session uses.
Open the skill picker
PROTECTED_BLOCK_0
The skills picker has Repo, Personal, and skills.sh tabs.
The picker has three tabs. Use PROTECTED_BLOCK_10 and PROTECTED_BLOCK_11 to switch tabs when the search box is empty, or type to search across all fields.
| Tab | Source | Scope |
|---|---|---|
| PROTECTED_BLOCK_12 | PROTECTED_BLOCK_13 | Shared with everyone working in the project |
| PROTECTED_BLOCK_14 | PROTECTED_BLOCK_15 | Yours, available in every project |
| PROTECTED_BLOCK_16 | Public skill directory | Installed into the repo or your personal library on demand |
Repo skills are discovered by walking up from your working directory to the repository root, so a PROTECTED_BLOCK_17 folder in any ancestor directory is picked up too.
If a repo skill and a personal skill share a name, the repo one wins in the auto-loaded catalog. Selecting the personal entry in PROTECTED_BLOCK_18 replaces it for that session.
Invoke a loaded skill
Once a skill is loaded, reference it with followed by its name:
$code-review check this diff
Or mention it in a normal sentence:
Use $deploy-runbook to ship this to staging.
Skills are not slash commands. Typing /code-review will report an unknown command and point you at $code-review instead.
Skill actions
Selecting a skill in the picker opens an action menu rather than acting immediately:
| Action | Available when |
|---|---|
Load Skill | The skill is installed but not active in this session |
Unload Skill | The skill is currently active |
Remove Skill | The skill is installed in your repo or personal library |
Download | The skill comes from skills.sh and is not installed yet |
Downloading from skills.sh asks where to put it:
| Target | Location |
|---|---|
Project | <cwd>/.agents/skills/ — committed with your repo |
Personal | ~/.agents/skills/ — available everywhere, not shared |
The skills.sh tab lists from a local cache. It refreshes in the background when stale, so opening the picker never blocks on the network. If skills.sh is unreachable, the tab shows an error and the other tabs still work.
Removing a skill only ever deletes a directory directly under a skills root. Anything else is refused, so a malformed entry cannot delete unrelated files.
Writing a skill
A skill is a folder with a SKILL.md inside:
.agents/skills/code-review/SKILL.md
---
name: code-review
description: Review a diff for correctness, tests, and style.
---
When reviewing a change:
1. Read the full diff before commenting.
2. Check that new behavior has tests.
3. Flag anything that changes a public API without a docs update.
Put project conventions in .agents/skills/ so the whole team gets them, and personal habits in ~/.agents/skills/.
Discovery tools
R-CLI can also find skills and MCP servers for you, instead of you picking them up front.
/discover
This toggles two agent tools for the current session:
| Tool | What it does |
|---|---|
find_skill | Searches your installed skills first, then skills.sh |
find_mcp | Searches the curated MCP server catalog |
Discovery is off by default and is session-only — it resets when you restart. Turning it on lets the agent propose installing third-party code. Every install still requires your explicit confirmation.
When find_skill finds a good local match, it activates it silently. When the best match is remote, it asks first:
Download and use "changelog-writer" from skills.sh?
Source: github.com/example/skills, 1,240 installs.
This runs "npx skills add" to install third-party code into this repo.
› Download
Cancel
find_mcp behaves the same way, and tells you up front if the server needs credentials:
Add and connect the "Monday" MCP server?
Requires env vars: MONDAY_API_KEY (set them in your MCP config for it to connect).
› Add
Cancel
Servers that authenticate in the browser rather than through environment variables — Linear, for example — omit the second line.
Servers marked unavailable in the catalog are never suggested. Asking for one by name explains why:
"Example Server" is unavailable: the upstream service was retired.
Sub-agents cannot install
Sub-agents can call find_skill and find_mcp, but can never install anything — installing needs your confirmation, and only the main agent can prompt you. A sub-agent reports the match back instead:
Found "changelog-writer" on skills.sh, but downloading a third-party skill must be
confirmed by the user and a sub-agent cannot prompt. Ask the main agent to run
find_skill for this task.
This keeps every third-party install behind a prompt you actually see.
Related
- MCP servers and hooks — configuring MCP servers directly
- Permissions — gating what discovered tools may do
- Command reference —
/skills,/discover, and config paths