---

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 工具	MCP	Prompt	Skill	斜杠命令	子代理
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	✅	❌	❌	❌	❌

---

为什么需要 agent-add？

各个 AI 工具配置不尽相同，agent-add 可以帮您抹平它们的不同之处，用一条命令就能安装到所有 AI 工具中的任意一个：

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'

# 不指定 AI 工具将会有个可交互的菜单供选择
npx -y agent-add --mcp 'https://github.com/modelcontextprotocol/servers.git#.mcp.json'

用法

安装 Node.js（v18+）后即可通过 npx 直接运行，无需额外安装。

安装 MCP

# 从 JSON 源码安装
npx -y agent-add \
  --mcp '{"playwright":{"command":"npx","args":["-y","@playwright/mcp"]}}'

# 从 Git 仓库中的配置文件安装
npx -y agent-add \
  --mcp 'https://github.com/modelcontextprotocol/servers.git#.mcp.json'

# 从 HTTP URL 直接安装
npx -y agent-add \
  --mcp 'https://raw.githubusercontent.com/modelcontextprotocol/servers/main/.mcp.json'

安装 Skill

# 从 Anthropic 官方 Skills 仓库安装
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'

安装 Prompt（Rule 文件 / System Prompt）

# 直接传入 Markdown 内联文本（含换行自动识别，第一个 # 标题作为名称）
npx -y agent-add --host claude-code \
  --prompt $'# Code Review Rules\n\nAlways review for security issues first.'

# 从知名 Cursor Rules 仓库安装
npx -y agent-add --host cursor \
  --prompt 'https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/nextjs-react-tailwind/.cursorrules'

# 从 HTTP URL 安装团队共享的 Prompt
npx -y agent-add --host claude-code \
  --prompt 'https://your-team.com/shared/code-review-rules.md'

安装斜杠命令（Command）

# 从 commands 仓库安装
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'

安装子代理（Sub-agent）

# 从社区 Sub-agent 仓库安装后端开发代理（⭐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'

# 安装完整的三件套：后端 + Python + 代码审查
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'

来源格式

