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

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

The parseAddOptions function in src/add.ts handles the raw CLI arguments:

// 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:

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

The installer writes skill files to ~/.cursor/skills, as defined in src/agents.ts.

Multiple agents

List several agents to install to all of them:

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:

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

In src/add.ts lines 39-44, the code detects this token and expands it to all keys from the agents record:

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 lines 44-51:

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

npx skills list --agent cursor

In src/list.ts lines 56-78, this filters output to show only the Cursor agent's installed skills.

Remove skills from specific agents

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

The 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 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, validates against 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 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 and 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.

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