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
Cursor	✅	✅	✅	✅	✅
Claude Code	✅	✅	✅	✅	✅
Trae	✅	✅	✅	❌	❌
Qwen Code	✅	✅	✅	✅	✅
GitHub Copilot	✅	✅	✅	✅	✅
Codex CLI	✅	✅	✅	❌	✅
Windsurf	✅	✅	✅	✅	❌
Gemini CLI	✅	✅	✅	✅	✅
Kimi Code	✅	✅	✅	❌	❌
Augment	✅	✅	✅	✅	✅
Roo Code	✅	✅	✅	✅	❌
Kiro CLI	✅	✅	✅	❌	✅
Tabnine CLI	✅	✅	❌	✅	❌
Kilo Code	✅	✅	✅	✅	✅
opencode	✅	✅	✅	✅	✅
OpenClaw	✅	✅	✅	❌	❌
Mistral Vibe	✅	✅	✅	❌	❌
Claude Desktop	✅	❌	❌	❌	❌

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	`[email protected]:org/repo.git@main#path`	✅	✅	✅	✅	✅
Git HTTPS	`https://github.com/org/[email protected]#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
  --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 --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/).

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

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.

License

Mozilla Public License 2.0

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

agent-add

Why agent-add?

Usage

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

Uh oh!

Releases 1

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

agent-add

Why agent-add?

Usage

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

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages