# How to Target Specific Agents with the `--agent` Flag During Skill Installation

> Install skills to specific agents with the --agent flag. Target runtimes like cursor or claude-code or use * for all agents. Learn how to manage your skill installations effectively.

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

---

**Use `npx skills add <package> --agent <agent-name>` to install skills only to specific agent runtimes like `cursor` or `claude-code`, or use `--agent '*'` to target all supported agents.**

The `--agent` flag in the [vercel-labs/skills](https://github.com/vercel-labs/skills) CLI gives you precise control over which AI agent environments receive your installed skills. Whether you're working with Cursor, Claude Code, or other supported agents, this flag lets you avoid cluttering agents with irrelevant tools.

## How the `--agent` Flag Works

The CLI defines the `--agent` flag in [`src/cli.ts`](https://github.com/vercel-labs/skills/blob/main/src/cli.ts) as `-a, --agent <agents>` followed by one or more agent identifiers. When you run `skills add`, the flag value flows through parsing, validation, and finally to the installer that writes files to each agent's skill directory.

### Flag parsing in [`src/add.ts`](https://github.com/vercel-labs/skills/blob/main/src/add.ts)

The `parseAddOptions` function in [`src/add.ts`](https://github.com/vercel-labs/skills/blob/main/src/add.ts) handles the raw CLI arguments:

```typescript
// From src/add.ts lines 78-89
if (args[i] === '-a' || args[i] === '--agent') {
  i++;
  while (i < args.length && !args[i].startsWith('-')) {
    options.agent.push(args[i]);
    i++;
  }
}

```

This loop captures every argument after `--agent` until it hits another flag, letting you specify multiple agents in one command.

## Installing Skills to Specific Agents

### Single agent installation

Target one agent by passing its identifier:

```bash
npx skills add vercel-labs/agent-skills --agent cursor

```

The installer writes skill files to `~/.cursor/skills`, as defined in [`src/agents.ts`](https://github.com/vercel-labs/skills/blob/main/src/agents.ts).

### Multiple agents

List several agents to install to all of them:

```bash
npx skills add vercel-labs/agent-skills --agent cursor claude-code

```

The `options.agent` array becomes `['cursor', 'claude-code']`, and the installer processes both directories.

### All agents with wildcard

Use `'*'` as a shorthand for every supported agent:

```bash
npx skills add vercel-labs/agent-skills --agent '*'

```

In [`src/add.ts`](https://github.com/vercel-labs/skills/blob/main/src/add.ts) lines 39-44, the code detects this token and expands it to all keys from the `agents` record:

```typescript
if (options.agent.includes('*')) {
  targetAgents = Object.keys(agents);
}

```

## Agent Validation and Error Handling

When you specify concrete agent names, `runAdd` validates them against `validAgents` in [`src/add.ts`](https://github.com/vercel-labs/skills/blob/main/src/add.ts) lines 44-51:

```typescript
const validAgents = Object.keys(agents);
const invalidAgents = options.agent.filter(a => !validAgents.includes(a));
if (invalidAgents.length > 0) {
  console.error(`Invalid agents: ${invalidAgents.join(', ')}`);
  console.error(`Valid agents are: ${validAgents.join(', ')}`);
  process.exit(1);
}

```

This prevents typos like `--agent curso` from failing silently.

## When You Omit the `--agent` Flag

The CLI handles missing `--agent` through automatic detection in [`src/add.ts`](https://github.com/vercel-labs/skills/blob/main/src/add.ts) lines 54-94:

### No agents detected

If `detectInstalledAgents` returns nothing, the behavior depends on `--yes`:

- With `--yes`: installs to **all agents**
- Without `--yes`: shows an **interactive prompt** to select agents

### Single agent detected

Automatically uses that agent plus **universal agents** (like `cursor`) via `ensureUniversalAgents`.

## Using `--agent` with Other Commands

The same flag works consistently across the CLI:

### List agent-specific skills

```bash
npx skills list --agent cursor

```

In [`src/list.ts`](https://github.com/vercel-labs/skills/blob/main/src/list.ts) lines 56-78, this filters output to show only the Cursor agent's installed skills.

### Remove skills from specific agents

```bash
npx skills rm my-skill --agent claude-code

```

The [`src/remove.ts`](https://github.com/vercel-labs/skills/blob/main/src/remove.ts) implementation in lines 70-115 locates and deletes the skill only from the specified agent's directory.

## Supported Agent Identifiers

The [`src/agents.ts`](https://github.com/vercel-labs/skills/blob/main/src/agents.ts) file defines all supported agents and their skill directories:

| Agent ID | Skill Directory |
|----------|-----------------|
| `cursor` | `~/.cursor/skills` |
| `claude-code` | `~/.claude-code/skills` |
| `amp` | `~/.amp/skills` |

Pass any of these IDs to `--agent` to target that specific runtime.

## Summary

- The `--agent` flag controls which AI agent environments receive installed skills
- Pass single or multiple agent IDs, or use `'*'` for all agents
- The flag parses in [`src/add.ts`](https://github.com/vercel-labs/skills/blob/main/src/add.ts), validates against [`src/agents.ts`](https://github.com/vercel-labs/skills/blob/main/src/agents.ts), and resolves to concrete directories per agent
- Omitting `--agent` triggers automatic detection with interactive or `--yes` fallback
- The same flag works with `skills list` and `skills rm` for consistent agent targeting

## Frequently Asked Questions

### What happens if I specify an invalid agent name?

The CLI validates your input against known agents in [`src/agents.ts`](https://github.com/vercel-labs/skills/blob/main/src/agents.ts) and exits with an error listing valid options. For example, `--agent vscode` would fail with "Invalid agents: vscode" and show the correct IDs like `cursor` and `claude-code`.

### Can I use `--agent` with the `--all` flag?

Yes. The `--all` flag internally sets `options.agent = ['*']` along with `options.skill = ['*']` and `options.yes = true`. This installs all available skills to all agents without prompting.

### Does `--agent` work the same way for `skills list` and `skills rm`?

Yes. Both [`src/list.ts`](https://github.com/vercel-labs/skills/blob/main/src/list.ts) and [`src/remove.ts`](https://github.com/vercel-labs/skills/blob/main/src/remove.ts) import the same agent parsing and validation logic. The flag filters which agents' skill directories are read for listing or targeted for removal, maintaining consistent behavior across all CLI commands.

### What if the agent I target isn't installed on my system?

The CLI does not check whether the agent software itself is installed. It only validates that the agent ID is known and writes to the corresponding skill directory (e.g., `~/.cursor/skills`). If the agent isn't actually present, the skills will sit unused until that agent is installed.