来源	示例	MCP	Prompt	Skill	Command	Sub-agent
内联 JSON	'{"name":{...}}'（以 { 开头）	✅	❌	❌	❌	❌
内联 Markdown	$'# Title\n\nContent'（含换行）	❌	✅	❌	✅	✅
本地路径	./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 来源支持 @ref 指定分支/标签/commit，#path 指定仓库内子路径（sparse checkout，不会克隆整个仓库）。

内联 JSON 格式为 {"<名称>": {...config...}}，key 即资产名称。内联 Markdown 从第一个 # 标题 推断名称。

Skill 是目录资产，不支持内联内容或单文件 HTTP URL。

CLI 参考

npx -y agent-add [OPTIONS]

Options:
  --host <host>         指定目标 AI Agent
  --mcp <source>        安装 MCP Server 配置
  --skill <source>      安装 Skill 目录
  --prompt <source>     安装 Prompt 文件
  --command <source>    安装 Command 文件
  --sub-agent <source>  安装 Sub-agent 文件
  --pack <source>       安装 Agent Pack manifest
  -V, --version         显示版本号
  -h, --help            显示帮助信息

所有资产 flag 可重复使用（安装多个同类资产），也可与 --pack 自由组合。

资产开发者指南

如果你是 MCP Server、Skill、Prompt 等资产的开发者或分发者，以下是 agent-add 接受的文件格式规范。

MCP 配置文件

agent-add 支持两种 JSON 格式，自动识别：

格式 A：内层配置（单个 server）

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

资产名从文件名推断：playwright.json → 名称为 playwright。

格式 B：包含 mcpServers 的完整配置

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

agent-add 会自动解包 mcpServers，提取内层的 server 名称和配置。

包裹格式目前仅支持单个 server。如需安装多个 MCP，请使用多个 --mcp flag 或 Pack 的多源语法。

内联 JSON 同样支持两种格式：

# 格式 A：顶层 key 即名称
npx -y agent-add --mcp '{"playwright":{"command":"npx","args":["-y","@playwright/mcp"]}}'

# 格式 B：自动解包 mcpServers
npx -y agent-add --mcp '{"mcpServers":{"playwright":{"command":"npx","args":["-y","@playwright/mcp"]}}}'

agent-add 会自动将配置合并到目标宿主的配置文件中（如 .cursor/mcp.json 的 mcpServers 字段、Codex 的 TOML 等），开发者无需关心宿主差异。

Skill 目录

Skill 是一个目录，根目录必须包含 SKILL.md 入口文件：

my-skill/
├── SKILL.md          ← 必须存在
├── helpers/
│   └── utils.py
└── templates/
    └── report.md

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

# Skill: my-skill

This skill does something useful.

安装时整个目录会被递归复制到宿主的 skills 目录下（如 .cursor/skills/my-skill/）。

Prompt 文件（Rule 文件 / System Prompt）

纯 Markdown 文件，无特殊格式要求：

# Code Review Rules

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

agent-add 根据宿主自动选择写入策略：

• 追加模式（Cursor → AGENTS.md、Claude Code → CLAUDE.md 等）：内容被 HTML 注释 marker 包裹后追加到文件末尾，保证幂等：

  <!-- agent-add:code-review-rules -->
  # Code Review Rules
  ...
  <!-- /agent-add:code-review-rules -->
  

• 独立文件模式（Windsurf → .windsurf/rules/、Roo Code → .roo/rules/ 等）：在规则目录下创建 <name>.md 文件

Command 文件

Markdown 文件，支持可选的 YAML frontmatter：

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

# code-review

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

安装到宿主的 commands 目录（如 .cursor/commands/code-review.md）。

对于 Gemini CLI，Markdown 正文会序列化为 .gemini/commands/<name>.toml 中的 prompt 字符串。可选的 frontmatter description 字符串会保留，其余 frontmatter 字段会省略。其他宿主仍保留原始 Markdown。

Sub-agent 文件

Markdown + YAML frontmatter。支持 agent-add/<host>/<key> 宿主特化语法 —— 同一份文件可为不同宿主提供不同的 frontmatter 字段值。这在指定 sub-agent 的模型时格外有用

比如我们希望这个 sub-agent 在 Cursor 和 Claude Code 都使用各自最快速的模型：

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

安装时，agent-add 会：

1. 将匹配当前宿主的 agent-add/<host>/* 值提升到顶层
2. 移除所有 agent-add/* 前缀的 key

安装到 Cursor 后：

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

# Playwright Test Agent

Plan and generate Playwright tests.

安装到 Claude Code 后：

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

# Playwright Test Agent

Plan and generate Playwright tests.

Pack Manifest

JSON 文件，将多种资产打包在一起分发：

{
  "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" }
  ]
}

字段规范：

字段	要求	说明
name	必填	格式 namespace/pack-name，仅允许 [a-zA-Z0-9_-]
assets	必填	至少 1 项
assets[].type	必填	mcp | skill | prompt | command | subAgent
assets[].source	必填	字符串或字符串数组（多源自动展开为多个同类资产）

多源示例 —— 一次安装多个 MCP：

{
  "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"
      ]
    }
  ]
}

资产名称推断

当未显式指定名称时，agent-add 按以下优先级从来源字符串推断：

来源类型	推断规则	示例
内联 JSON	取唯一的顶层 key	{"playwright":{...}} → playwright
内联 Markdown	取第一个 # 标题，转 kebab-case	# Code Review → code-review
Git URL + #path	取 # 后路径的最后一段（去扩展名）	...git#skills/pdf → pdf
Git URL 无 #	取仓库名（去 .git 后缀）	...playwright.git → playwright
本地路径 / HTTP	取文件名（去扩展名）	./mcps/playwright.json → playwright

贡献

欢迎贡献！以下是入门指南。

环境搭建

npm install
npm run build
npm run install:vibe

最后一条命令通过 vibe/manifest.json 包清单安装开发所需资产，包括 scenario-test（skill + command + sub-agent）、verify-host-readme 命令和系统提示词。当前宿主不支持的资产会被自动跳过。

运行测试

npm test                # 所有 unit + integration 测试
npm run test:contract   # 仅 CLI 黑盒契约测试
npx vitest run tests/unit/hosts/cursor.test.ts  # 单个文件

场景测试（tests/features/ 中的 Gherkin .feature 文件）通过 AI agent 执行，需要预先安装 scenario-test。在 AI 工具中使用 /scenario-exec 命令触发：

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

每个场景在独立的临时目录中运行。运行配置定义在 tests/features/scenario-run-config.md（executor、并发数、tag 过滤等）。运行前请确保已执行 npm run build，因为场景测试调用编译后的 bin/agent-add.js。

License

Mozilla Public License 2.0