agent-add

Install MCP, Skills, slash commands, sub-agents and more into any AI tool like Claude Code, Cursor, etc.

npx -y agent-add \
  --mcp '{"playwright":{"command":"npx","args":["-y","@playwright/mcp"]}}' \
  --mcp 'https://github.com/modelcontextprotocol/servers.git#.mcp.json' \
  --skill 'https://github.com/anthropics/skills.git#skills/pdf' \
  --prompt $'# Code Review Rules\n\nAlways review for security issues first.' \
  --command 'https://github.com/wshobson/commands.git#tools/security-scan.md' \
  --sub-agent 'https://github.com/VoltAgent/awesome-claude-code-subagents.git#categories/01-core-development/backend-developer.md'

Releases are built and published via GitHub Actions; see npm provenance and the Socket Security report.

Supported Hosts

Project scope (default)

Install into the current project without --global.

AI Tool	MCP	Prompt	Skill	Command	Sub-agent
Cursor	✅	✅	✅	✅	✅
Claude Code	✅	✅	✅	✅	✅
Trae	✅	✅	✅	❌	❌
Qwen Code	✅	✅	✅	✅	✅
GitHub Copilot	✅	✅	✅	✅	✅
Codex CLI	✅	✅	✅	❌	✅
Windsurf (legacy Cascade)	❌	✅	✅	✅	❌
Gemini CLI	✅	✅	✅	✅	✅
Kimi Code	❌	✅	✅	❌	❌
Augment	✅	✅	✅	✅	✅
Roo Code	✅	✅	✅	✅	❌
Kiro (CLI V3 / IDE 1.0)	✅	✅	✅	❌	✅
Tabnine (IDE Agent / CLI)	✅	✅	❌	✅	❌
Kilo Code	✅	✅	✅	✅	✅
opencode	✅	✅	✅	✅	✅
Mistral Vibe	✅	✅	✅	❌	✅
Zed Agent	❌	✅	✅	❌	❌
Cline	❌	✅	✅	❌	❌
Continue	✅	✅	❌	❌	❌
Aider	❌	✅	❌	❌	❌
goose	❌	✅	✅	❌	❌
Amp CLI	✅	✅	✅	❌	❌

OpenClaw and Claude Desktop are global-only hosts; they have no project installation target.

User scope (`--global`)

Install for the current OS user, independently of the current project.

AI Tool	MCP	Prompt	Skill	Command	Sub-agent
Cursor	✅	❌	✅	❌	✅
Claude Code	✅	✅	✅	✅	✅
Trae	❌	❌	✅	❌	❌
Qwen Code	✅	❌	✅	✅	✅
GitHub Copilot (VS Code)	❌	❌	✅	❌	✅
Codex CLI	✅	✅	✅	❌	✅
Windsurf (legacy Cascade)	❌	❌	❌	✅	❌
Gemini CLI	✅	✅	✅	✅	✅
Kimi Code	✅	❌	✅	❌	❌
Augment / Auggie	✅	✅	✅	✅	✅
Roo Code	❌	✅	✅	✅	❌
Kiro (CLI V3 / IDE 1.0)	✅	✅	✅	❌	✅
Tabnine (IDE Agent / CLI)	✅	❌	❌	✅	❌
Kilo Code	✅	❌	✅	✅	✅
opencode	✅	✅	✅	✅	✅
OpenClaw (global only)	❌	❌	✅	❌	❌
Mistral Vibe	✅	✅	✅	❌	✅
Claude Desktop (global only)	✅	❌	❌	❌	❌
Zed Agent	❌	✅	✅	❌	❌
Cline	✅	✅	✅	❌	❌
Continue	❌	❌	❌	❌	❌
Aider	❌	❌	❌	❌	❌
goose	❌	✅	✅	❌	❌
Amp CLI	✅	✅	✅	❌	❌

✅ / ❌ = installable / unavailable through agent-add in that scope. Claude Desktop requires macOS or Windows.

Why agent-add?

Every AI tool has its own config format — Cursor uses .cursor/mcp.json, Claude Code uses .mcp.json, Codex uses project TOML...

agent-add smooths out all the differences. One command installs to any of the supported AI tools:

npx -y agent-add --host claude-code --mcp 'https://github.com/modelcontextprotocol/servers.git#.mcp.json'
npx -y agent-add --host cursor      --mcp 'https://github.com/modelcontextprotocol/servers.git#.mcp.json'
npx -y agent-add --host codex       --mcp 'https://github.com/modelcontextprotocol/servers.git#.mcp.json'

