Agent Add
Cross-host AI Agent Pack installer β install MCP, Skill, Prompt, Command, Sub-agent in one command
Ask AI about Agent Add
Powered by Claude Β· Grounded in docs
I know everything about Agent Add. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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'
| AI Tool | MCP | Prompt | Skill | Command | Sub-agent |
|---|---|---|---|---|---|
| β | β | β | β | β | |
| β | β | β | β | β | |
| β | β | β | β | β | |
| β | β | β | β | β | |
| β | β | β | β | β | |
| β | β | β | β | β | |
| β | β | β | β | β | |
| β | β | β | β | β | |
| β | β | β | β | β | |
| β | β | β | β | β | |
| β | β | β | β | β | |
| β | β | β | β | β | |
| β | β | β | β | β | |
| β | β | β | β | β | |
| β | β | β | β | β | |
| β | β | β | β | β | |
| β | β | β | β | β | |
| β | β | β | β | β |
Why agent-add?
Every AI tool has its own config format β Cursor uses .cursor/mcp.json, Claude Code uses .mcp.json, Windsurf uses global paths, Codex even uses 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.
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'
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
@reffor branch/tag/commit and#pathfor 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
--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
All asset flags can be repeated (to install multiple assets of the same type) and freely combined 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
--mcpflags 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/).
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:<!-- agent-add:code-review-rules --> # Code Review Rules ... <!-- /agent-add:code-review-rules --> - Standalone file mode (Windsurf β
.windsurf/rules/, Roo Code β.roo/rules/, etc.): creates a<name>.mdfile 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).
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-get/cursor/model: fast
agent-get/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. Assets unsupported by the detected host are automatically skipped.
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.
