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

> Learn how to selectively remove skills from specific agents using the skills remove command with the -a or --agent flag. Uninstall skills without affecting other agents.

- Repository: [Vercel Labs/skills](https://github.com/vercel-labs/skills)
- Tags: how-to-guide
- Published: 2026-04-23

---

**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`](https://github.com/vercel-labs/skills/blob/main/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`](https://github.com/vercel-labs/skills/blob/main/src/remove.ts), the command determines the target scope:

```typescript
// 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`](https://github.com/vercel-labs/skills/blob/main/src/agents.ts). This validation occurs at lines 70-78 in [`src/remove.ts`](https://github.com/vercel-labs/skills/blob/main/src/remove.ts):

```typescript
// 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`](https://github.com/vercel-labs/skills/blob/main/src/installer.ts). The cleanup logic at lines 56-70 removes agent-specific directories or symlinks:

```typescript
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`](https://github.com/vercel-labs/skills/blob/main/src/remove.ts). It determines whether any remaining agents still have the skill installed before removing the canonical skill folder:

```typescript
// 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`](https://github.com/vercel-labs/skills/blob/main/skill-lock.ts):

```typescript
// 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

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

```

### Remove a skill from multiple agents

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

```

### Interactive removal from a specific agent

```bash
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

```bash
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`](https://github.com/vercel-labs/skills/blob/main/src/remove.ts).

## Key Source Files

| File | Role in Selective Removal |
|------|---------------------------|
| [`src/remove.ts`](https://github.com/vercel-labs/skills/blob/main/src/remove.ts) | Core `remove` command implementation, agent validation, target determination, per-agent and canonical cleanup |
| [`src/agents.ts`](https://github.com/vercel-labs/skills/blob/main/src/agents.ts) | Supported agent definitions and directory layouts for validation and path resolution |
| [`src/installer.ts`](https://github.com/vercel-labs/skills/blob/main/src/installer.ts) | `getInstallPath`, `getCanonicalPath`, and `sanitizeName` helpers for filesystem location mapping |
| [`src/skill-lock.ts`](https://github.com/vercel-labs/skills/blob/main/src/skill-lock.ts) | Global lock file management via `removeSkillFromLock` |
| [`src/cli.ts`](https://github.com/vercel-labs/skills/blob/main/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`](https://github.com/vercel-labs/skills/blob/main/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`](https://github.com/vercel-labs/skills/blob/main/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`](https://github.com/vercel-labs/skills/blob/main/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.