# Omit --host for an interactive selection menu
npx -y agent-add --mcp 'https://github.com/modelcontextprotocol/servers.git#.mcp.json'

Usage

Install Node.js (v18+), then run directly via npx — no separate install needed.

By default, identical content is left unchanged. Add --overwrite to force rewriting an existing same-name asset, even if its content is identical.

Project or global?

No flag: install into the current project. --global: install for your user, across projects. The two installations are separate.

# Project MCP → .mcp.json
npx -y agent-add --host claude-code \
  --mcp '{"playwright":{"command":"npx","args":["-y","@playwright/mcp"]}}'

# User MCP → ~/.claude.json
npx -y agent-add --global --host claude-code \
  --mcp '{"playwright":{"command":"npx","args":["-y","@playwright/mcp"]}}'

# User prompt → ~/.claude/CLAUDE.md (read ./prompts/personal.md from this directory)
npx -y agent-add --global --host claude-code \
  --prompt ./prompts/personal.md

# Global-only tool: always use --global (macOS / Windows)
npx -y agent-add --global --host claude-desktop \
  --mcp '{"playwright":{"command":"npx","args":["-y","@playwright/mcp"]}}'

Install a pack

Use a pack manifest to install several assets together. --global applies to everything in the command.

# Install a pack into this project
npx -y agent-add --host claude-code --pack ./agent-pack.json

# Install the same pack for your user
npx -y agent-add --global --host claude-code --pack ./agent-pack.json

# Add extra assets alongside a pack — all installed for your user
npx -y agent-add --global --host claude-code \
  --pack ./agent-pack.json \
  --skill ./skills/my-skill \
  --prompt ./prompts/personal.md

Install MCP

# From inline JSON
npx -y agent-add \
  --mcp '{"playwright":{"command":"npx","args":["-y","@playwright/mcp"]}}'

# From a Git repository
npx -y agent-add \
  --mcp 'https://github.com/modelcontextprotocol/servers.git#.mcp.json'

# From an HTTP URL
npx -y agent-add \
  --mcp 'https://raw.githubusercontent.com/modelcontextprotocol/servers/main/.mcp.json'

# Replace an existing MCP
npx -y agent-add --host cursor --overwrite --mcp ./mcps/playwright.json

Install Skill

# From the official Anthropic Skills repository
npx -y agent-add \
  --skill 'https://github.com/anthropics/skills.git#skills/pdf'

npx -y agent-add \
  --skill 'https://github.com/anthropics/skills.git#skills/webapp-testing'

Install Prompt (Rule file / System Prompt)

# Pass inline Markdown directly (newlines trigger auto-detection, first # heading becomes the name)
npx -y agent-add --host claude-code \
  --prompt $'# Code Review Rules\n\nAlways review for security issues first.'

# From the popular Cursor Rules repository
npx -y agent-add --host cursor \
  --prompt 'https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/nextjs-react-tailwind/.cursorrules'

# From an HTTP URL for team-shared prompts
npx -y agent-add --host claude-code \
  --prompt 'https://your-team.com/shared/code-review-rules.md'

Install Slash Command

# From the commands repository
npx -y agent-add --host cursor \
  --command 'https://github.com/wshobson/commands.git#tools/security-scan.md'

npx -y agent-add --host claude-code \
  --command 'https://github.com/wshobson/commands.git#tools/ai-assistant.md'

Install Sub-agent

# From VoltAgent's awesome-claude-code-subagents repository (⭐16k)
npx -y agent-add --host cursor \
  --sub-agent 'https://github.com/VoltAgent/awesome-claude-code-subagents.git#categories/01-core-development/backend-developer.md'

# Install the full trio: backend + Python + code-reviewer
npx -y agent-add --host cursor \
  --sub-agent 'https://github.com/VoltAgent/awesome-claude-code-subagents.git#categories/01-core-development/backend-developer.md' \
  --sub-agent 'https://github.com/VoltAgent/awesome-claude-code-subagents.git#categories/02-language-specialists/python-pro.md' \
  --sub-agent 'https://github.com/VoltAgent/awesome-claude-code-subagents.git#categories/04-quality-security/code-reviewer.md'

Source Formats

Source	Example	MCP	Prompt	Skill	Command	Sub-agent
Inline JSON	`'{"name":{...}}'` (starts with `{`)	✅	❌	❌	❌	❌
Inline Markdown	`$'# Title\n\nContent'` (contains newline)	❌	✅	❌	✅	✅
Local path	`./mcps/config.json`	✅	✅	✅	✅	✅
Git SSH	`git@github.com:org/repo.git@main#path`	✅	✅	✅	✅	✅
Git HTTPS	`https://github.com/org/repo.git@v1.0#path`	✅	✅	✅	✅	✅
HTTP URL	`https://example.com/config.json`	✅	✅	❌	✅	✅

Git sources support @ref for branch/tag/commit and #path for sub-paths within the repo (sparse checkout — won't clone the entire repository).

Inline JSON format: {"<name>": {...config...}}, the key is the asset name. Inline Markdown infers the name from the first # heading.

Skill is a directory asset and does not support inline content or single-file HTTP URLs.

CLI Reference

npx -y agent-add [OPTIONS]

Options:
  --host <host>         Target AI tool ID
  --overwrite          Force rewriting same-name assets, even if identical
  --global              Install all supplied assets into the host's user scope
  --mcp <source>        Install an MCP Server config
  --skill <source>      Install a Skill directory
  --prompt <source>     Install a Prompt file
  --command <source>    Install a Command file
  --sub-agent <source>  Install a Sub-agent file
  --pack <source>       Install an Agent Pack manifest
  -V, --version         Show version number
  -h, --help            Show help

Repeat asset flags to install more than one, or combine them with --pack.

Asset Developer Guide

If you are a developer or distributor of MCP Servers, Skills, Prompts, or other assets, here are the file format specifications that agent-add accepts.

MCP Config File

agent-add supports two JSON formats and auto-detects which one you're using:

Format A: Inner config (single server)

{
  "command": "npx",
  "args": ["@playwright/mcp@latest"],
  "env": {}
}

The asset name is inferred from the filename: playwright.json → name is playwright.

Format B: Full config with mcpServers wrapper

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

agent-add automatically unwraps mcpServers and extracts the inner server name and config.

The wrapped format currently supports a single server only. To install multiple MCPs, use multiple --mcp flags or Pack multi-source syntax.

Inline JSON also supports both formats:

# Format A: top-level key is the name
npx -y agent-add --mcp '{"playwright":{"command":"npx","args":["-y","@playwright/mcp"]}}'

# Format B: auto-unwraps mcpServers
npx -y agent-add --mcp '{"mcpServers":{"playwright":{"command":"npx","args":["-y","@playwright/mcp"]}}}'

agent-add automatically merges the config into the target host's config file (e.g. .cursor/mcp.json under mcpServers, Codex's TOML, etc.) — asset developers don't need to worry about host differences.

Skill Directory

A Skill is a directory that must contain a SKILL.md entry file at the root:

my-skill/
├── SKILL.md          ← required
├── helpers/
│   └── utils.py
└── templates/
    └── report.md

<!-- SKILL.md -->
---
name: my-skill
description: A reusable agent skill.
---

# Skill: my-skill

This skill does something useful.

The entire directory is recursively copied to the host's skills directory (e.g. .cursor/skills/my-skill/). With --overwrite, the directory is replaced with the source, removing obsolete files.

Prompt File (Rule file / System Prompt)

Plain Markdown file with no special format requirements:

# Code Review Rules

Always review for security issues first.
Use bullet points for lists.

agent-add automatically selects the write strategy based on the host:

Append mode (Cursor → AGENTS.md, Claude Code → CLAUDE.md, etc.): content is wrapped in HTML comment markers and appended to the file, ensuring idempotency:
```

# Code Review Rules
...

```
Standalone file mode (Windsurf → .windsurf/rules/, Roo Code → .roo/rules/, etc.): creates a <name>.md file in the rules directory

Command File

Markdown file with optional YAML frontmatter:

---
description: Run a comprehensive code review.
---

# code-review

Review the current file for bugs, security issues, and style violations.

Installed to the host's commands directory (e.g. .cursor/commands/code-review.md).

For Gemini CLI, the Markdown body is serialized as the prompt string in .gemini/commands/<name>.toml. An optional frontmatter description string is preserved; other frontmatter fields are omitted. Other hosts keep the original Markdown.

Sub-agent File

Markdown + YAML frontmatter. Supports agent-add/<host>/<key> host specialization syntax — a single file can provide different frontmatter field values for different hosts. This is especially useful when specifying the model for a sub-agent.

For example, to use the fastest model on each host for a sub-agent:

---
name: playwright-tester
description: A playwright testing agent.
agent-add/cursor/model: fast
agent-add/claude-code/model: haiku
---

# Playwright Test Agent

Plan and generate Playwright tests.

During installation, agent-add will:

Promote matching agent-add/<host>/* values to top-level keys
Remove all agent-add/* prefixed keys

After installing to Cursor:

---
name: playwright-tester
description: A playwright testing agent.
model: fast
---

# Playwright Test Agent

Plan and generate Playwright tests.

After installing to Claude Code:

---
name: playwright-tester
description: A playwright testing agent.
model: haiku
---

# Playwright Test Agent

Plan and generate Playwright tests.

Pack Manifest

A JSON file that bundles multiple assets for distribution:

{
  "name": "my-team/frontend-pack",
  "assets": [
    { "type": "mcp",      "source": "https://github.com/modelcontextprotocol/servers.git#.mcp.json" },
    { "type": "skill",    "source": "https://github.com/anthropics/skills.git#skills/pdf" },
    { "type": "prompt",   "source": "https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/nextjs-react-tailwind/.cursorrules" },
    { "type": "command",  "source": "https://github.com/wshobson/commands.git#tools/security-scan.md" },
    { "type": "subAgent", "source": "https://github.com/VoltAgent/awesome-claude-code-subagents.git#categories/01-core-development/backend-developer.md" }
  ]
}

Field specification:

Field	Required	Description
`name`	Yes	Format `namespace/pack-name`, only `[a-zA-Z0-9_-]` allowed
`assets`	Yes	At least 1 item
`assets[].type`	Yes	`mcp` \| `skill` \| `prompt` \| `command` \| `subAgent`
`assets[].source`	Yes	String or array of strings (multi-source auto-expands into multiple assets)

Multi-source example — install multiple MCP servers at once:

{
  "name": "my-team/mcp-collection",
  "assets": [
    {
      "type": "mcp",
      "source": [
        "https://github.com/modelcontextprotocol/servers.git#.mcp.json",
        "https://raw.githubusercontent.com/my-team/mcps/main/filesystem.json"
      ]
    }
  ]
}

Asset Name Inference

When no name is explicitly specified, agent-add infers it from the source string in this priority order:

Source Type	Inference Rule	Example
Inline JSON	Extract the single top-level key	`{"playwright":{...}}` → `playwright`
Inline Markdown	Extract the first `# heading`, convert to kebab-case	`# Code Review` → `code-review`
Git URL + `#path`	Take the last segment after `#` (strip extension)	`...git#skills/pdf` → `pdf`
Git URL without `#`	Take the repo name (strip `.git` suffix)	`...playwright.git` → `playwright`
Local path / HTTP	Take the filename (strip extension)	`./mcps/playwright.json` → `playwright`

Contributing

Contributions welcome! Here's how to get started.

Setup

npm install
npm run build
npm run install:vibe

The last command installs dev assets via the pack manifest at vibe/manifest.json, including scenario-test (skill + command + sub-agent), a verify-host-readme command, and a system prompt. Explicit unsupported assets fail; unsupported Pack entries are skipped without resolving their sources.

Running Tests

npm test                # All unit + integration tests
npm run test:contract   # CLI black-box contract tests only
npx vitest run tests/unit/hosts/cursor.test.ts  # Single file

Scenario tests (Gherkin .feature files in tests/features/) are executed by AI agents via scenario-test. Use the /scenario-exec command in your AI tool:

/scenario-exec tests/features/core
/scenario-exec tests/features/host

Each scenario runs in an isolated temp directory. The run configuration is defined in tests/features/scenario-run-config.md (executor, concurrency, tag filters, etc.). Make sure to npm run build before running scenarios as they invoke the compiled bin/agent-add.js.

License

Mozilla Public License 2.0

Name		Name	Last commit message	Last commit date
.github		.github
bin		bin
docs		docs
src		src
tests		tests
vibe		vibe
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository navigation

About

Repository files navigation

agent-add

Supported Hosts

Project scope (default)

User scope (`--global`)

Why agent-add?

Usage

Project or global?

Install a pack

Install MCP

Install Skill

Install Prompt (Rule file / System Prompt)

Install Slash Command

Install Sub-agent

Source Formats

CLI Reference

Asset Developer Guide

MCP Config File

Skill Directory

Prompt File (Rule file / System Prompt)

Command File

Sub-agent File

Pack Manifest

Asset Name Inference

Contributing

Setup

Running Tests

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

agent-add

Supported Hosts

Project scope (default)

User scope (--global)

Why agent-add?

Usage

Project or global?

Install a pack

Install MCP

Install Skill

Install Prompt (Rule file / System Prompt)

Install Slash Command

Install Sub-agent

Source Formats

CLI Reference

Asset Developer Guide

MCP Config File

Skill Directory

Prompt File (Rule file / System Prompt)

Command File

Sub-agent File

Pack Manifest

Asset Name Inference

Contributing

Setup

Running Tests

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

User scope (`--global`)