Skip to main content

​
Usage

skills remove [skills...] [options]
skills rm [skills...] [options]

​
Description

The remove command uninstalls skills from agents. It removes:
  • The canonical skill directory (.agents/skills/skill-name)
  • Symlinks from agent directories
  • Entries from the skill lock file (for global installs)
If no skill names are provided, an interactive selection menu is shown.

​
Arguments

​
skills
string[]
Optional skill name(s) to remove. Supports multiple skills separated by spaces.Examples:
  • frontend-design
  • skill-creator web-design
If omitted, shows an interactive multi-select menu.

​
Options

​
-g, --global
boolean
Remove from global scope (~/.agents/skills/) instead of project scope (./.agents/skills/).Default: false (removes from project)
​
-a, --agent
string[]
Remove from specific agents only. Accepts multiple agent names or '*' for all agents.Examples:
  • -a claude-code -a cursor
  • --agent '*' (all agents)
By default, removes from all known agents to clean up any ghost symlinks.
​
-s, --skill
string[]
Specify which skills to remove. Accepts multiple skill names or '*' for all skills.Examples:
  • -s frontend-design -s web-design
  • --skill '*' (all skills)
This is useful when combined with --agent to remove specific skills from specific agents.
​
-y, --yes
boolean
Skip confirmation prompts. Automatically confirms removal.Default: false
Use with caution - skills will be removed immediately without confirmation.
​
--all
boolean
Shorthand for --skill '*' --agent '*' -y. Removes all skills from all agents without prompts.Default: false
This will remove ALL installed skills immediately!

​
Examples

# Show interactive selection menu
skills remove

# Select multiple skills using space bar
# Press enter to confirm

​
Interactive Selection

When run without skill names, the CLI shows an interactive multi-select menu:
1

Scan for Skills

The CLI scans for installed skills in:
  • Canonical directory (.agents/skills/ or ~/.agents/skills/)
  • All agent-specific directories
◇  Found 5 unique installed skill(s)
2

Select Skills

Use arrow keys and space bar to select skills:
  • Up/Down: Navigate
  • Space: Toggle selection
  • Enter: Confirm
  • Esc: Cancel
◆  Select skills to remove (space to toggle)
│  ◼ frontend-design
│  ◻ web-design-guidelines
│  ◼ skill-creator
│  ◻ pr-review
└  ◻ commit-message
3

Confirm Removal

Review selected skills and confirm:
Skills to remove:
  • frontend-design
  • skill-creator

◆  Are you sure you want to uninstall 2 skill(s)? … yes

​
Removal Process

The removal process handles:
  1. Agent-specific removals: Removes skill from each specified agent’s directory
  2. Canonical removal: Removes the canonical copy (only if no other agents are using it)
  3. Lock file updates: Updates ~/.agents/.skill-lock.json for global installs
  4. Symlink cleanup: Handles both symlinks and copied files

​
Safety Features

Selective Removal

When removing from specific agents with --agent, the canonical copy is only removed if no other installed agents are using it.

Ghost Cleanup

Automatically cleans up ghost symlinks from agents that may no longer be installed.

​
Output Example

$ skills remove frontend-design web-design

◇  Found 2 unique installed skill(s)

Skills to remove:
  • frontend-design
  • web-design

◆  Are you sure you want to uninstall 2 skill(s)? … yes
◇  Removal process complete
◆  Successfully removed 2 skill(s)

◆  Done!

​
Failed Removals

If any skills fail to remove, details are shown: 
◆  Successfully removed 2 skill(s)
◆  Failed to remove 1 skill(s)
  ✗ my-skill: EACCES: permission denied

​
Understanding Scope

​
Project Scope (Default)

Removes skills from the current project:
  • Canonical directory: ./.agents/skills/
  • Agent directories: ./<agent>/skills/
  • Does NOT affect global skills
skills remove my-skill

​
Global Scope

Removes skills from your home directory:
  • Canonical directory: ~/.agents/skills/
  • Agent directories: ~/<agent>/skills/
  • Updates global lock file: ~/.agents/.skill-lock.json
  • Does NOT affect project skills
skills remove my-skill -g

​
Help

View detailed help for the remove command: 
skills remove --help
Outputs: 
Usage: skills remove [skills...] [options]

Description:
  Remove installed skills from agents. If no skill names are provided,
  an interactive selection menu will be shown.

Arguments:
  skills            Optional skill names to remove (space-separated)

Options:
  -g, --global       Remove from global scope (~/) instead of project scope
  -a, --agent        Remove from specific agents (use '*' for all agents)
  -s, --skill        Specify skills to remove (use '*' for all skills)
  -y, --yes          Skip confirmation prompts
  --all              Shorthand for --skill '*' --agent '*' -y

[examples shown...]

​
Aliases

The following aliases are available:
  • skills rm → skills remove
  • skills r → skills remove

​
Exit Codes

CodeDescription
0All skills removed successfully
1Invalid agent names provided

Build docs developers (and LLMs) love

Get started for freeTalk to us