How to Selectively Remove Skills from Specific Agents Using the `skills remove` Command

Use the -a or --agent flag with skills remove to uninstall a skill from one or more specific agents without affecting other agents in your environment.

The skills CLI provides granular control over skill management through its remove command. When you need to remove skills from specific agents, the tool validates agent identifiers against known agents and performs targeted cleanup while preserving the skill for other agents that still need it.

Understanding Agent-Targeted Removal

The remove command in src/remove.ts implements selective removal through a multi-stage process. When you specify agents with -a, the CLI builds a targetAgents array containing only your requested agents rather than defaulting to all agents.

At lines 14-22 in src/remove.ts, the command determines the target scope:

// If --agent is provided, use only those agents; otherwise target all agents
const targetAgents = options.agents?.length > 0 
  ? options.agents 
  : getAllAgents();

This design ensures that when you remove a skill from specific agents, the CLI won't inadvertently clean up symlinks for agents you didn't specify.

Validating Agent Identifiers

Before performing any removal operations, the CLI validates your agent identifiers against the canonical list defined in src/agents.ts. This validation occurs at lines 70-78 in src/remove.ts:

// Validate each specified agent exists in our known agents
for (const agentId of options.agents) {
  if (!isKnownAgent(agentId)) {
    throw new Error(`Unknown agent: ${agentId}. Valid agents are: ${listKnownAgents().join(', ')}`);
  }
}

This validation prevents typos from causing silent failures and provides immediate feedback with the complete list of valid agent identifiers.

Per-Agent Cleanup Process

For each selected skill, the command iterates over targetAgents and computes the install path using getInstallPath from src/installer.ts. The cleanup logic at lines 56-70 removes agent-specific directories or symlinks:

for (const agent of targetAgents) {
  const installPath = getInstallPath(skillName, agent);
  
  // Remove the agent-specific symlink or directory
  if (fs.existsSync(installPath)) {
    fs.unlinkSync(installPath);
    console.log(`Removed ${skillName} from ${agent}`);
  }
}

This targeted approach ensures that other agents' installations remain completely untouched.

Canonical Folder Management

After processing all specified agents, the CLI performs a critical safety check at lines 92-105 in src/remove.ts. It determines whether any remaining agents still have the skill installed before removing the canonical skill folder:

// Check if any other agents still use this skill
const remainingAgents = getAllAgents().filter(a => 
  !targetAgents.includes(a) && skillIsInstalled(skillName, a)
);

// Only remove canonical folder if no agents reference it
if (remainingAgents.length === 0) {
  fs.rmSync(getCanonicalPath(skillName), { recursive: true });
}

This prevents the common pitfall of breaking other agents when you only intend to remove a skill from a subset of agents.

Global vs. Local Scope

The --global flag modifies where the CLI looks for skills. When enabled, operations target global skill directories via getCanonicalSkillsDir(true, cwd) and update the lock file through skill-lock.ts:

// Global mode uses system-wide skill directories
const skillsDir = options.global 
  ? getCanonicalSkillsDir(true, cwd) 
  : getCanonicalSkillsDir(false, cwd);

// Update global lock file when in global mode
if (options.global) {
  removeSkillFromLock(skillName);
}

The lock file management ensures global skill installations remain consistent across your system.

Practical Code Examples

Remove a skill from a single agent

skills remove my-skill -a claude-code -y

Remove a skill from multiple agents

skills remove my-skill -a claude-code cursor -y

Interactive removal from a specific agent

skills remove -a cursor

This prompts you to select which skills to uninstall from the cursor agent.

Remove a globally-installed skill from one agent

skills remove my-skill -g -a claude-code -y

Command Reference

Flag	Long Form	Purpose
-a	--agent	One or more agent identifiers (e.g., claude-code, cursor)
-g	--global	Operate on global skill store instead of local project
-y	--yes	Skip confirmation prompt
	--all	Remove all installed skills (ignores -a)

Agent parsing logic is implemented at lines 95-101 in src/remove.ts.

Key Source Files

File	Role in Selective Removal
src/remove.ts	Core remove command implementation, agent validation, target determination, per-agent and canonical cleanup
src/agents.ts	Supported agent definitions and directory layouts for validation and path resolution
src/installer.ts	getInstallPath, getCanonicalPath, and sanitizeName helpers for filesystem location mapping
src/skill-lock.ts	Global lock file management via removeSkillFromLock
src/cli.ts	Command registration and option parsing through parseRemoveOptions

Summary

• Use skills remove <skill> -a <agent> to target specific agents without affecting others
• The CLI validates agent identifiers against src/agents.ts before any removal occurs
• Per-agent cleanup removes only the specified agents' symlinks/directories while preserving the canonical skill folder if other agents still use it
• Combine -a with -g for global skill management scoped to specific agents
• The -y flag enables non-interactive operation for automation scripts

Frequently Asked Questions

What happens if I specify an invalid agent name?

The CLI throws an error with a list of valid agents. At lines 70-78 in src/remove.ts, the remove command checks each agent against isKnownAgent() and provides immediate feedback: Unknown agent: <name>. Valid agents are: claude-code, cursor, ...

Can I remove a skill from all agents except one?

There is no direct exclusion flag. You must explicitly list the agents to target with -a. To achieve "all except one," first list all agents with a helper command, then filter and pass the desired agents to skills remove -a.

Does removing a skill from one agent break other agents using the same skill?

No. The canonical folder removal logic at lines 92-105 in src/remove.ts checks whether any remaining agents still reference the skill. The canonical folder is only deleted when remainingAgents.length === 0, ensuring other agents continue functioning normally.

What is the difference between -a and --all?

The -a / --agent flag specifies which agents to target for removal. The --all flag removes every installed skill regardless of agent, and it ignores any -a values you provide. These flags serve entirely different purposes and should not be confused.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}