{ "canonical_name": "pea3nut/agent-add", "compilation_id": "pack_803a6bb89aa44412b35cc222f560d1ae", "created_at": "2026-05-19T05:33:59.749021+00:00", "created_by": "project-pack-compiler", "feedback": { "carrier_selection_notes": [ "viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight", "recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight" ], "evidence_delta": { "confirmed_claims": [ "identity_anchor_present", "capability_and_host_targets_present", "install_path_declared_or_better" ], "missing_required_fields": [], "must_verify_forwarded": [ "Run or inspect `npx -y agent-add` in an isolated environment.", "Confirm the project exposes the claimed capability to at least one target host." ], "quickstart_execution_scope": "allowlisted_sandbox_smoke", "sandbox_command": "npx -y agent-add", "sandbox_container_image": "node:22-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "deterministic_isolated_install", "sandbox_validation_id": "sbx_42702166d7c54a9d8b844f82a712ea33" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_9b12abce4417f6a9c55512a11e7a4543", "canonical_name": "pea3nut/agent-add", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/pea3nut/agent-add", "slug": "agent-add", "source_packet_id": "phit_36403cd08fb24db684cbb706adfb5626", "source_validation_id": "dval_3e340640c8434f42816f732f71099d5f" }, "merchandising": { "best_for": "需要软件开发与交付能力，并使用 mcp_host的用户", "github_forks": null, "github_stars": null, "one_liner_en": "
", "one_liner_zh": "
", "primary_category": { "category_id": "software-development", "confidence": "medium", "name_en": "Software Development", "name_zh": "软件开发与交付", "reason": "matched_keywords:code, git" }, "target_user": "使用 mcp_host, claude, claude_code 等宿主 AI 的用户", "title_en": "agent-add", "title_zh": "agent-add 能力包", "visible_tags": [ { "label_en": "Browser Agents", "label_zh": "浏览器 Agent", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-browser-agents", "type": "product_domain" }, { "label_en": "Web Task Automation", "label_zh": "网页任务自动化", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-web-task-automation", "type": "user_job" }, { "label_en": "Browser Automation", "label_zh": "浏览器自动化", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-browser-automation", "type": "core_capability" }, { "label_en": "Node-based Workflow", "label_zh": "节点式流程编排", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-node-based-workflow", "type": "workflow_pattern" }, { "label_en": "Local-first", "label_zh": "本地优先", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-local-first", "type": "selection_signal" } ] }, "packet_id": "phit_36403cd08fb24db684cbb706adfb5626", "page_model": { "artifacts": { "artifact_slug": "agent-add", "files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json", "REPO_INSPECTION.md", "CAPABILITY_CONTRACT.json", "EVIDENCE_INDEX.json", "CLAIM_GRAPH.json" ], "required_files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json" ] }, "detail": { "capability_source": "Project Hit Packet + DownstreamValidationResult", "commands": [ { "command": "npx -y agent-add", "label": "Node.js / npx · 官方安装入口", "source": "https://github.com/pea3nut/agent-add#readme", "verified": true } ], "display_tags": [ "浏览器 Agent", "网页任务自动化", "浏览器自动化", "节点式流程编排", "本地优先" ], "eyebrow": "软件开发与交付", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要软件开发与交付能力，并使用 mcp_host的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "
" }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "mcp_host, claude, claude_code, cursor, chatgpt", "label": "Check 2", "value": "确认宿主兼容" }, { "body": "publish to Doramagic.ai project surfaces", "label": "Check 3", "value": "先隔离验证" } ], "mode": "mcp_config, recipe, host_instruction, eval, preflight", "pitfall_log": { "items": [ { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.1.0", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_5c106a51ec5d4f999b8bcef8e68a89ec | https://github.com/pea3nut/agent-add/releases/tag/1.1.0 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v1.1.0", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "I built a CLI that installs MCP, skills, prompts, commands and sub ... 6 Apr 2026 · Project & Supported Tools. The source code is hosted on GitHub: https://github.com/pea3nut/agent-add ... r/mcp - I built a tool that auto- ...", "category": "安装坑", "evidence": [ "social_signal:reddit | ssig_6d54ef81557a451081be71b052d0e31b | https://www.reddit.com/r/ClaudeAI/comments/1sdrk6k/i_built_a_cli_that_installs_mcp_skills_prompts/ | I built a CLI that installs MCP, skills, prompts, commands and sub ..." ], "severity": "medium", "suggested_check": "Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。", "title": "社区讨论暴露的待验证问题：I built a CLI that installs MCP, skills, prompts, commands and sub ...", "user_impact": "这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。" }, { "body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。", "category": "配置坑", "evidence": [ "capability.host_targets | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | host_targets=mcp_host, claude, claude_code, cursor, chatgpt" ], "severity": "medium", "suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。", "title": "可能修改宿主 AI 配置", "user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。" }, { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" }, { "body": "未记录 last_activity_observed。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | last_activity_observed missing" ], "severity": "medium", "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。", "title": "维护活跃度未知", "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "downstream_validation.risk_items | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "risks.scoring_risks | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。", "title": "存在评分风险", "user_impact": "风险会影响是否适合普通用户安装。" }, { "body": "issue_or_pr_quality=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | issue_or_pr_quality=unknown" ], "severity": "low", "suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。", "title": "issue/PR 响应质量未知", "user_impact": "用户无法判断遇到问题后是否有人维护。" }, { "body": "release_recency=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | release_recency=unknown" ], "severity": "low", "suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。", "title": "发布节奏不明确", "user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：v1.1.0。", "title": "踩坑日志" }, "snapshot": { "contributors": null, "forks": null, "license": "unknown", "note": "站点快照，非实时质量证明；用于开工前背景判断。", "stars": null }, "source_url": "https://github.com/pea3nut/agent-add", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "
", "title": "agent-add 能力包", "trial_prompt": "# agent-add - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for pea3nut/agent-add.\n\nProject:\n- Name: agent-add\n- Repository: https://github.com/pea3nut/agent-add\n- Summary:
\n- Host target: mcp_host, claude, claude_code, cursor\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet:
\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. introduction: Introduction. Produce one small intermediate artifact and wait for confirmation.\n2. getting-started: Getting Started. Produce one small intermediate artifact and wait for confirmation.\n3. system-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. host-integration: Host Integration. Produce one small intermediate artifact and wait for confirmation.\n5. source-resolution: Source Resolution. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/pea3nut/agent-add#readme\n- tests/fixtures/skill/my-skill/SKILL.md\n- README.md\n- package.json\n- bin/agent-add.js\n- src/cli.ts\n- src/index.ts\n- src/installer.ts\n- src/hosts/index.ts\n- src/source/index.ts\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n", "voices": [ { "body": "来源平台：github, reddit。github/github_release: v1.1.0（https://github.com/pea3nut/agent-add/releases/tag/1.1.0）；reddit: I built a CLI that installs MCP, skills, prompts, commands and sub ...（https://www.reddit.com/r/ClaudeAI/comments/1sdrk6k/i_built_a_cli_that_installs_mcp_skills_prompts/）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "kind": "github_release", "source": "github", "title": "v1.1.0", "url": "https://github.com/pea3nut/agent-add/releases/tag/1.1.0" }, { "kind": "searxng_indexed", "source": "reddit", "title": "I built a CLI that installs MCP, skills, prompts, commands and sub ...", "url": "https://www.reddit.com/r/ClaudeAI/comments/1sdrk6k/i_built_a_cli_that_installs_mcp_skills_prompts/" } ], "status": "已收录 2 条来源", "title": "社区讨论" } ] }, "homepage_card": { "category": "软件开发与交付", "desc": "
", "effort": "安装已验证", "forks": null, "icon": "code", "name": "agent-add 能力包", "risk": "需复核", "slug": "agent-add", "stars": null, "tags": [ "浏览器 Agent", "网页任务自动化", "浏览器自动化", "节点式流程编排", "本地优先" ], "thumb": "gray", "type": "MCP 配置" }, "manual": { "markdown": "# https://github.com/pea3nut/agent-add 项目说明书\n\n生成时间：2026-05-15 10:35:27 UTC\n\n## 目录\n\n- [Introduction](#introduction)\n- [Getting Started](#getting-started)\n- [System Architecture](#system-architecture)\n- [Host Integration](#host-integration)\n- [Source Resolution](#source-resolution)\n- [Asset Types](#asset-types)\n- [Manifest System](#manifest-system)\n- [CLI Interface](#cli-interface)\n- [Testing](#testing)\n- [Project Configuration](#configuration)\n\n\n\n## Introduction\n\n### 相关页面\n\n相关主题：[Getting Started](#getting-started), [System Architecture](#system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n- [package.json](https://github.com/pea3nut/agent-add/blob/main/package.json)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n- [src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n- [src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n- [src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n- [vibe/system-prompt.md](https://github.com/pea3nut/agent-add/blob/main/vibe/system-prompt.md)\n
\n\n# Introduction\n\nagent-add is a unified CLI tool that streamlines the installation and management of AI coding agent assets across multiple host environments. It eliminates the need to manually configure MCP servers, skills, prompts, commands, and sub-agents by automating asset discovery, validation, and deployment to the appropriate host-specific directories.\n\n## Purpose and Scope\n\nagent-add addresses the fragmented ecosystem of AI coding assistants by providing a single command-line interface that works with 18 different host environments. Rather than maintaining separate installation instructions for Cursor, Claude Code, Windsurf, and other tools, developers and asset distributors can use agent-add to distribute assets universally.\n\n**Core capabilities include:**\n\n- **Asset Installation**: Install MCP servers, skills, prompts, commands, and sub-agents from local paths, Git URLs, or HTTP endpoints\n- **Host Abstraction**: Automatic detection and adaptation for each host's unique configuration format and directory structure\n- **Pack Distribution**: Bundle multiple assets into a single JSON manifest for team-wide distribution\n- **Atomic Operations**: Safe file writes using temp file + rename patterns to prevent corruption\n- **Idempotent Updates**: Marker-based append strategy ensures repeated installations do not create duplicates\n\n资料来源：[README.md:1-50](https://github.com/pea3nut/agent-add/blob/main/README.md)\n\n## Supported Hosts\n\nagent-add supports the following 18 AI coding host environments:\n\n| Host ID | Configuration Format | Install Directory |\n|---------|---------------------|-------------------|\n| `cursor` | JSON | `.cursor/` |\n| `claude-code` | JSON | `.claude/` |\n| `claude-desktop` | JSON | `~/Library/Application Support/Claude/` |\n| `windsurf` | JSON | `.windsurf/rules/` |\n| `github-copilot` | JSON | `.github/copilot/` |\n| `gemini` | JSON | `.gemini/` |\n| `roo-code` | JSON | `.roo/rules/` |\n| `kilo-code` | JSON | `.kilocode/` |\n| `qwen-code` | JSON | `.qwen/` |\n| `opencode` | JSON | `.opencode/` |\n| `augment` | JSON | `.augment/` |\n| `kiro` | JSON | `.kiro/` |\n| `tabnine` | JSON | `.tabnine/` |\n| `kimi` | JSON | `.kimi/` |\n| `trae` | JSON | `.trae/` |\n| `openclaw` | JSON | `.openclaw/` |\n| `codex` | TOML | `.codex/` |\n| `vibe` | TOML | `.vibe/` |\n\n资料来源：[vibe/system-prompt.md:30-35](https://github.com/pea3nut/agent-add/blob/main/vibe/system-prompt.md)\n\n## Supported Asset Types\n\nagent-add manages five distinct asset types, each with host-specific installation strategies:\n\n| Asset Type | Description | Install Behavior |\n|------------|-------------|------------------|\n| `mcp` | Model Context Protocol server configurations | JSON shallow merge or TOML array append |\n| `skill` | Reusable agent skill directories | Recursive directory copy |\n| `prompt` | System prompts or rule files | Append-with-marker or create-file-in-dir |\n| `command` | Slash commands | Create in commands directory |\n| `subAgent` | Sub-agent configurations | Create in agents directory |\n\n资料来源：[src/installer.ts:1-50](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n\n## Architecture Overview\n\nThe codebase follows a layered architecture pattern with clear separation of concerns:\n\n```mermaid\ngraph TD\n A[CLI Input] --> B[CLI Parser
src/cli.ts]\n B --> C[Installer Core
src/installer.ts]\n C --> D[Source Resolution
src/source/]\n D --> E[Validation]\n E --> F[Host Adapter
src/hosts/]\n F --> G[Asset Handler
src/assets/]\n G --> H[Filesystem]\n \n I[Pack Manifest] -.-> C\n J[18 Host Adapters] -.-> F\n K[5 Asset Handlers] -.-> G\n```\n\n**Layer responsibilities:**\n\n| Layer | Module | Responsibility |\n|-------|--------|----------------|\n| Input | `src/cli.ts` | Commander.js argument parsing, TTY detection, interactive host selection |\n| Core | `src/installer.ts` | Orchestration: input parsing → capability check → source resolution → validation → handler execution → summary |\n| Resolution | `src/source/` | Local file access, Git URL handling, HTTP fetching, inline content parsing |\n| Adaptation | `src/hosts/` | Host-specific directory paths, capability declarations, write strategies |\n| Execution | `src/assets/` | Type-specific installation logic (MCP merge, skill copy, prompt append, etc.) |\n\n资料来源：[vibe/system-prompt.md:45-65](https://github.com/pea3nut/agent-add/blob/main/vibe/system-prompt.md)\n\n## Core Data Flow\n\nThe installation pipeline follows a sequential process from CLI invocation to filesystem write:\n\n```mermaid\ngraph LR\n A[CLI flags / --pack Manifest] --> B[Explicit flag capability check
exit 2 if unsupported]\n B --> C[AssetDescriptor[]
type + source]\n C --> D[ResolvedSource[]
localPath + tempDir]\n D --> E[InstallJob[]
skip unsupported assets]\n E --> F[InstallResult[]
written / exists / updated / conflict / skipped / error]\n F --> G[Summary output]\n```\n\n**Processing stages:**\n\n1. **Input Collection**: Gather all asset sources from CLI flags and pack manifests\n2. **Capability Validation**: Verify each asset type is supported by the target host (exit 2 if explicit flag unsupported)\n3. **Source Resolution**: Convert sources to local file paths (git clone, http download, inline temp files)\n4. **Asset Validation**: Validate file existence, format compliance, and required metadata\n5. **Job Creation**: Build installation jobs, skipping assets with unsupported capabilities\n6. **Execution**: Dispatch to appropriate asset handler based on type\n7. **Result Reporting**: Output summary with status for each asset\n\n资料来源：[src/cli.ts:1-80](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n\n## Write Strategies\n\nDifferent asset types use different write strategies based on host capabilities:\n\n```mermaid\ngraph TD\n A[Asset Type] --> B{Write Strategy}\n B --> C[append-with-marker]\n B --> D[create-file-in-dir]\n B --> E[atomic-json-merge]\n B --> F[directory-copy]\n \n C --> G[HTML comment markers
]\n D --> H[Create new file
Skip if exists]\n E --> I[Temp file + rename
JSON shallow merge]\n F --> J[Recursive copy
SKILL.md required]\n```\n\n| Strategy | Used By | Behavior |\n|----------|---------|----------|\n| `append-with-marker` | Prompt (Cursor, Claude Code) | Wraps content in HTML comment markers, idempotent append |\n| `create-file-in-dir` | Prompt (Windsurf, Roo Code), Command, Sub-agent | Creates `.md` in rules/commands/agents directory |\n| `atomic-json-merge` | MCP (JSON hosts) | Shallow merge with temp file + rename for safety |\n| `toml-array-append` | MCP (Codex, Vibe) | Append to `[[mcp_servers]]` array |\n| `directory-copy` | Skill | Recursive copy to host's skills directory |\n\n资料来源：[src/installer.ts:50-120](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n\n## Source Resolution\n\nagent-add accepts assets from multiple source types with automatic detection:\n\n| Source Format | Example | Name Inference |\n|---------------|---------|---------------|\n| Git URL + `#path` | `https://github.com/user/repo.git#skills/pdf` | Last segment after `#` (strip extension) |\n| Git URL without `#` | `https://github.com/user/playwright.git` | Repo name (strip `.git`) |\n| Local path | `./mcps/playwright.json` | Filename (strip extension) |\n| HTTP URL | `https://example.com/config.json` | Filename (strip extension) |\n| Inline JSON | `{\"playwright\":{...}}` | Top-level key as name |\n| Inline Markdown | `# Code Review\\n\\nRules...` | First `# Heading` in kebab-case |\n\n资料来源：[src/source/infer-name.ts:1-50](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n\n## Installation and Usage\n\n### Quick Install\n\n```bash\n# Install a single MCP server\nnpx -y agent-add --host cursor --mcp 'https://github.com/modelcontextprotocol/servers.git#mcp/playwright'\n\n# Install multiple assets\nnpx -y agent-add --host cursor \\\n --mcp './configs/mcp.json' \\\n --skill './skills/pdf' \\\n --prompt './rules/code-review.md'\n\n# Install from a pack manifest\nnpx -y agent-add --host claude-code --pack './manifests/frontend-pack.json'\n```\n\n### CLI Options\n\n| Flag | Description | Can Repeat |\n|------|-------------|------------|\n| `--host ` | Target host ID (required in CI, optional in TTY) | No |\n| `--pack ` | Install from a pack manifest | Yes |\n| `--mcp ` | Install MCP server configuration | Yes |\n| `--skill ` | Install skill directory | Yes |\n| `--prompt ` | Install prompt/rule file | Yes |\n| `--command ` | Install slash command | Yes |\n| `--sub-agent ` | Install sub-agent file | Yes |\n\n资料来源：[src/cli.ts:40-60](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n\n## Key Design Decisions\n\nThe architecture reflects several intentional design choices:\n\n**Atomic JSON Writes**: MCP configuration uses temp file + rename pattern to prevent corruption from interrupted writes. 资料来源：[vibe/system-prompt.md:70-72](https://github.com/pea3nut/agent-add/blob/main/vibe/system-prompt.md)\n\n**Marker-Based Idempotency**: Prompt append mode uses `` HTML comment markers, ensuring repeated installations update existing blocks rather than creating duplicates.\n\n**Explicit Flag Rejection**: When using explicit flags like `--mcp`, agent-add validates host capability and exits with code 2 if unsupported. Pack sources skip unsupported assets silently instead.\n\n**Non-TTY Strict Mode**: CI environments must explicitly specify `--host` to prevent ambiguous behavior in automated pipelines.\n\n**Inline Content Support**: Prompt/Command/Sub-agent assets support inline content via newline detection, while MCP supports inline JSON via brace detection. HTTP and inline sources are explicitly rejected for Skill type assets.\n\n资料来源：[src/installer.ts:80-100](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n\n## Project Structure\n\n```\nagent-add/\n├── bin/\n│ └── agent-add.js # Compiled entry point\n├── src/\n│ ├── index.ts # Main entry, program creation\n│ ├── cli.ts # Commander definition + TTY detection\n│ ├── installer.ts # Orchestration core\n│ ├── hosts/ # Host adapter layer (18 hosts)\n│ │ ├── types.ts # HostAdapter, AssetCapability types\n│ │ ├── index.ts # Host registry (Map)\n│ │ └── .ts # Per-host adapter implementations\n│ ├── assets/ # 5 asset type handlers\n│ │ ├── mcp.ts # JSON/TOML MCP handling\n│ │ ├── skill.ts # Directory copy + validation\n│ │ ├── prompt.ts # Append or create-file strategy\n│ │ ├── command.ts # Command file creation\n│ │ └── subAgent.ts # Sub-agent file creation\n│ ├── source/ # Source resolution\n│ │ ├── infer-name.ts # Asset name inference\n│ │ └── expand-directory.ts # Directory expansion\n│ ├── manifest/ # Pack manifest handling\n│ │ └── parser.ts # Zod schema validation\n│ └── utils/ # Shared utilities\n│ └── unwrap-mcp-servers.ts\n├── tests/\n│ ├── unit/ # Unit tests per module\n│ ├── features/ # Gherkin scenario tests\n│ └── fixtures/ # Static test fixtures\n└── vibe/ # Development assets\n ├── manifest.json # Dev pack manifest\n └── tasks/ # AI task definitions\n```\n\n资料来源：[README.md:80-100](https://github.com/pea3nut/agent-add/blob/main/README.md)\n\n## Development\n\n```bash\n# Setup\nnpm install\nnpm run build\n\n# Run tests\nnpm test # All unit + integration tests\nnpm run test:contract # CLI black-box contract tests only\nnpx vitest run tests/unit/hosts/cursor.test.ts # Single file\n\n# Run scenario tests (Gherkin)\n# Use /scenario-exec command in your AI tool:\n/scenario-exec tests/features/core\n/scenario-exec tests/features/host\n```\n\n资料来源：[README.md:100-120](https://github.com/pea3nut/agent-add/blob/main/README.md)\n\n---\n\n\n\n## Getting Started\n\n### 相关页面\n\n相关主题：[Introduction](#introduction), [CLI Interface](#cli-interface)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n- [src/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/index.ts)\n- [src/manifest/parser.ts](https://github.com/pea3nut/agent-add/blob/main/src/manifest/parser.ts)\n- [src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n- [src/source/expand-directory.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/expand-directory.ts)\n
\n\n# Getting Started\n\n## Overview\n\n`agent-add` is a CLI tool that automates the installation of AI agent assets—including MCP servers, skills, prompts, commands, and sub-agents—across 18 different AI coding assistant hosts. It provides a unified interface for installing community assets from Git repositories, local paths, HTTP URLs, or inline content.\n\nThe tool handles host-specific installation logic, validates assets before installation, and supports batch installation via pack manifests. 资料来源：[src/index.ts:1-7]()\n\n## Prerequisites\n\n- **Node.js**: v18 or later\n- **npm** or **pnpm** for package management\n- Access to the target host's configuration directory\n\n## Installation\n\n### Using npx (Recommended for One-time Use)\n\n```bash\nnpx -y agent-add --help\n```\n\n### Global Installation\n\n```bash\nnpm install -g agent-add\n# or\npnpm add -g agent-add\n```\n\n### Local Installation\n\n```bash\nnpm install\nnpm run build\n```\n\nThe CLI entry point is located at `bin/agent-add.js`. 资料来源：[README.md](https://github.com/pea3nut/agent-add)\n\n## Basic Usage\n\n### Interactive Mode\n\nWhen run in a TTY environment without specifying a host, `agent-add` prompts for target selection:\n\n```bash\nnpx -y agent-add\n```\n\nThe CLI detects available hosts in the current directory and presents an interactive selection menu. 资料来源：[src/cli.ts:56-77]()\n\n### Non-interactive Mode\n\nIn CI environments or when a host must be specified explicitly:\n\n```bash\nnpx -y agent-add --host [asset-flags...]\n```\n\nIf `--host` is omitted in non-TTY environments, the CLI exits with error code 2. 资料来源：[src/cli.ts:46-55]()\n\n## Supported Hosts\n\nThe following 18 hosts are supported:\n\n| Host ID | Type | Notes |\n|---------|------|-------|\n| `cursor` | JSON | Cursor IDE |\n| `claude-code` | Markdown | Claude Code CLI |\n| `claude-desktop` | JSON | Claude Desktop |\n| `windsurf` | JSON | Windsurf IDE |\n| `github-copilot` | JSON | GitHub Copilot |\n| `gemini` | JSON | Google Gemini |\n| `roo-code` | JSON | Roo Code |\n| `kilo-code` | JSON | Kilo Code |\n| `qwen-code` | JSON | Qwen Code |\n| `opencode` | JSON | OpenCode |\n| `augment` | JSON | Augment |\n| `kiro` | JSON | Kiro |\n| `tabnine` | JSON | Tabnine |\n| `kimi` | JSON | Kimi |\n| `trae` | JSON | Trae |\n| `openclaw` | JSON | OpenClaw |\n| `codex` | TOML | Codex |\n| `vibe` | TOML | Vibe |\n\n资料来源：[README.md](https://github.com/pea3nut/agent-add)\n\n## Asset Types\n\n### 1. MCP Server\n\nInstalls Model Context Protocol server configurations.\n\n```bash\nagent-add --host cursor --mcp 'https://github.com/modelcontextprotocol/servers.git#mcp/playwright'\n```\n\n### 2. Skill\n\nInstalls reusable agent skill directories containing `SKILL.md`.\n\n```bash\nagent-add --host cursor --skill './my-skill'\nagent-add --host cursor --skill 'https://github.com/anthropics/skills.git#skills/webapp-testing'\n```\n\n> **Note**: Skills must target directory sources (local paths or Git URLs). Inline content or direct HTTP(S) URLs are not supported. 资料来源：[src/installer.ts:80-84]()\n\n### 3. Prompt\n\nInstalls system prompts or rule files.\n\n```bash\nagent-add --host claude-code --prompt 'https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/nextjs-react-tailwind/.cursorrules'\n```\n\n### 4. Command\n\nInstalls slash commands for AI assistants.\n\n```bash\nagent-add --host cursor --command 'https://github.com/wshobson/commands.git#tools/security-scan.md'\n```\n\n### 5. Sub-agent\n\nInstalls specialized agent configurations.\n\n```bash\nagent-add --host cursor --sub-agent 'https://github.com/VoltAgent/awesome-claude-code-subagents.git#categories/01-core-development/backend-developer.md'\n```\n\n## Source Specification\n\n`agent-add` supports multiple source types for each asset:\n\n| Source Type | Syntax Example | Name Inference |\n|-------------|-----------------|----------------|\n| Git URL with path | `...git#skills/pdf` | Last segment after `#`, stripped extension |\n| Git URL without path | `...playwright.git` | Repository name (strip `.git`) |\n| Local path | `./mcps/playwright.json` | Filename (strip extension) |\n| HTTP URL | `https://example.com/config.json` | Filename (strip extension) |\n| Inline JSON | `{\"playwright\":{...}}` | Single top-level key |\n| Inline Markdown | `# Heading\\nContent` | First `# Heading`, kebab-cased |\n\n资料来源：[src/source/infer-name.ts:1-41]()\n\n## Pack Manifests\n\nBundles multiple assets for distribution via a JSON manifest:\n\n```json\n{\n \"name\": \"my-team/frontend-pack\",\n \"assets\": [\n { \"type\": \"mcp\", \"source\": \"https://github.com/modelcontextprotocol/servers.git#.mcp.json\" },\n { \"type\": \"skill\", \"source\": \"https://github.com/anthropics/skills.git#skills/pdf\" },\n { \"type\": \"prompt\", \"source\": \"https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/nextjs-react-tailwind/.cursorrules\" }\n ]\n}\n```\n\nInstall with:\n\n```bash\nagent-add --host cursor --pack './my-pack.json'\n```\n\nPack names must follow `namespace/pack-name` format with only `[a-zA-Z0-9_-]` characters. 资料来源：[src/manifest/parser.ts:1-31]()\n\n## Workflow Diagram\n\n```mermaid\ngraph TD\n A[CLI Input] --> B{Source Type Detection}\n B -->|Git URL| C[Clone to temp]\n B -->|Local Path| D[Resolve absolute path]\n B -->|HTTP URL| E[Download to temp]\n B -->|Inline| F[Write temp file]\n C --> G[Validate Asset]\n D --> G\n E --> G\n F --> G\n G -->|Invalid| H[Exit 2 with error]\n G -->|Valid| I{Check Host Capability}\n I -->|Unsupported| J[Skip asset]\n I -->|Supported| K[Install to Host]\n K --> L[Print Summary]\n J --> L\n```\n\n## Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| 0 | Success (all assets installed or already up-to-date) |\n| 1 | Partial failure (conflicts or errors occurred) |\n| 2 | Fatal error (invalid input, missing host, validation failure) |\n\n资料来源：[src/cli.ts:27-34]()\n\n## Examples\n\n### Install MCP Server from GitHub\n\n```bash\nnpx -y agent-add --host cursor --mcp 'https://github.com/modelcontextprotocol/servers.git#mcp/playwright'\n```\n\n### Install Multiple Assets\n\n```bash\nagent-add --host claude-code \\\n --mcp 'https://github.com/modelcontextprotocol/servers.git#mcp/playwright' \\\n --prompt 'https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/nextjs-react-tailwind/.cursorrules' \\\n --command 'https://github.com/wshobson/commands.git#tools/security-scan.md'\n```\n\n### Install Pack Manifest\n\n```bash\nagent-add --host cursor --pack 'https://github.com/VoltAgent/awesome-claude-code-subagents.git#manifests/backend-dev.json'\n```\n\n### Inline MCP Configuration\n\n```bash\nagent-add --host cursor --mcp '{\"playwright\":{\"command\":\"npx\",\"args\":[\"@playwright/mcp@latest\"]}}'\n```\n\n## Directory Expansion\n\nFor directories containing multiple assets, `agent-add` automatically expands them:\n\n```bash\nagent-add --host cursor --mcp './mcp-servers/'\n```\n\nEach `.json` file in the directory becomes a separate MCP asset. For skills, it scans for subdirectories containing `SKILL.md`. 资料来源：[src/source/expand-directory.ts:1-43]()\n\n## Validation\n\nBefore installation, `agent-add` validates:\n\n- **MCP**: File must exist and have `.json` extension\n- **Skill**: Directory must contain `SKILL.md`; cannot use inline or HTTP sources\n- **Prompt/Command/Sub-agent**: File must exist\n\n资料来源：[src/installer.ts:78-107]()\n\n## Next Steps\n\n- Review the [Asset Developer Guide](https://github.com/pea3nut/agent-add#asset-developer-guide) for creating distributable assets\n- Explore the [Host Adapter Architecture](https://github.com/pea3nut/agent-add#architecture-overview) for adding new hosts\n- Run `agent-add --help` for complete CLI reference\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Host Integration](#host-integration), [Source Resolution](#source-resolution)\n\n
\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/index.ts)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n- [src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n- [src/hosts/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/index.ts)\n- [src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n- [src/source/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/index.ts)\n- [src/assets/mcp.ts](https://github.com/pea3nut/agent-add/blob/main/src/assets/mcp.ts)\n- [src/assets/skill.ts](https://github.com/pea3nut/agent-add/blob/main/src/assets/skill.ts)\n- [src/assets/prompt.ts](https://github.com/pea3nut/agent-add/blob/main/src/assets/prompt.ts)\n- [src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n
\n\n# System Architecture\n\nagent-add is a cross-host AI agent pack installer CLI tool that enables developers to install MCP (Model Context Protocol), Skill, Prompt, Command, and Sub-agent assets into various AI agent hosts with a single command. The system is built with TypeScript 5.x in strict mode, targeting Node.js 18+ as a CommonJS bundle.\n\n## Overview\n\nThe architecture follows a layered, pipeline-based design that separates concerns between CLI interface, orchestration logic, host adapters, and asset handlers. The system is stateless—no install state files are maintained—relying instead on filesystem-based idempotency checks.\n\n```mermaid\ngraph TD\n subgraph CLI[\"CLI Layer\"]\n CLI_ENTRY[\"src/index.ts
Entry Point\"]\n CLI_CMD[\"src/cli.ts
Commander + TTY Detection\"]\n end\n\n subgraph Core[\"Core Pipeline\"]\n INST[\"src/installer.ts
Orchestration Core\"]\n VALIDATE[\"Validation Layer\"]\n RESOLVE[\"src/source/index.ts
Source Resolution\"]\n end\n\n subgraph Adapters[\"Host Adapter Layer\"]\n REGISTRY[\"src/hosts/index.ts
Host Registry\"]\n CURSOR[\"cursor.ts\"]\n CLAUDE_CODE[\"claude-code.ts\"]\n VIBE[\"vibe.ts\"]\n CODEX[\"codex.ts\"]\n end\n\n subgraph Handlers[\"Asset Handler Layer\"]\n MCP[\"assets/mcp.ts\"]\n SKILL[\"assets/skill.ts\"]\n PROMPT[\"assets/prompt.ts\"]\n COMMAND[\"assets/command.ts\"]\n SUBAGENT[\"assets/sub-agent.ts\"]\n end\n\n CLI_ENTRY --> CLI_CMD\n CLI_CMD --> INST\n INST --> VALIDATE\n INST --> RESOLVE\n RESOLVE --> REGISTRY\n REGISTRY --> CURSOR\n REGISTRY --> CLAUDE_CODE\n REGISTRY --> VIBE\n REGISTRY --> CODEX\n INST --> MCP\n INST --> SKILL\n INST --> PROMPT\n INST --> COMMAND\n INST --> SUBAGENT\n```\n\n资料来源：[src/index.ts:1-7]()\n\n## Directory Structure\n\n```\nagent-add/\n├── src/\n│ ├── index.ts # Entry point\n│ ├── cli.ts # Commander definition + TTY detection\n│ ├── installer.ts # Orchestration core\n│ ├── hosts/ # Host adapter layer\n│ │ ├── index.ts # Host registry (Map)\n│ │ ├── types.ts # HostAdapter, AssetCapability, WriteStrategy\n│ │ ├── README.md # Capability matrix (single source of truth)\n│ │ └── .ts # Per-host adapter (18 hosts)\n│ ├── assets/ # Asset type handlers\n│ │ ├── mcp.ts # JSON shallow merge + atomic write\n│ │ ├── skill.ts # Directory copy + SKILL.md validation\n│ │ ├── prompt.ts # Marker append or create-file-in-dir\n│ │ ├── command.ts # Command file handler\n│ │ └── sub-agent.ts # Sub-agent with host specialization\n│ └── source/ # Source resolution system\n│ ├── index.ts # Source resolution entry\n│ ├── infer-name.ts # Asset name inference\n│ ├── local.ts # Local file resolution\n│ ├── git.ts # Git URL cloning\n│ └── http.ts # HTTP/HTTPS download\n├── tests/\n│ ├── unit/ # Unit tests (vitest)\n│ ├── integration/ # Integration tests\n│ ├── features/ # Gherkin scenario tests\n│ └── fixtures/ # Static test fixtures\n└── dist/ # Built output\n```\n\n资料来源：[README.md:1-45]()\n\n## Core Data Flow\n\nThe installation pipeline follows a strict sequential flow from CLI input to final installation result:\n\n```mermaid\ngraph LR\n A[\"CLI Flags /
--pack Manifest\"] --> B[\"Explicit Flag
Capability Check\"]\n B --> C[\"AssetDescriptor[]
(type + source)\"]\n C --> D[\"ResolvedSource[]
(localPath + tempDir)\"]\n D --> E[\"InstallJob[]
(skip unsupported)\"]\n E --> F[\"InstallResult[]
(written/exists/updated/
conflict/skipped/error)\"]\n F --> G[\"Summary Output\"]\n```\n\n### Pipeline Stages\n\n| Stage | Input | Output | Key Operations |\n|-------|-------|--------|-----------------|\n| CLI Parsing | `process.argv` | `CliInput` object | TTY detection, host selection |\n| Capability Check | `CliInput` | `AssetDescriptor[]` | Validates `--host` exists, checks explicit flags against host capabilities |\n| Source Resolution | `AssetDescriptor[]` | `ResolvedSource[]` | Downloads Git/HTTP, extracts archives, writes inline sources to temp |\n| Job Creation | `ResolvedSource[]` | `InstallJob[]` | Filters assets unsupported by target host |\n| Handler Execution | `InstallJob[]` | `InstallResult[]` | Writes files using host-specific strategies |\n| Summary | `InstallResult[]` | Console output | Formatted install summary |\n\n资料来源：[src/installer.ts:1-200]()\n\n## Host Adapter Layer\n\nThe host adapter layer provides a unified interface for interacting with different AI agent hosts. Each host has specific capabilities, installation paths, and write strategies.\n\n### Host Registry\n\nThe `src/hosts/index.ts` file maintains a `Map` that maps host IDs to their adapter implementations:\n\n```typescript\nconst hostRegistry = new Map([\n ['cursor', new CursorAdapter()],\n ['claude-code', new ClaudeCodeAdapter()],\n ['claude-desktop', new ClaudeDesktopAdapter()],\n ['windsurf', new WindsurfAdapter()],\n ['github-copilot', new GitHubCopilotAdapter()],\n ['gemini', new GeminiAdapter()],\n ['roo-code', new RooCodeAdapter()],\n ['kilo-code', new KiloCodeAdapter()],\n ['qwen-code', new QwenCodeAdapter()],\n ['opencode', new OpenCodeAdapter()],\n ['augment', new AugmentAdapter()],\n ['kiro', new KiroAdapter()],\n ['tabnine', new TabnineAdapter()],\n ['kimi', new KimiAdapter()],\n ['trae', new TraeAdapter()],\n ['openclaw', new OpenClawAdapter()],\n ['codex', new CodexAdapter()],\n ['vibe', new VibeAdapter()],\n]);\n```\n\n资料来源：[src/hosts/index.ts]()\n资料来源：[src/hosts/README.md:1-100]()\n\n### Supported Hosts\n\n| Host ID | MCP | Prompt | Skill | Command | Sub-agent | Config Format |\n|---------|-----|--------|-------|---------|-----------|---------------|\n| cursor | ✅ | ✅ | ✅ | ✅ | ✅ | JSON |\n| claude-code | ✅ | ✅ | ❌ | ❌ | ❌ | JSON |\n| claude-desktop | ✅ | ❌ | ❌ | ❌ | ❌ | JSON |\n| windsurf | ✅ | ✅ | ✅ | ❌ | ❌ | JSON |\n| github-copilot | ✅ | ❌ | ❌ | ❌ | ❌ | JSON |\n| codex | ✅ | ✅ | ❌ | ❌ | ❌ | TOML |\n| vibe | ✅ | ✅ | ❌ | ❌ | ❌ | TOML |\n\n资料来源：[src/hosts/README.md:1-150]()\n\n### HostAdapter Interface\n\nEach host adapter implements the `HostAdapter` interface with asset-specific capabilities:\n\n```typescript\ninterface HostAdapter {\n readonly id: string;\n readonly displayName: string;\n readonly docs: string;\n readonly assets: Record;\n}\n\ninterface AssetCapability {\n supported: boolean;\n reason?: string;\n configFile?: string;\n installDir?: string;\n writeStrategy?: WriteStrategy;\n baseRulesFile?: string;\n}\n```\n\n资料来源：[src/hosts/types.ts]()\n\n### Write Strategies\n\nThe system supports different write strategies for different asset types and hosts:\n\n| Strategy | Description | Used By |\n|----------|-------------|---------|\n| `append-with-marker` | Appends content wrapped in HTML comment markers (``) | Cursor, Claude Code |\n| `create-file-in-dir` | Creates standalone `.md` file in rules directory | Windsurf, Roo Code, Kilo Code |\n| `json-merge` | Shallow JSON merge for MCP config | Most hosts |\n| `toml-merge` | TOML merge for Codex/Vibe | codex, vibe |\n\n资料来源：[src/hosts/types.ts]()\n资料来源：[src/assets/prompt.ts]()\n资料来源：[src/assets/mcp.ts]()\n\n## Asset Handler Layer\n\nEach asset type has a dedicated handler that implements the `AssetHandler` interface:\n\n```mermaid\ngraph TD\n H[\"InstallJob\"] --> MCP[\"MCP Handler\"]\n H --> SKILL[\"Skill Handler\"]\n H --> PROMPT[\"Prompt Handler\"]\n H --> COMMAND[\"Command Handler\"]\n H --> SUBAGENT[\"Sub-agent Handler\"]\n\n MCP --> MCP_WRITE[\"Atomic JSON/TOML Write\"]\n SKILL --> SKILL_COPY[\"Directory Copy + Validation\"]\n PROMPT --> PROMPT_STRAT[\"Marker Append or Create File\"]\n COMMAND --> COMMAND_WRITE[\"YAML Frontmatter Parse\"]\n SUBAGENT --> SUB_WRITE[\"Host Specialization Processing\"]\n```\n\n### MCP Handler\n\nThe MCP handler supports both JSON and TOML formats with automatic format detection:\n\n- **JSON format A (inner config)**: Single server without wrapper\n- **JSON format B (full config)**: With `mcpServers` wrapper\n- **TOML format**: Auto-detected by `.toml` extension\n\nKey behavior:\n- Shallow merge for existing configurations\n- Atomic write using temp file + rename pattern\n- TOML auto-dispatches for Codex and Vibe hosts\n\n资料来源：[src/assets/mcp.ts]()\n资料来源：[README.md:50-80]()\n\n### Skill Handler\n\nThe Skill handler installs entire skill directories:\n\n- Recursively copies directory contents to host's skills directory\n- Validates `SKILL.md` exists within the source directory\n- Asset name becomes the subdirectory name under skills root\n- **Note**: Does not support inline sources, HTTP URLs, or git subpaths\n\n资料来源：[src/assets/skill.ts]()\n资料来源：[src/installer.ts:50-100]()\n\n### Prompt Handler\n\nThe Prompt handler supports two write strategies:\n\n1. **Append Mode** (Cursor, Claude Code): Content is wrapped in idempotent HTML markers\n ```html\n \n # Code Review Rules\n ...\n \n ```\n\n2. **Standalone File Mode** (Windsurf, Roo Code): Creates `.md` in rules directory\n\n资料来源：[src/assets/prompt.ts]()\n资料来源：[README.md:80-120]()\n\n### Sub-agent Handler\n\nThe Sub-agent handler supports host specialization using YAML frontmatter:\n\n```yaml\n---\nname: playwright-tester\ndescription: A playwright testing agent.\nagent-add/cursor/model: fast\nagent-add/claude-code/model: haiku\n---\n\n# Playwright Test Agent\n```\n\nDuring installation:\n1. Matching `agent-add//*` values are promoted to top-level\n2. All `agent-add/*` prefixed keys are removed\n3. Resulting frontmatter is host-specific\n\n资料来源：[src/assets/sub-agent.ts]()\n资料来源：[README.md:140-180]()\n\n## Source Resolution System\n\nThe source resolution system handles multiple source types and normalizes them to local filesystem paths:\n\n```mermaid\ngraph TD\n S[\"Source String\"] --> TYPE{\"Source Type Detection\"}\n \n TYPE -->|Starts with `{` | INLINE_JSON[\"Inline JSON\"]\n TYPE -->|Contains `\\n` | INLINE_MD[\"Inline Markdown\"]\n TYPE -->|Starts with `http` | HTTP[\"HTTP/HTTPS URL\"]\n TYPE -->|Contains `://` or `.git` | GIT[\"Git URL\"]\n TYPE -->|Otherwise | LOCAL[\"Local Path\"]\n \n INLINE_JSON --> TEMP[\"Write to Temp File\"]\n INLINE_MD --> TEMP\n HTTP --> DOWNLOAD[\"Download via fetch\"]\n GIT --> CLONE[\"Git Clone/Shallow Clone\"]\n LOCAL --> RESOLVE[\"path.resolve()\"]\n \n DOWNLOAD --> CACHE[\"Cache in Temp Dir\"]\n CLONE --> CACHE\n TEMP --> CACHE\n RESOLVE --> CACHE\n \n CACHE --> RESULT[\"ResolvedSource\"]\n```\n\n### Supported Source Types\n\n| Source Type | Detection | Processing |\n|-------------|-----------|------------|\n| Inline JSON | Starts with `{` | Parse, validate, write to temp |\n| Inline Markdown | Contains `\\n` | Extract name from `# Heading`, write to temp |\n| HTTP File | `https://` or `http://` | Download via fetch, save to temp |\n| Git URL | Contains `://` or `.git` | Shallow clone to temp directory |\n| Local Path | Default | Resolve relative to cwd |\n\n### Name Inference Rules\n\nAsset names are inferred from sources using these rules:\n\n| Source Pattern | Inference Rule | Example |\n|----------------|----------------|---------|\n| Git URL + `#path` | Last segment after `#`, kebab-case | `...git#skills/pdf` → `pdf` |\n| Git URL without `#` | Repo name, strip `.git` | `...playwright.git` → `playwright` |\n| HTTP URL | Filename, strip extension | `./mcps/playwright.json` → `playwright` |\n| Local path | Filename, strip extension | `playwright.json` → `playwright` |\n| Inline JSON | Top-level key name | `{\"playwright\":{...}}` → `playwright` |\n| Inline Markdown | First `# Heading`, kebab-case | `# Code Review` → `code-review` |\n\n资料来源：[src/source/infer-name.ts:1-50]()\n\n## CLI Layer\n\n### Entry Point\n\n```typescript\nimport { createProgram } from './cli.js';\n\nconst program = createProgram();\nprogram.parseAsync(process.argv).catch((err: Error) => {\n process.stderr.write(`agent-add error: ${err.message}\\n`);\n process.exit(2);\n});\n```\n\n资料来源：[src/index.ts:1-7]()\n\n### CLI Options\n\n| Flag | Type | Description | Repeatable |\n|------|------|-------------|------------|\n| `--pack ` | string | Install Agent Pack manifest | Yes |\n| `--mcp ` | string | Install MCP config | Yes |\n| `--skill ` | string | Install Skill directory | Yes |\n| `--prompt ` | string | Install Prompt file | Yes |\n| `--command ` | string | Install Command file | Yes |\n| `--sub-agent ` | string | Install Sub-agent file | Yes |\n| `--host ` | string | Target host ID | No |\n| `-V, --version` | - | Show version | - |\n| `-h, --help` | - | Show help | - |\n\n资料来源：[src/cli.ts]()\n资料来源：[README.md:200-220]()\n\n### TTY Detection\n\nNon-TTY environments (CI/CD) require explicit `--host` specification:\n\n```typescript\nif (!process.stdout.isTTY && !cliInput.host) {\n process.stderr.write(\n `agent-add error: Non-TTY environment detected. ` +\n `Specify --host explicitly. Valid hosts: ${validIds.join(', ')}\\n`,\n );\n process.exit(2);\n}\n```\n\n资料来源：[src/cli.ts]()\n资料来源：[README.md:30-35]()\n\n## Validation Layer\n\nThe validation layer performs asset-specific validation before installation:\n\n| Asset Type | Validations |\n|------------|-------------|\n| MCP | File must exist, extension must be `.json` |\n| Skill | Must be directory (not HTTP/inline), must contain `SKILL.md` |\n| Prompt | None (Markdown has no required structure) |\n| Command | None (Markdown with optional YAML frontmatter) |\n| Sub-agent | None (Markdown with optional YAML frontmatter) |\n\n资料来源：[src/installer.ts:100-150]()\n\n### Explicit Flag Capability Check\n\nWhen a user explicitly specifies an asset type flag (e.g., `--mcp`), the system checks if the target host supports that asset type. If `supported: false`, the installation exits with code 2 and provides a helpful error message with documentation link.\n\n**Exception**: Assets from `--pack` manifests skip this check, as pack authors may include host-specific assets.\n\n资料来源：[src/installer.ts:30-60]()\n\n## Error Handling\n\n| Error Type | Exit Code | Action |\n|------------|-----------|--------|\n| Capability not supported | 2 | Exit with error message + README link |\n| Validation failure | 2 | Exit with source path |\n| No matching files in directory | 2 | Exit with source path |\n| Inline source for Skill | 2 | Exit with reason |\n| Install conflict | 1 | Exit 1 (not 2, partial success) |\n| Install error | 1 | Exit 1 (not 2, partial success) |\n\n资料来源：[src/installer.ts:150-200]()\n资料来源：[src/cli.ts:60-80]()\n\n## Testing Architecture\n\nThe project uses a three-layer test strategy:\n\n```mermaid\ngraph TD\n T[\"npm test\"] --> U[\"Unit Tests\"]\n T --> I[\"Integration Tests\"]\n T --> CONTRACT[\"Contract Tests\"]\n \n U --> V[\"vitest unit/\"]\n I --> VITEST_INT[\"vitest integration/\"]\n CONTRACT --> BLACKBOX[\"CLI black-box tests\"]\n \n SCENARIO[\"Gherkin Scenarios\"] -.-> MANUAL[\"AI Agent Manual Trigger\"]\n SCENARIO --> FEATURES[\"tests/features/\"]\n FEATURES --> ISOLATED[\"Isolated Temp Dir Execution\"]\n```\n\n| Test Layer | Command | Purpose |\n|------------|---------|---------|\n| Unit | `npm test` | Component-level testing with mocks |\n| Integration | `npm run test:integration` | Full flow testing with filesystem |\n| Contract | `npm run test:contract` | CLI black-box behavior verification |\n| Scenario | `/scenario-exec tests/features/` | Gherkin feature files, AI-executed |\n\n资料来源：[README.md:15-30]()\n资料来源：[README.md:230-250]()\n\n## Environment Variables\n\n| Variable | Purpose |\n|----------|---------|\n| `AGENT_ADD_HOME` | Overrides `os.homedir()` for test isolation, redirects Claude Desktop/Codex host install paths to temp directories |\n\n资料来源：[system-prompt.md:10-12]()\n资料来源：[src/assets/mcp.ts]()\n\n## Key Design Decisions\n\n### Atomic Writes\n\nMCP configuration uses a temp file + rename pattern to ensure atomicity:\n\n```typescript\n// 1. Write to temp file\n// 2. Rename to target (atomic on POSIX)\n// 3. On failure, temp file is orphaned (not a partial write)\n```\n\n资料来源：[src/assets/mcp.ts]()\n\n### Idempotent Marker Blocks\n\nPrompt append mode uses HTML comment markers for safe re-installation:\n\n```html\n\n# Code Review Rules\n...\n\n```\n\nIf markers exist, content between them is replaced; otherwise, markers are appended.\n\n资料来源：[src/assets/prompt.ts]()\n资料来源：[README.md:100-110]()\n\n### TOML Auto-Dispatch\n\nThe MCP handler detects `.toml` extension and routes to TOML-specific merge logic:\n\n```typescript\nif (resolved.localPath.endsWith('.toml')) {\n // Use smol-toml for read/write\n} else {\n // Use JSON shallow merge\n}\n```\n\n资料来源：[src/assets/mcp.ts]()\n资料来源：[package.json:20-25]()\n\n## Technology Stack\n\n| Component | Technology | Version |\n|-----------|------------|---------|\n| Language | TypeScript | 5.x (strict mode) |\n| Runtime | Node.js | 18+ |\n| Build | tsup (esbuild) | 8.x |\n| Testing | vitest | 4.x |\n| CLI | commander | 14.x |\n| TOML | smol-toml | 1.x |\n| Config validation | zod | 4.x |\n| YAML parsing | yaml | 2.x |\n| Interactive prompts | @inquirer/select | 5.x |\n\n资料来源：[package.json:1-50]()\n\n---\n\n\n\n## Host Integration\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [Asset Types](#asset-types)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n- [src/hosts/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/index.ts)\n- [src/hosts/cursor.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/cursor.ts)\n- [src/hosts/claude-code.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/claude-code.ts)\n- [src/hosts/windsurf.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/windsurf.ts)\n- [src/hosts/github-copilot.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/github-copilot.ts)\n- [src/hosts/README.md](https://github.com/pea3nut/agent-add/blob/main/src/hosts/README.md)\n
\n\n# Host Integration\n\n## Overview\n\nThe Host Integration layer is the core abstraction in `agent-add` that enables cross-host compatibility. It provides a unified interface for installing assets (MCP servers, Skills, Prompts, Commands, and Sub-agents) across 18 different AI agent hosts including Cursor, Claude Code, Windsurf, and GitHub Copilot.\n\nEach supported host has a dedicated adapter class that encapsulates:\n- Host detection mechanisms\n- Asset installation paths\n- Configuration file formats\n- Write strategies for different asset types\n- Platform-specific considerations\n\nThis architecture allows `agent-add` to abstract away the complexities of each host's unique file system structure and configuration format, presenting a single CLI interface to end users.\n\n## Architecture\n\n### System Architecture\n\n```mermaid\ngraph TD\n subgraph \"CLI Layer\"\n CLI[CLI Input Parsing]\n end\n \n subgraph \"Core Engine\"\n INST[Installer]\n VAL[Validator]\n end\n \n subgraph \"Host Adapter Layer\"\n REG[Host Registry]\n CA[Cursor Adapter]\n CCA[Claude Code Adapter]\n WA[Windsurf Adapter]\n OHA[Other Host Adapters]\n end\n \n subgraph \"Asset Handlers\"\n MCP[MCP Handler]\n SKILL[Skill Handler]\n PROMPT[Prompt Handler]\n CMD[Command Handler]\n SUB[Sub-agent Handler]\n end\n \n CLI --> INST\n INST --> VAL\n VAL --> REG\n REG --> CA\n REG --> CCA\n REG --> WA\n REG --> OHA\n \n CA --> MCP\n CA --> SKILL\n CA --> PROMPT\n CA --> CMD\n CA --> SUB\n \n CCA --> MCP\n CCA --> SKILL\n CCA --> PROMPT\n CCA --> CMD\n CCA --> SUB\n```\n\n### Data Flow\n\n```mermaid\nsequenceDiagram\n participant CLI as CLI Input\n participant INST as Installer\n participant HOST as Host Adapter\n participant HAND as Asset Handler\n participant FS as File System\n \n CLI->>INST: Parse flags + --pack manifest\n INST->>INST: Capability check\n INST->>INST: Source resolution\n INST->>INST: Asset validation\n INST->>HOST: Get capabilities for asset type\n HOST-->>INST: Return AssetCapability\n INST->>INST: Create InstallJob[]\n INST->>HAND: Execute install job\n HAND->>FS: Write with strategy\n FS-->>HAND: Confirm write\n HAND-->>INST: InstallResult\n INST->>INST: Format summary output\n```\n\n## HostAdapter Interface\n\nThe `HostAdapter` interface defines the contract all host implementations must follow.\n\n### Interface Definition\n\n```typescript\n// src/hosts/types.ts\nexport interface HostAdapter {\n readonly id: string;\n readonly displayName: string;\n readonly docs: string;\n readonly detection: {\n paths: string[];\n };\n readonly assets: Record;\n}\n```\n\n### Property Specification\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `id` | `string` | Unique identifier for the host (e.g., `\"cursor\"`, `\"claude-code\"`) |\n| `displayName` | `string` | Human-readable name (e.g., `\"Claude Code\"`) |\n| `docs` | `string` | URL to official documentation |\n| `detection.paths` | `string[]` | Directory paths that indicate this host is active |\n| `assets` | `Record` | Capability definitions for each asset type |\n\n资料来源：[src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n\n## AssetCapability Types\n\nEach asset type has its own capability configuration within the host adapter.\n\n### AssetType Enum\n\n```typescript\n// src/hosts/types.ts\nexport type AssetType = 'mcp' | 'skill' | 'prompt' | 'command' | 'subAgent';\n```\n\n### Capability Structure\n\n```typescript\n// src/hosts/types.ts\nexport interface AssetCapability {\n supported: boolean;\n reason?: string; // Required when supported=false\n configFile?: ConfigFileSpec; // For MCP\n configKey?: string; // For MCP\n targetFile?: string; // For Prompt (append mode)\n installDir?: string; // For Skill/Command/Sub-agent\n entryFile?: string; // For Skill\n fileExtension?: string; // For Command/Sub-agent\n writeStrategy?: WriteStrategy; // Strategy for writing files\n}\n\nexport interface ConfigFileSpec {\n darwin?: string;\n linux?: string;\n win32?: string;\n}\n```\n\n### Supported Asset Types\n\n| Asset Type | Purpose | Install Method |\n|------------|---------|----------------|\n| `mcp` | Model Context Protocol servers | Modify config file (JSON or TOML) |\n| `skill` | Reusable agent skill directories | Copy directory recursively |\n| `prompt` | System prompts / rule files | Append or create standalone file |\n| `command` | Custom slash commands | Copy markdown file |\n| `subAgent` | Sub-agent configurations | Copy configuration file |\n\n资料来源：[src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n\n## Write Strategies\n\nThe `writeStrategy` property determines how assets are installed to the host's filesystem.\n\n### Strategy Types\n\n| Strategy | Description | Supported Asset Types |\n|----------|-------------|----------------------|\n| `inject-json-key` | Inject configuration into existing JSON/TOML file | MCP, Prompt (append mode) |\n| `append-with-marker` | Append content wrapped in HTML comment markers | Prompt |\n| `copy-file` | Copy file directly to target directory | Skill, Command, Sub-agent |\n| `create-file-in-dir` | Create file at `installDir/.md` | Prompt (standalone mode) |\n\n### Marker Block Format\n\nWhen using `append-with-marker`, content is wrapped in HTML comment markers for idempotent updates:\n\n```html\n\n# Code Review Rules\n\nAlways review for security issues first.\n\n```\n\n### JSON Injection\n\nThe `inject-json-key` strategy performs shallow merging of MCP server configurations:\n\n```typescript\n// Before\n{ \"mcpServers\": { \"existing-server\": {} } }\n\n// After (injecting playwright)\n{ \"mcpServers\": { \"existing-server\": {}, \"playwright\": { \"command\": \"npx\", \"args\": [\"@playwright/mcp@latest\"] } } }\n```\n\n## Host Registry\n\nThe host registry maps host IDs to their adapter instances.\n\n```mermaid\nclassDiagram\n class HostRegistry {\n +hostRegistry: Map~string, HostAdapter~\n +getHost(id: string): HostAdapter\n +getValidHostIds(): string[]\n }\n \n class HostAdapter {\n <>\n +id: string\n +displayName: string\n +docs: string\n +assets: Record~AssetType, AssetCapability~\n }\n \n HostRegistry --> HostAdapter\n```\n\n### Registry Implementation\n\n```typescript\n// src/hosts/index.ts\nconst hostRegistry = new Map([\n ['cursor', new CursorAdapter()],\n ['claude-code', new ClaudeCodeAdapter()],\n ['windsurf', new WindsurfAdapter()],\n ['github-copilot', new GitHubCopilotAdapter()],\n // ... 14 more hosts\n]);\n```\n\n### Currently Supported Hosts\n\nThe system supports 18 hosts across multiple platforms:\n\n| Host ID | Display Name | Config Format |\n|---------|--------------|---------------|\n| `cursor` | Cursor AI | JSON |\n| `claude-code` | Claude Code | JSON |\n| `claude-desktop` | Claude Desktop | JSON |\n| `windsurf` | Windsurf | TOML |\n| `github-copilot` | GitHub Copilot | JSON |\n| `gemini` | Google Gemini | JSON |\n| `roo-code` | Roo Code | JSON |\n| `kilo-code` | Kilo Code | JSON |\n| `qwen-code` | Qwen Code | JSON |\n| `opencode` | OpenCode | JSON |\n| `augment` | Augment Code | JSON |\n| `kiro` | Kiro | JSON |\n| `tabnine` | Tabnine | JSON |\n| `kimi` | Kimi | JSON |\n| `trae` | Trae | JSON |\n| `openclaw` | OpenClaw | JSON |\n| `codex` | Codex CLI | TOML |\n| `vibe` | Vibe | TOML |\n\n## Example Host Adapters\n\n### Claude Code Adapter\n\n```typescript\n// src/hosts/claude-code.ts\nexport class ClaudeCodeAdapter implements HostAdapter {\n readonly id = 'claude-code';\n readonly displayName = 'Claude Code';\n readonly docs = 'https://code.claude.com/docs/en';\n readonly detection = {\n paths: ['.claude/'],\n };\n readonly assets: Record = {\n mcp: {\n supported: true,\n configFile: '.mcp.json',\n configKey: 'mcpServers',\n writeStrategy: 'inject-json-key',\n },\n skill: {\n supported: true,\n installDir: '.claude/skills/',\n entryFile: 'SKILL.md',\n writeStrategy: 'copy-file',\n },\n prompt: {\n supported: true,\n targetFile: 'CLAUDE.md',\n writeStrategy: 'append-with-marker',\n },\n command: {\n supported: true,\n installDir: '.claude/commands/',\n fileExtension: '.md',\n writeStrategy: 'copy-file',\n },\n subAgent: {\n supported: true,\n installDir: '.claude/agents/',\n fileExtension: '.md',\n writeStrategy: 'copy-file',\n },\n };\n}\n```\n\n资料来源：[src/hosts/claude-code.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/claude-code.ts)\n\n### Cursor Adapter\n\n```typescript\n// src/hosts/cursor.ts\nexport class CursorAdapter implements HostAdapter {\n readonly id = 'cursor';\n readonly displayName = 'Cursor';\n readonly docs = 'https://www.cursor.com/docs';\n readonly detection = {\n paths: ['.cursor/'],\n };\n readonly assets: Record = {\n mcp: {\n supported: true,\n configFile: {\n darwin: '~/Library/Application Support/Cursor/config/mcp.json',\n linux: '~/.config/Cursor/config/mcp.json',\n win32: '%APPDATA%\\\\Cursor\\\\config\\\\mcp.json',\n },\n configKey: 'mcpServers',\n writeStrategy: 'inject-json-key',\n },\n skill: {\n supported: true,\n installDir: '.cursor/skills/',\n entryFile: 'SKILL.md',\n writeStrategy: 'copy-file',\n },\n prompt: {\n supported: true,\n targetFile: 'AGENTS.md',\n writeStrategy: 'append-with-marker',\n },\n command: {\n supported: true,\n installDir: '.cursor/commands/',\n fileExtension: '.md',\n writeStrategy: 'copy-file',\n },\n subAgent: {\n supported: true,\n installDir: '.cursor/agents/',\n fileExtension: '.md',\n writeStrategy: 'copy-file',\n },\n };\n}\n```\n\n资料来源：[src/hosts/cursor.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/cursor.ts)\n\n### Unsupported Assets\n\nHosts that don't support certain asset types use the `NOT_SUPPORTED` helper:\n\n```typescript\n// src/hosts/github-copilot.ts\nconst NOT_SUPPORTED = (reason: string): AssetCapability => ({\n supported: false,\n reason,\n});\n\nexport class GitHubCopilotAdapter implements HostAdapter {\n // ...\n readonly assets: Record = {\n mcp: {\n supported: true,\n configFile: '.github/copilot-instruqt.md',\n writeStrategy: 'inject-json-key',\n },\n command: NOT_SUPPORTED('GitHub Copilot does not support custom slash commands via files.'),\n // ...\n };\n}\n```\n\n## Adding a New Host\n\n### Contribution Workflow\n\n```mermaid\ngraph LR\n A[Create Adapter] --> B[Register in index.ts]\n B --> C[Update README.md]\n C --> D[Add Unit Tests]\n D --> E[Verify with scenario tests]\n```\n\n### Step 1: Create the Adapter File\n\nCreate `src/hosts/.ts` with a class implementing `HostAdapter`:\n\n```typescript\n// src/hosts/new-host.ts\nimport type { HostAdapter, AssetCapability, AssetType } from './types.js';\n\nconst NOT_SUPPORTED = (reason: string): AssetCapability => ({\n supported: false,\n reason,\n});\n\nexport class NewHostAdapter implements HostAdapter {\n readonly id = 'new-host';\n readonly displayName = 'New Host';\n readonly docs = 'https://docs.newhost.com';\n readonly detection = {\n paths: ['.newhost/'],\n };\n readonly assets: Record = {\n mcp: {\n supported: true,\n configFile: '.newhost/mcp.json',\n configKey: 'mcpServers',\n writeStrategy: 'inject-json-key',\n },\n prompt: NOT_SUPPORTED('New Host does not support prompts.'),\n skill: NOT_SUPPORTED('New Host does not support skills.'),\n command: NOT_SUPPORTED('New Host does not support commands.'),\n subAgent: NOT_SUPPORTED('New Host does not support sub-agents.'),\n };\n}\n```\n\n### Step 2: Register the Adapter\n\nAdd to the registry in `src/hosts/index.ts`:\n\n```typescript\nimport { NewHostAdapter } from './new-host.js';\n\nconst hostRegistry = new Map([\n // ... existing entries\n ['new-host', new NewHostAdapter()],\n]);\n```\n\n### Step 3: Update Documentation\n\nAdd a row to the capability matrix in `src/hosts/README.md`:\n\n| Host | MCP | Prompt | Skill | Command | Sub-agent |\n|------|-----|--------|-------|---------|-----------|\n| New Host | ✅ `.newhost/mcp.json` | ❌ | ❌ | ❌ | ❌ |\n\n### Step 4: Add Unit Tests\n\nCreate `tests/unit/hosts/new-host.test.ts`:\n\n```typescript\nimport { describe, it, expect } from 'vitest';\nimport { NewHostAdapter } from '../../../src/hosts/new-host.js';\n\ndescribe('NewHostAdapter', () => {\n const adapter = new NewHostAdapter();\n\n it('should have correct id', () => {\n expect(adapter.id).toBe('new-host');\n });\n\n it('should have correct displayName', () => {\n expect(adapter.displayName).toBe('New Host');\n });\n\n it('should support MCP', () => {\n expect(adapter.assets.mcp.supported).toBe(true);\n expect(adapter.assets.mcp.configFile).toBe('.newhost/mcp.json');\n });\n});\n```\n\n## Key Design Decisions\n\n### Atomic JSON Writes\n\nMCP configurations use a temp file + rename pattern to ensure atomicity:\n\n```mermaid\ngraph TD\n A[New Config] --> B[Write to temp file]\n B --> C[Rename temp to target]\n C --> D{Success?}\n D -->|Yes| E[Complete]\n D -->|No| F[Rollback temp file]\n```\n\n### Platform-Specific Paths\n\nMCP config files use platform-specific paths:\n\n```typescript\nconfigFile: {\n darwin: '~/Library/Application Support/Cursor/config/mcp.json',\n linux: '~/.config/Cursor/config/mcp.json',\n win32: '%APPDATA%\\\\Cursor\\\\config\\\\mcp.json',\n}\n```\n\n### TOML vs JSON Auto-Detection\n\nThe system auto-detects TOML format based on file extension:\n\n```typescript\n// src/assets/mcp.ts\nif (path.extname(configFile) === '.toml') {\n // Use smol-toml for read/write\n} else {\n // Use standard JSON\n}\n```\n\n### Explicit Flag Capability Checking\n\nThe installer validates that explicitly requested asset types are supported before attempting installation:\n\n```typescript\n// src/installer.ts\nif (!capability.supported) {\n skippedResults.push({\n job: { assetType, assetName, resolvedSource, host },\n status: 'skipped',\n reason: capability.reason,\n });\n}\n```\n\n## Summary\n\nThe Host Integration system provides a scalable architecture for supporting multiple AI agent hosts through a consistent adapter pattern. Key benefits include:\n\n- **Single Source of Truth**: All host capabilities defined in adapter classes and documented in `src/hosts/README.md`\n- **Extensibility**: New hosts can be added by implementing the `HostAdapter` interface\n- **Type Safety**: TypeScript strict mode ensures adapter implementations match specifications\n- **Testability**: Each adapter has corresponding unit tests verifying exact field values\n- **Platform Abstraction**: Platform-specific paths handled transparently\n- **Format Flexibility**: Supports both JSON and TOML configuration formats\n\n---\n\n\n\n## Source Resolution\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [Asset Types](#asset-types)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/source/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/index.ts)\n- [src/source/git.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/git.ts)\n- [src/source/http-file.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/http-file.ts)\n- [src/source/local.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/local.ts)\n- [src/source/inline.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/inline.ts)\n- [src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n
\n\n# Source Resolution\n\n## Overview\n\nSource Resolution is the core subsystem responsible for transforming user-provided source strings into concrete filesystem paths that the installer can process. It acts as an abstraction layer that normalizes diverse input formats—including local paths, Git URLs, HTTP URLs, and inline content—into a unified `ResolvedSource` data structure.\n\nThe resolution pipeline accepts asset sources in multiple formats and outputs temporary directories containing the asset content, ready for downstream handlers to install into host-specific locations. This design decouples asset specification from asset installation, enabling users to reference assets through various convenient syntaxes without understanding host-specific installation mechanics.\n\n资料来源：[src/source/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/index.ts)\n\n## Architecture\n\nThe Source Resolution module is located in `src/source/` and comprises six specialized modules:\n\n| Module | Purpose |\n|--------|---------|\n| `index.ts` | Main entry point; orchestrates resolution pipeline |\n| `git.ts` | Resolves Git URLs (SSH and HTTPS) with sparse checkout support |\n| `http-file.ts` | Downloads assets from HTTP/HTTPS URLs |\n| `local.ts` | Resolves local filesystem paths |\n| `inline.ts` | Handles inline JSON and Markdown content |\n| `infer-name.ts` | Extracts asset names from source strings |\n\n资料来源：[src/source/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/index.ts)\n\n## Resolution Pipeline\n\nThe resolution process follows a sequential pipeline that attempts each resolver until one successfully produces a `ResolvedSource`:\n\n```mermaid\ngraph TD\n A[User Source String] --> B{Starts with ./ or / or ~?}\n B -->|Yes| C[Local Resolver]\n B -->|No| D{Starts with http:// or https://?}\n D -->|Yes| E[HTTP Resolver]\n D -->|No| F{Starts with git@ or ends with .git?}\n F -->|Yes| G[Git Resolver]\n F -->|No| H{Starts with {?}\n H -->|Yes| I[Inline JSON Resolver]\n H -->|No| J{Contains \\n?}\n J -->|Yes| K[Inline Markdown Resolver]\n J -->|No| L[Error: Unknown source format]\n \n C --> M[ResolvedSource]\n E --> M\n G --> M\n I --> M\n K --> M\n```\n\nEach resolver returns a `ResolvedSource` object containing the original source, resolved local path, and content type:\n\n```typescript\ninterface ResolvedSource {\n originalSource: string; // The user's original input\n localPath: string; // Absolute path to resolved content\n type: SourceType; // 'local' | 'git' | 'http-file' | 'inline-json' | 'inline-md'\n tempDir?: string; // Temp directory if content was downloaded/generated\n}\n```\n\n资料来源：[src/source/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/index.ts)\n\n## Source Types\n\n### Local Files and Directories\n\nThe local resolver handles filesystem paths beginning with `./`, `../`, `/`, or `~`. It performs the following operations:\n\n1. **Path normalization**: Expands `~` to home directory and resolves relative paths to absolute paths\n2. **Existence verification**: Confirms the path exists on the filesystem\n3. **Directory detection**: For directory sources, scans for matching asset files\n\n```typescript\n// Supported path formats\n'./mcps/playwright.json' // Relative path\n'/absolute/path/to/file' // Absolute path\n'~/dotfiles/mcp.json' // Home directory expansion\n'../shared/rules.md' // Parent directory relative path\n```\n\n资料来源：[src/source/local.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/local.ts)\n\n### Git URLs\n\nThe Git resolver supports both SSH and HTTPS Git URLs with optional path fragment syntax for sparse checkout:\n\n| Format | Example | Behavior |\n|--------|---------|----------|\n| SSH | `git@github.com:user/repo.git#path/to/asset` | Clones via SSH, extracts specified path |\n| HTTPS | `https://github.com/user/repo.git#path/to/asset` | Clones via HTTPS, extracts specified path |\n| Without fragment | `git@github.com:user/repo.git` | Clones entire repository |\n\n**Sparse Checkout Behavior**\n\nWhen a `#path` fragment is specified, the resolver performs a sparse checkout, downloading only the specified directory or file. This is particularly useful for monorepos where only specific assets are needed.\n\n```typescript\n// Example: Extract only the playwright skill from a monorepo\ngit@github.com:anthropics/skills.git#skills/playwright\n```\n\nThe resolver supports both formats:\n- **Directory path**: Extracts all files within the directory\n- **File path**: Extracts a single file\n\n资料来源：[src/source/git.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/git.ts)\n\n### HTTP/HTTPS URLs\n\nThe HTTP resolver downloads files directly from web URLs. It supports:\n\n- Direct file downloads from any HTTP/HTTPS endpoint\n- Automatic filename extraction from URL path\n- Integrity verification of downloaded content\n\n**Supported Asset Types for HTTP:**\n\n| Asset Type | HTTP Support |\n|------------|--------------|\n| MCP | ✅ Yes |\n| Skill | ❌ No (validation rejects) |\n| Prompt | ✅ Yes |\n| Command | ✅ Yes |\n| Sub-agent | ✅ Yes |\n\n资料来源：[src/source/http-file.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/http-file.ts)\n\n### Inline Content\n\nInline sources allow embedding asset content directly in the command line, eliminating the need for separate files or remote URLs. The system auto-detects content type based on format.\n\n#### Inline JSON (MCP Only)\n\nSources beginning with `{` are treated as inline JSON. The format supports MCP configuration in two structures:\n\n**Format A: Inner config (single server)**\n```json\n{\"command\":\"npx\",\"args\":[\"@playwright/mcp@latest\"]}\n```\nAsset name is inferred from the MCP config filename.\n\n**Format B: Wrapped config with `mcpServers`**\n```json\n{\"mcpServers\":{\"playwright\":{\"command\":\"npx\",\"args\":[\"@playwright/mcp@latest\"]}}}\n```\nThe wrapper is automatically unwrapped and the inner server name becomes the asset name.\n\n```bash\n# Example command\nnpx -y agent-add --host cursor \\\n --mcp '{\"playwright\":{\"command\":\"npx\",\"args\":[\"@playwright/mcp\"]}}'\n```\n\n资料来源：[src/source/inline.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/inline.ts)\n\n#### Inline Markdown (Prompt/Command/Sub-agent)\n\nSources containing `\\n` (newline) are treated as inline Markdown. This applies to:\n\n- **Prompt files**: System prompts and rule files\n- **Command files**: Slash commands\n- **Sub-agent files**: Agent configurations\n\nThe asset name is inferred from the first `# Heading` in the content, converted to kebab-case:\n\n```markdown\n# Code Review Rules\n\nAlways review for security first.\n```\n→ Asset name: `code-review-rules`\n\n```bash\n# Example command\nnpx -y agent-add --host claude-code \\\n --prompt $'# Code Review Rules\\n\\nAlways review for security issues first.'\n```\n\n资料来源：[src/source/inline.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/inline.ts)\n资料来源：[src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n\n## Asset Name Inference\n\nThe `infer-name.ts` module extracts consistent asset names from diverse source formats. This ensures uniform naming regardless of how the asset is referenced.\n\n### Name Inference Rules\n\n| Source Type | Rule | Example Input | Inferred Name |\n|-------------|------|---------------|---------------|\n| Inline JSON | Extract top-level key | `{\"playwright\":{...}}` | `playwright` |\n| Inline Markdown | First `# Heading` → kebab-case | `# Code Review` | `code-review` |\n| Git URL + `#path` | Last segment, strip extension | `...git#skills/pdf` | `pdf` |\n| Git URL without `#` | Repository name, strip `.git` | `...playwright.git` | `playwright` |\n| Local path / HTTP | Filename, strip extension | `./mcps/playwright.json` | `playwright` |\n\n### Inline JSON Parsing\n\nWhen processing inline JSON sources:\n\n1. Parse the JSON string into an object\n2. If the object has an `mcpServers` wrapper, unwrap it\n3. Extract the top-level key as the asset name\n4. If multiple keys exist, throw an error (inline JSON supports single MCP only)\n\n```typescript\n// Single server (inner format) - name from source metadata\n{\"command\":\"npx\",\"args\":[\"@playwright/mcp\"]} // ❌ No name, requires filename inference\n\n// Single server (wrapped format) - name from key\n{\"mcpServers\":{\"playwright\":{...}}} // ✅ Name is \"playwright\"\n```\n\n资料来源：[src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n\n## Temporary File Management\n\nSource Resolution manages temporary directories to ensure clean operation:\n\n1. **Downloaded content**: HTTP and Git downloads are stored in temporary directories\n2. **Inline content**: Generated files (from inline JSON/Markdown) are written to temp files\n3. **Cleanup**: Temp directories are cleaned up after installation completes\n\nThe `AGENT_ADD_HOME` environment variable can override the default temp directory location, useful for test isolation:\n\n```bash\nAGENT_ADD_HOME=/tmp/test-home npx -y agent-add --host cursor --mcp '{\"test\":{...}}'\n```\n\n资料来源：[src/source/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/index.ts)\n\n## Integration with Installation Pipeline\n\nSource Resolution integrates into the broader installation workflow as follows:\n\n```mermaid\ngraph LR\n A[CLI Input] --> B[Source Resolution]\n B --> C[ResolvedSource]\n C --> D[Validation]\n D --> E[InstallJob Creation]\n E --> F[Asset Handler Execution]\n F --> G[InstallResult]\n \n B -.->|Inline sources| H[Temp File Generation]\n B -.->|Git/HTTP sources| I[Download to Temp]\n```\n\nAfter resolution, the `installer.ts` module performs validation based on asset type:\n\n- **MCP**: File must exist and have `.json` extension\n- **Skill**: Must be a directory containing `SKILL.md`\n- **Prompt/Command/Sub-agent**: No additional validation at this stage\n\n```typescript\n// From src/installer.ts - validation logic\nif (assetType === 'skill') {\n if (resolved.type === 'http-file' || resolved.type === 'inline-json' || resolved.type === 'inline-md') {\n return 'Skill assets must point to directory sources (local path or Git URL)';\n }\n const skillMdPath = path.join(resolved.localPath, 'SKILL.md');\n // ...\n}\n```\n\n资料来源：[src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n\n## Error Handling\n\nThe resolution system provides specific error messages for common failures:\n\n| Error Condition | Message |\n|-----------------|---------|\n| Inline JSON parse failure | `内联 JSON 解析失败。格式应为 {\"\":{...}}` |\n| Inline JSON not object | `内联 JSON 必须为对象类型` |\n| Multiple keys in inline JSON | Error listing unsupported multiple keys |\n| Directory empty (skill) | `No matching files found in directory` |\n| SKILL.md missing | `Skill 目录内缺少 SKILL.md 文件` |\n| MCP file missing | `MCP 来源文件不存在` |\n| MCP wrong extension | `MCP 来源文件扩展名必须为 .json` |\n| HTTP for Skill | `Skill 资产必须指向目录来源` |\n\nAll errors result in process exit with code 2, ensuring CI/CD pipelines fail fast on configuration issues.\n\n资料来源：[src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n资料来源：[src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n\n---\n\n\n\n## Asset Types\n\n### 相关页面\n\n相关主题：[Manifest System](#manifest-system), [Host Integration](#host-integration)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/manifest/schema.ts](https://github.com/pea3nut/agent-add/blob/main/src/manifest/schema.ts)\n- [src/manifest/parser.ts](https://github.com/pea3nut/agent-add/blob/main/src/manifest/parser.ts)\n- [vibe/manifest.json](https://github.com/pea3nut/agent-add/blob/main/vibe/manifest.json)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n- [src/assets/mcp.ts](https://github.com/pea3nut/agent-add/blob/main/src/assets/mcp.ts)\n- [src/assets/skill.ts](https://github.com/pea3nut/agent-add/blob/main/src/assets/skill.ts)\n- [src/assets/prompt.ts](https://github.com/pea3nut/agent-add/blob/main/src/assets/prompt.ts)\n- [src/assets/command.ts](https://github.com/pea3nut/agent-add/blob/main/src/assets/command.ts)\n- [src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n
\n\n# Asset Types\n\nAsset Types define the categories of installable resources that agent-add can distribute to AI coding assistant hosts. The system supports five distinct asset types, each with specific file formats, validation rules, and installation behaviors.\n\n## Overview\n\nagent-add categorizes all distributable resources into five asset types. Each type has a dedicated handler responsible for installation logic, validation, and host-specific write strategies.\n\n```mermaid\ngraph TD\n A[User Input / Pack Manifest] --> B{Asset Type Detection}\n B -->|JSON| C[MCP Server]\n B -->|Directory + SKILL.md| D[Skill]\n B -->|Markdown| E[Prompt]\n B -->|Markdown + Frontmatter| F[Command]\n B -->|Markdown + Agent Meta| G[Sub-agent]\n \n C --> H[Validation]\n D --> H\n E --> H\n F --> H\n G --> H\n \n H --> I[Host Adapter]\n I --> J[Write Strategy]\n J --> K[Host Filesystem]\n```\n\n## Supported Asset Types\n\n| Asset Type | Identifier | Source Format | Validation Requirement |\n|------------|------------|---------------|------------------------|\n| MCP Server | `mcp` | JSON file | `.json` extension required |\n| Skill | `skill` | Directory | Must contain `SKILL.md` |\n| Prompt | `prompt` | Markdown file | First `# Heading` required |\n| Command | `command` | Markdown with YAML frontmatter | Optional description field |\n| Sub-agent | `subAgent` | Markdown with YAML frontmatter | Optional host specialization |\n\n资料来源：[src/manifest/schema.ts]() and [src/manifest/parser.ts:30-35]()\n\n## MCP Server (`mcp`)\n\nMCP Servers provide Model Context Protocol configurations that enable AI assistants to interact with external tools and services.\n\n### Supported JSON Formats\n\nagent-add auto-detects two MCP configuration formats:\n\n**Format A: Inner Config (Single Server)**\n\n```json\n{\n \"command\": \"npx\",\n \"args\": [\"@playwright/mcp@latest\"],\n \"env\": {}\n}\n```\n\nThe asset name is inferred from the filename: `playwright.json` → name is `playwright`.\n\n**Format B: Full Config with `mcpServers` Wrapper**\n\n```json\n{\n \"mcpServers\": {\n \"playwright\": {\n \"command\": \"npx\",\n \"args\": [\"@playwright/mcp@latest\"]\n }\n }\n}\n```\n\nagent-add automatically unwraps the `mcpServers` object and extracts the inner server name and configuration. This format currently supports a single server only.\n\n资料来源：[README.md - Asset Developer Guide](README.md)\n\n### Installation Behavior\n\n- **JSON shallow merge**: New servers are merged into existing configuration\n- **Atomic write**: Uses temp file + rename for safe writes\n- **TOML support**: `.toml` extension auto-dispatches to TOML parsing path for Codex and Vibe hosts\n\n```mermaid\ngraph LR\n A[MCP JSON Input] --> B{Extension Check}\n B -->|.json| C[JSON Handler]\n B -->|.toml| D[TOML Handler]\n C --> E[Shallow Merge]\n D --> E\n E --> F[Atomic Write]\n F --> G[host mcp config]\n```\n\n## Skill (`skill`)\n\nSkills are reusable agent capabilities distributed as directory bundles.\n\n### Structure Requirements\n\nA valid Skill asset must be a directory containing a `SKILL.md` file at its root:\n\n```\nhelpers/\n├── utils.py\n└── templates/\n └── report.md\n```\n\nThe `SKILL.md` file defines the skill metadata:\n\n```markdown\n---\nname: my-skill\ndescription: A reusable agent skill.\n---\n\n# Skill: my-skill\n\nThis skill does something useful.\n```\n\n### Installation Behavior\n\n- **Directory copy**: Entire directory is recursively copied to host's skills directory\n- **Location**: Installed to `.cursor/skills/my-skill/` (path varies by host)\n- **Validation**: Refuses installation if `SKILL.md` is missing\n\n资料来源：[src/installer.ts:85-93]()\n\n### Source Restrictions\n\nSkills have strict source requirements:\n\n| Allowed Source | Description |\n|----------------|-------------|\n| Local directory path | `~/path/to/skill` |\n| Git URL | `https://github.com/user/repo.git#path/to/skill` |\n\n| Prohibited Source | Reason |\n|-------------------|--------|\n| HTTP(S) URL | Not supported |\n| Inline JSON | Not supported |\n| Inline Markdown | Not supported |\n\n资料来源：[src/installer.ts:85-93]()\n\n## Prompt (`prompt`)\n\nPrompts are rule files or system prompts that define agent behavior guidelines.\n\n### Installation Strategies\n\nPrompts use different write strategies based on host capabilities:\n\n**Append Mode** (Cursor, Claude Code, etc.)\n\nContent is wrapped in HTML comment markers and appended idempotently:\n\n```html\n\n# Code Review Rules\n\nAlways review for security issues first.\nUse bullet points for lists.\n\n```\n\n**Standalone File Mode** (Windsurf, Roo Code, etc.)\n\nCreates a `.md` file in the rules directory:\n\n```\n.windsurf/rules/code-review-rules.md\n```\n\n资料来源：[README.md - Prompt File]()\n\n### Naming Convention\n\nThe asset name is inferred from the first `# Heading` in the Markdown content:\n\n```markdown\n# Code Review Rules\n```\n\n→ Asset name: `code-review-rules`\n\n## Command (`command`)\n\nCommands are slash commands that users can invoke directly in the AI assistant interface.\n\n### File Format\n\nCommands are Markdown files with optional YAML frontmatter:\n\n```markdown\n---\ndescription: Run a comprehensive code review.\n---\n\n# code-review\n\nReview the current file for bugs, security issues, and style violations.\n```\n\n### Installation Behavior\n\n- **Installation directory**: Host-specific commands directory (e.g., `.cursor/commands/`)\n- **File extension**: `.md`\n- **Naming**: Derived from filename or `# Heading`\n\n## Sub-agent (`subAgent`)\n\nSub-agents are specialized AI agents with their own configuration and instructions.\n\n### File Format\n\nSub-agents use Markdown with YAML frontmatter, supporting host specialization:\n\n```markdown\n---\nname: playwright-tester\ndescription: A playwright testing agent.\nagent-add/cursor/model: fast\nagent-add/claude-code/model: haiku\n---\n\n# Playwright Test Agent\n\nPlan and generate Playwright tests.\n```\n\n### Host Specialization Syntax\n\nThe `agent-add//` syntax allows different frontmatter values per host:\n\n```mermaid\ngraph TD\n A[Sub-agent File] --> B[Installation Time]\n B --> C{Current Host}\n C -->|Cursor| D[Extract agent-add/cursor/*]\n C -->|Claude Code| E[Extract agent-add/claude-code/*]\n \n D --> F[Promote to top-level keys]\n E --> F\n F --> G[Remove agent-add/* prefixes]\n G --> H[Install Result]\n```\n\n**After installing to Cursor:**\n\n```markdown\n---\nname: playwright-tester\ndescription: A playwright testing agent.\nmodel: fast\n---\n\n# Playwright Test Agent\n```\n\n**After installing to Claude Code:**\n\n```markdown\n---\nname: playwright-tester\ndescription: A playwright testing agent.\nmodel: haiku\n---\n\n# Playwright Test Agent\n```\n\n## Asset Validation\n\nEach asset type undergoes validation before installation:\n\n```mermaid\ngraph TD\n A[Resolved Source] --> B{Asset Type}\n \n B -->|skill| C{Directory Check}\n C -->|Missing SKILL.md| D[Error: Exit 2]\n C -->|Valid| E[Pass]\n \n B -->|mcp| F{File Check}\n F -->|File not exist| G[Error: Exit 2]\n F -->|.json extension?| H[Error: Exit 2]\n F -->|Valid| E\n \n B -->|prompt| I{Name from Heading}\n I -->|No heading| J[Error: Exit 2]\n I -->|Valid| E\n \n B -->|command| I\n B -->|subAgent| I\n```\n\n资料来源：[src/installer.ts:71-101]()\n\n### Validation Rules by Type\n\n| Asset Type | Checks |\n|------------|--------|\n| `mcp` | File exists, `.json` extension |\n| `skill` | Directory exists, contains `SKILL.md` |\n| `prompt` | First `# Heading` exists (for name inference) |\n| `command` | First `# Heading` exists |\n| `subAgent` | First `# Heading` exists |\n\n## Pack Manifest Integration\n\nAsset types are bundled in pack manifests for distribution:\n\n```json\n{\n \"name\": \"my-team/frontend-pack\",\n \"assets\": [\n { \"type\": \"mcp\", \"source\": \"https://github.com/modelcontextprotocol/servers.git#.mcp.json\" },\n { \"type\": \"skill\", \"source\": \"https://github.com/anthropics/skills.git#skills/pdf\" },\n { \"type\": \"prompt\", \"source\": \"https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/nextjs-react-tailwind/.cursorrules\" },\n { \"type\": \"command\", \"source\": \"https://github.com/wshobson/commands.git#tools/security-scan.md\" },\n { \"type\": \"subAgent\", \"source\": \"https://github.com/VoltAgent/awesome-claude-code-subagents.git#categories/01-core-development/backend-developer.md\" }\n ]\n}\n```\n\n### Asset Name Inference Rules\n\nWhen a pack manifest doesn't specify an asset name, it is inferred from the source:\n\n| Source Pattern | Name Inference |\n|----------------|----------------|\n| Git URL + `#path` | Last segment after `#`, strip extension |\n| Git URL without `#` | Repo name, strip `.git` suffix |\n| Local path / HTTP | Filename, strip extension |\n| Inline JSON `{...}` | Top-level key as MCP name |\n| Inline Markdown with `\\n` | First `# Heading` in kebab-case |\n\n资料来源：[src/source/infer-name.ts]()\n\n---\n\n\n\n## Manifest System\n\n### 相关页面\n\n相关主题：[Asset Types](#asset-types), [CLI Interface](#cli-interface)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/manifest/parser.ts](https://github.com/pea3nut/agent-add/blob/main/src/manifest/parser.ts)\n- [src/manifest/schema.ts](https://github.com/pea3nut/agent-add/blob/main/src/manifest/schema.ts)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n- [src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n- [vibe/manifest.json](https://github.com/pea3nut/agent-add/blob/main/vibe/manifest.json)\n- [README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n
\n\n# Manifest System\n\nThe Manifest System is a core component of agent-add that enables batch installation of multiple assets through a single JSON configuration file. It provides a declarative way to define, distribute, and install a collection of AI agent assets (MCPs, Skills, Prompts, Commands, and Sub-agents) as a single package.\n\n## Overview\n\nAgent Packs are JSON files that bundle multiple assets together, allowing developers and teams to share complete asset collections with a single reference. The Manifest System handles parsing, validation, and processing of these pack manifests.\n\n```mermaid\ngraph TD\n A[Pack Manifest JSON] --> B[Manifest Parser]\n B --> C{Validation}\n C -->|Pass| D[Asset Descriptor Array]\n C -->|Fail| E[Error Exit 2]\n D --> F[Source Resolver]\n F --> G[Install Jobs]\n G --> H[Asset Handlers]\n H --> I[Host Installation]\n```\n\n## Manifest File Format\n\n### Schema Structure\n\nThe manifest schema is defined using Zod for runtime validation. The file path to the schema definition is:\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `name` | `string` | Yes | Pack identifier in `namespace/pack-name` format. Only `[a-zA-Z0-9_-]` characters allowed |\n| `assets` | `Asset[]` | Yes | Array of asset definitions, minimum 1 item |\n\n### Asset Definition\n\nEach asset in the `assets` array has the following structure:\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `type` | `string` | Yes | Asset type: `mcp`, `skill`, `prompt`, `command`, or `subAgent` |\n| `source` | `string` | Yes | Source location (Git URL, local path, or HTTP URL) |\n\n资料来源：[README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n\n### Example Manifest\n\n```json\n{\n \"name\": \"my-team/frontend-pack\",\n \"assets\": [\n { \"type\": \"mcp\", \"source\": \"https://github.com/modelcontextprotocol/servers.git#/.mcp.json\" },\n { \"type\": \"skill\", \"source\": \"https://github.com/anthropics/skills.git#skills/pdf\" },\n { \"type\": \"prompt\", \"source\": \"https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/nextjs-react-tailwind/.cursorrules\" },\n { \"type\": \"command\", \"source\": \"https://github.com/wshobson/commands.git#tools/security-scan.md\" },\n { \"type\": \"subAgent\", \"source\": \"https://github.com/VoltAgent/awesome-claude-code-subagents.git#categories/01-core-development/backend-developer.md\" }\n ]\n}\n```\n\n资料来源：[README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n\n## Source Syntax for Manifests\n\nThe manifest parser supports multiple source formats that are resolved to local paths:\n\n```mermaid\ngraph LR\n A[Source String] --> B{Format Detection}\n B --> C[#path segment]\n B --> D[Git URL .git suffix]\n B --> E[Local/HTTP path]\n \n C --> F[kebab-case name from path]\n D --> G[repo name without .git]\n E --> H[filename without extension]\n```\n\n### Source Resolution Rules\n\n| Source Format | Name Extraction Rule | Example |\n|--------------|---------------------|---------|\n| Git URL with `#path` | Take last segment after `#`, strip extension | `...git#skills/pdf` → `pdf` |\n| Git URL without `#` | Take repo name, strip `.git` suffix | `...playwright.git` → `playwright` |\n| Local path / HTTP URL | Take filename, strip extension | `./mcps/playwright.json` → `playwright` |\n\n资料来源：[src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n\n### Inline Sources\n\nManifests support two inline source formats:\n\n| Format | Detection | Name Source |\n|--------|-----------|-------------|\n| `inline-json` | Starts with `{` | Single top-level JSON key |\n| `inline-md` | Contains `\\n` (newlines) | First `# Heading` in Markdown, converted to kebab-case |\n\nBoth inline sources are written to temporary files before following the normal installation flow.\n\n## Parser Implementation\n\n### Entry Point\n\nThe manifest parser is invoked from the installer orchestrator. When `--pack` flags are detected, the parser processes each manifest file:\n\n```mermaid\nsequenceDiagram\n participant CLI as CLI Input\n participant Inst as Installer\n participant MP as Manifest Parser\n participant SR as Source Resolver\n \n CLI->>Inst: pack: [manifest.json, ...]\n Inst->>MP: parseManifest(filePath)\n MP->>MP: Read JSON file\n MP->>MP: Zod validation\n alt Valid\n MP-->>Inst: ManifestData[]\n else Invalid\n MP->>Inst: Error + Exit 2\n end\n Inst->>SR: Resolve each asset source\n```\n\n### Validation Flow\n\nThe parser performs comprehensive validation using Zod schema validation:\n\n1. **Schema validation**: Checks required fields and types\n2. **Name format validation**: Ensures `name` matches `namespace/pack-name` pattern\n3. **Asset type validation**: Verifies all `type` fields are in the allowed set\n4. **Error reporting**: Provides specific error messages with field paths\n\n资料来源：[src/manifest/parser.ts](https://github.com/pea3nut/agent-add/blob/main/src/manifest/parser.ts)\n\n### Error Handling\n\nThe parser provides structured error messages for common validation failures:\n\n| Error Condition | Message |\n|-----------------|---------|\n| Invalid asset type | `Unsupported asset type: ''. Supported: mcp, skill, prompt, command, subAgent` |\n| Invalid name format | `Manifest name must match namespace/pack-name format` |\n| Missing required field | `Manifest missing required field: ` |\n| JSON parse failure | `Invalid Manifest format` |\n\n资料来源：[src/manifest/parser.ts](https://github.com/pea3nut/agent-add/blob/main/src/manifest/parser.ts)\n\n## Integration with Installer\n\n### Processing Pipeline\n\n```mermaid\ngraph TD\n subgraph Input Processing\n A[Pack Manifests] --> B[Parse Each Manifest]\n B --> C[Extract Asset Descriptors]\n end\n \n subgraph Resolution\n C --> D[Resolve Sources]\n D --> E[Validate Each Asset]\n end\n \n subgraph Job Creation\n E --> F{Capability Check}\n F -->|Supported| G[Create Install Job]\n F -->|Unsupported| H[Skip Result]\n end\n \n subgraph Execution\n G --> I[Execute Handler]\n I --> J[Install Result]\n end\n```\n\n### Manifest Processing in Installer\n\nThe installer processes manifests in the following sequence:\n\n1. **Parse**: Each manifest file is parsed to extract asset descriptors\n2. **Resolve**: Asset sources are resolved to local file paths\n3. **Validate**: Each asset is validated according to its type requirements\n4. **Filter**: Assets unsupported by the target host are skipped\n5. **Execute**: Valid assets are processed by appropriate handlers\n\n资料来源：[src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n\n### Skip Behavior for Pack Sources\n\nUnlike explicit flag sources, pack sources that target unsupported asset types are **silently skipped** rather than causing errors. This design allows pack authors to create cross-host compatible manifests without requiring per-host manifest files.\n\n> Note: This is different from explicit flags, which exit with error code 2 if the asset type is unsupported.\n\n## CLI Usage\n\n### Installing a Pack\n\n```bash\n# Single pack installation\nnpx -y agent-add --host cursor --pack ./manifest.json\n\n# Multiple packs\nnpx -y agent-add --host claude-code \\\n --pack ./frontend-pack.json \\\n --pack ./backend-pack.json\n\n# Combined with explicit assets\nnpx -y agent-add --host cursor \\\n --pack ./team-pack.json \\\n --mcp ./local-mcp.json\n```\n\n### All `--pack` Flag Options\n\n| Flag | Description | Collectable |\n|------|-------------|-------------|\n| `--pack ` | Install an Agent Pack manifest | Yes (repeatable) |\n\nAll asset flags can be repeated and freely combined with `--pack`.\n\n## Development and Testing\n\n### Test Coverage\n\nThe manifest system is tested through:\n\n| Test Type | Location | Purpose |\n|-----------|----------|---------|\n| Unit tests | `tests/unit/` | Parser validation, name inference |\n| Contract tests | `tests/contract/` | CLI black-box behavior |\n| Feature tests | `tests/features/` | End-to-end scenarios |\n\n### Running Tests\n\n```bash\n# All unit + integration tests\nnpm test\n\n# Contract tests only\nnpm run test:contract\n\n# Single manifest parser test\nnpx vitest run tests/unit/manifest/parser.test.ts\n```\n\n### Development Setup\n\n```bash\nnpm install\nnpm run build\nnpm run install:vibe # Installs dev assets via pack manifest\n```\n\nThe `install:vibe` command installs assets defined in `vibe/manifest.json`, demonstrating the pack manifest system in action.\n\n## Related Components\n\n| Component | File | Role |\n|-----------|------|------|\n| Schema | `src/manifest/schema.ts` | Zod schema definition for ManifestData |\n| Parser | `src/manifest/parser.ts` | Parsing and validation logic |\n| Name Inference | `src/source/infer-name.ts` | Extracts asset names from sources |\n| Installer | `src/installer.ts` | Orchestrates manifest processing |\n| CLI | `src/cli.ts` | Command-line argument handling |\n\n## Key Design Decisions\n\n| Decision | Rationale |\n|----------|-----------|\n| Pack sources skip unsupported types | Enables cross-host manifest sharing without per-host variants |\n| Explicit flags error on unsupported types | Forces developers to handle host compatibility explicitly |\n| Atomic JSON writes for MCP | Ensures config file integrity during concurrent operations |\n| Temp file + rename strategy | Provides atomicity for manifest-based MCP installations |\n| Zod for schema validation | Runtime type checking with detailed error messages |\n\n---\n\n\n\n## CLI Interface\n\n### 相关页面\n\n相关主题：[Getting Started](#getting-started), [Manifest System](#manifest-system)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n- [src/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/index.ts)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n- [bin/agent-add.js](https://github.com/pea3nut/agent-add/blob/main/bin/agent-add.js)\n- [package.json](https://github.com/pea3nut/agent-add/blob/main/package.json)\n
\n\n# CLI Interface\n\nThe CLI Interface is the primary user-facing component of agent-add, responsible for command-line argument parsing, host detection, input validation, and orchestrating the installation workflow. It serves as the entry point for all asset installation operations.\n\n## Overview\n\nagent-add provides a unified command-line interface for installing MCP servers, Skills, Prompts, Commands, and Sub-agents across 18 different AI agent hosts. The CLI handles argument parsing using the `commander` library and delegates actual installation logic to the `installer` module.\n\n```mermaid\ngraph TD\n A[User CLI Command] --> B[bin/agent-add.js]\n B --> C[src/index.ts]\n C --> D[src/cli.ts - createProgram]\n D --> E[program.parseAsync process.argv]\n E --> F[Input Validation]\n F --> G[runInstaller cliInput, host, cwd]\n G --> H[printSummary results]\n H --> I[Exit: 0=success, 1=conflict/error, 2=validation]\n```\n\n资料来源：[src/index.ts:1-8](https://github.com/pea3nut/agent-add/blob/main/src/index.ts)\n\n## Entry Points\n\n### Binary Entry Point\n\nThe CLI binary is defined at `bin/agent-add.js` and serves as the executable entry point for the npm package. It is registered in `package.json` under the `bin` field.\n\n```javascript\n#!/usr/bin/env node\nimport '../dist/index.js';\n```\n\n资料来源：[bin/agent-add.js](https://github.com/pea3nut/agent-add/blob/main/bin/agent-add.js)\n\n### Module Entry Point\n\nThe TypeScript module entry at `src/index.ts` creates the program and handles top-level error catching:\n\n```typescript\nimport { createProgram } from './cli.js';\n\nconst program = createProgram();\nprogram.parseAsync(process.argv).catch((err: Error) => {\n process.stderr.write(`agent-add error: ${err.message}\\n`);\n process.exit(2);\n});\n```\n\n资料来源：[src/index.ts:1-8](https://github.com/pea3nut/agent-add/blob/main/src/index.ts)\n\n## Command Structure\n\n### Global Options\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `--host ` | string | Target host ID (cursor, claude-code, claude-desktop, etc.) |\n| `-V, --version` | boolean | Show version number |\n| `-h, --help` | boolean | Show help information |\n\n### Asset Installation Flags\n\nAll asset flags can be repeated to install multiple assets of the same type and can be freely combined with `--pack`:\n\n| Flag | Type | Description |\n|------|------|-------------|\n| `--pack ` | string[] | Install an Agent Pack manifest |\n| `--mcp ` | string[] | Install an MCP server config |\n| `--skill ` | string[] | Install a Skill directory |\n| `--prompt ` | string[] | Install a Prompt file |\n| `--command ` | string[] | Install a Command file |\n| `--sub-agent ` | string[] | Install a Sub-agent file |\n\n资料来源：[src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n\n## Command Definition\n\nThe `createProgram()` function in `src/cli.ts` defines the Commander program structure:\n\n```typescript\nfunction createProgram() {\n const program = new Command();\n\n program\n .name('agent-add')\n .description('Install AI agent assets into different hosts')\n .argument('[sources...]', 'Sources to install')\n .option('--pack ', 'Install an Agent Pack manifest', collect, [])\n .option('--mcp ', 'Install an MCP server', collect, [])\n .option('--skill ', 'Install a Skill directory', collect, [])\n .option('--prompt ', 'Install a Prompt file', collect, [])\n .option('--command ', 'Install a Command file', collect, [])\n .option('--sub-agent ', 'Install a Sub-agent file', collect, [])\n .option('--host ', 'Target host ID', collect, [])\n .action(async (options) => { /* ... */ });\n\n return program;\n}\n```\n\n资料来源：[src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n\n## Input Collection\n\nThe `collect()` helper function accumulates multiple values when flags are repeated:\n\n```typescript\nfunction collect(value: string, previous: string[]): string[] {\n return [...previous, value];\n}\n```\n\nThis enables usage patterns like:\n```bash\nagent-add --mcp server1.json --mcp server2.json --skill ./my-skill\n```\n\n资料来源：[src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n\n## Input Validation Flow\n\n```mermaid\ngraph TD\n A[Parse CLI Options] --> B{Has Asset Flags?}\n B -->|No| C[Error: No asset flags provided]\n C --> D[Exit 2]\n B -->|Yes| E{Host Specified?}\n E -->|No| F{TTY Mode?}\n F -->|Yes| G[Interactive Host Selection]\n F -->|No| H[Error: --host required in CI]\n G --> I[Selected Host]\n E -->|Yes| I\n I --> J[runInstaller cliInput, host, cwd]\n J --> K[printSummary]\n K --> L{Results contain errors?}\n L -->|Yes| M[Exit 1]\n L -->|No| N[Exit 0]\n```\n\n### Asset Flag Validation\n\nBefore proceeding, the CLI verifies at least one asset flag is provided:\n\n```typescript\nconst hasAssetFlags =\n cliInput.pack.length > 0 ||\n cliInput.mcp.length > 0 ||\n cliInput.skill.length > 0 ||\n cliInput.prompt.length > 0 ||\n cliInput.command.length > 0 ||\n cliInput.subAgent.length > 0;\n\nif (!hasAssetFlags) {\n process.stderr.write(\n 'agent-add error: No asset flags provided. Use --pack, --mcp, --skill, --prompt, --command, or --sub-agent.\\n',\n );\n process.exit(2);\n}\n```\n\n资料来源：[src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n\n## Host Selection\n\n### Explicit Host Specification\n\nWhen `--host` is explicitly provided, it is used directly:\n\n```typescript\nif (cliInput.host) {\n hostId = cliInput.host;\n}\n```\n\n### Interactive Host Selection\n\nIn TTY (interactive) mode, if no host is specified, the CLI presents an interactive selection menu:\n\n```typescript\nelse if (process.stdout.isTTY) {\n const selected = await inquirer.prompt([{\n type: 'select',\n name: 'host',\n message: 'Select your AI agent host:',\n choices: getValidHostIds(),\n }]);\n hostId = selected.host;\n}\n```\n\n### Non-TTY Strict Mode\n\nIn CI/non-interactive environments, the CLI requires explicit host specification and exits with code 2 if missing:\n\n```typescript\nelse {\n const validIds = getValidHostIds().join(', ');\n process.stderr.write(\n `agent-add error: --host flag required in non-TTY environment. Valid hosts: ${validIds}\\n`,\n );\n process.exit(2);\n}\n```\n\n资料来源：[src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n\n## CliInput Data Model\n\nThe `CliInput` interface defines the internal representation of parsed CLI arguments:\n\n```typescript\ninterface CliInput {\n pack: string[];\n mcp: string[];\n skill: string[];\n prompt: string[];\n command: string[];\n subAgent: string[];\n host?: string;\n}\n```\n\nThis is populated from the command options and passed to the installer:\n\n```typescript\nconst cliInput: CliInput = {\n mcp: options.mcp,\n skill: options.skill,\n prompt: options.prompt,\n command: options.command,\n subAgent: options.subAgent,\n pack: options.pack,\n host: options.host,\n};\n```\n\n资料来源：[src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n\n## Error Handling\n\n### Top-Level Error Handler\n\nThe entry point catches all unhandled errors and exits with code 2:\n\n```typescript\nprogram.parseAsync(process.argv).catch((err: Error) => {\n process.stderr.write(`agent-add error: ${err.message}\\n`);\n process.exit(2);\n});\n```\n\n### Action-Level Error Handling\n\nThe main action also handles install results for conflicts and errors:\n\n```typescript\nconst hasConflicts = summary.results.some((r) => r.status === 'conflict');\nconst hasErrors = summary.results.some((r) => r.status === 'error');\n\nif (hasErrors || hasConflicts) {\n process.exit(1);\n}\n```\n\n## Exit Codes\n\n| Code | Meaning | Trigger |\n|------|---------|---------|\n| 0 | Success | All assets installed without errors or conflicts |\n| 1 | Partial failure | Install completed but had conflicts or errors |\n| 2 | Validation failure | Invalid input, missing flags, or unsupported operations |\n\n资料来源：[src/index.ts:6](https://github.com/pea3nut/agent-add/blob/main/src/index.ts) and [src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n\n## Usage Examples\n\n### Install Single Asset\n\n```bash\nnpx -y agent-add --host cursor --mcp ./playwright.json\n```\n\n### Install Multiple Assets\n\n```bash\nnpx -y agent-add --host claude-code \\\n --mcp ./mcp/servers.json \\\n --skill ./skills/pdf \\\n --prompt 'https://raw.githubusercontent.com/.../rules.md'\n```\n\n### Install via Pack Manifest\n\n```bash\nnpx -y agent-add --host cursor --pack ./manifest.json\n```\n\n### Interactive Mode\n\n```bash\nnpx -y agent-add --mcp ./server.json\n# (Prompts for host selection if in TTY mode)\n```\n\n资料来源：[README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n\n## Package Configuration\n\nThe CLI binary is registered in `package.json`:\n\n```json\n{\n \"bin\": {\n \"agent-add\": \"./bin/agent-add.js\"\n },\n \"type\": \"module\",\n \"engines\": {\n \"node\": \">=18\"\n }\n}\n```\n\n资料来源：[package.json](https://github.com/pea3nut/agent-add/blob/main/package.json)\n\n---\n\n\n\n## Testing\n\n### 相关页面\n\n相关主题：[Project Configuration](#configuration)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/pea3nut/agent-add/blob/main/package.json)\n- [README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n- [vibe/manifest.json](https://github.com/pea3nut/agent-add/blob/main/vibe/manifest.json)\n- [vibe/system-prompt.md](https://github.com/pea3nut/agent-add/blob/main/vibe/system-prompt.md)\n- [vibe/tasks/verify-host-readme.md](https://github.com/pea3nut/agent-add/blob/main/vibe/tasks/verify-host-readme.md)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n
\n\n# Testing\n\n## Overview\n\nThe agent-add project employs a multi-layered testing strategy to ensure reliability across different host environments and asset types. The testing infrastructure validates the CLI tool's functionality through unit tests, integration tests, contract tests, and scenario-based tests executed by AI agents.\n\n## Test Architecture\n\nThe testing framework is built on **Vitest** with a three-tier approach:\n\n```mermaid\ngraph TD\n A[Test Suite] --> B[Unit Tests]\n A --> C[Integration Tests]\n A --> D[Contract Tests]\n A --> E[Scenario Tests]\n \n B --> B1[vitest run]\n C --> C1[vitest run]\n D --> D1[Black-box CLI tests]\n E --> E1[AI Agent execution]\n \n style A fill:#e1f5fe\n style D fill:#fff3e0\n style E fill:#f3e5f5\n```\n\n## Test Configuration\n\nThe Vitest configuration is defined in `vitest.config.ts`:\n\n| Configuration Aspect | Value |\n|---------------------|-------|\n| Test Runner | Vitest 4.1.0 |\n| TypeScript Target | Node.js 18+ |\n| Test Location | `tests/` directory |\n| Run Command | `npm test` |\n\n## Test Categories\n\n### Unit Tests\n\nUnit tests verify individual components in isolation. Each host adapter has corresponding unit tests.\n\n**Test Location:** `tests/unit/hosts/.test.ts`\n\n**Example - Cursor Host Test:**\n```typescript\nnpx vitest run tests/unit/hosts/cursor.test.ts\n```\n\nUnit tests verify:\n- Adapter `id`, `displayName`, and `docs` values\n- Asset capabilities match the README matrix\n- Supported capabilities have required fields\n\n### Integration Tests\n\nIntegration tests validate the interaction between components.\n\n**Command:** `npm run test:integration`\n\n### Contract Tests\n\nContract tests perform black-box CLI testing without requiring the full test suite.\n\n**Command:** `npm run test:contract`\n\n### Scenario Tests\n\nScenario tests use Gherkin `.feature` files executed by AI agents via [scenario-test](https://github.com/pea3nut/scenario-test).\n\n**Location Structure:**\n```\ntests/\n├── features/\n│ ├── scenario-run-config.md # Run configuration\n│ ├── core/ # Core behavior tests (7 .feature files)\n│ └── host/ # Host compatibility tests (3 .feature files)\n└── fixtures/ # Static test fixtures\n```\n\n**Execution Commands:**\n```bash\n/scenario-exec tests/features/core\n/scenario-exec tests/features/host\n```\n\nEach scenario runs in an isolated temporary directory. The run configuration is defined in `tests/features/scenario-run-config.md`.\n\n## Test Fixtures\n\nStatic test fixtures support different asset types:\n\n```\ntests/fixtures/\n├── mcp/\n├── skill/\n├── prompt/\n├── command/\n├── sub-agent/\n└── pack/\n```\n\nFixtures are used by both unit tests and scenario tests to provide consistent test data.\n\n## Development Testing Workflow\n\n### Setup\n\nBefore running tests, build the project:\n\n```bash\nnpm install\nnpm run build\n```\n\n### Running Tests\n\n| Command | Purpose |\n|---------|---------|\n| `npm test` | All unit + integration tests |\n| `npm run test:contract` | CLI black-box contract tests only |\n| `npm run test:integration` | Integration tests |\n| `npx vitest run tests/unit/hosts/cursor.test.ts` | Single unit test file |\n\n### Vibe Development Assets\n\nThe project uses a custom testing manifest for development:\n\n**File:** `vibe/manifest.json`\n\n```json\n{\n \"name\": \"agent-add/dev-pack\",\n \"assets\": [\n { \"type\": \"skill\", \"source\": \"https://github.com/pea3nut/scenario-test.git#skills/scenario-test\" },\n { \"type\": \"command\", \"source\": \"https://github.com/pea3nut/scenario-test.git#commands/scenario-exec.md\" },\n { \"type\": \"subAgent\", \"source\": \"https://github.com/pea3nut/scenario-test.git#agents/scenario-case-runner.md\" },\n { \"type\": \"command\", \"source\": \"./vibe/tasks/verify-host-readme.md\" },\n { \"type\": \"prompt\", \"source\": \"./vibe/system-prompt.md\" }\n ]\n}\n```\n\nInstall dev assets via:\n```bash\nnpm run install:vibe\n```\n\nThis installs:\n- **scenario-test skill**: Provides testing infrastructure\n- **scenario-exec command**: Triggers scenario test execution\n- **scenario-case-runner sub-agent**: AI agent that executes scenarios\n- **verify-host-readme command**: Validates host README consistency\n- **system-prompt**: Development system prompt\n\n## Host README Verification\n\nThe `verify-host-readme.md` task validates consistency between the host capability matrix in `src/hosts/README.md` and actual adapter implementations.\n\n**Validation Criteria:**\n- Adapter configuration fields match README matrix values exactly\n- Unit tests assert exact values for every field\n- New host contributions must update both adapter and README\n\n## Linting and Type Checking\n\nBefore test execution, validate code quality:\n\n```bash\nnpm run lint # tsc --noEmit type checking\n```\n\n## Test Isolation\n\nThe testing framework ensures isolation through:\n\n1. **Temporary directories** - Scenario tests run in isolated temp directories\n2. **Temp file writes** - MCP config uses temp file + rename for safety\n3. **AGENT_ADD_HOME override** - Environment variable redirects install paths for test isolation\n\n## Dependencies\n\nTest infrastructure relies on:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| vitest | ^4.1.0 | Test runner |\n| tsx | ^4.21.0 | TypeScript execution |\n| typescript | ^5.9.3 | Type checking |\n| scenario-test | (external) | Scenario test framework |\n\n---\n\n\n\n## Project Configuration\n\n### 相关页面\n\n相关主题：[Testing](#testing)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/pea3nut/agent-add/blob/main/package.json)\n- [tsup.config.ts](https://github.com/pea3nut/agent-add/blob/main/tsup.config.ts)\n- [src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n- [src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n- [src/hosts/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/index.ts)\n- [src/assets/mcp.ts](https://github.com/pea3nut/agent-add/blob/main/src/assets/mcp.ts)\n- [src/assets/skill.ts](https://github.com/pea3nut/agent-add/blob/main/src/assets/skill.ts)\n- [src/assets/prompt.ts](https://github.com/pea3nut/agent-add/blob/main/src/assets/prompt.ts)\n- [src/manifest/schema.ts](https://github.com/pea3nut/agent-add/blob/main/src/manifest/schema.ts)\n
\n\n# Project Configuration\n\n## Overview\n\nThe agent-add project uses a multi-layered configuration system to support installing various asset types across 18 different AI coding hosts. The configuration architecture encompasses TypeScript compilation settings, build tooling via tsup, package metadata, host adapter definitions, asset handler configurations, and source resolution strategies.\n\nThe project targets Node.js 18+ and compiles to CommonJS format for maximum compatibility with AI coding tool environments. 资料来源：[package.json:17]()\n\n## Build System Configuration\n\n### tsup Build Configuration\n\nThe project uses [tsup](https://github.com/egoist/tsup) for TypeScript bundling, defined in `tsup.config.ts`:\n\n```typescript\nimport { defineConfig } from 'tsup';\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['cjs'],\n target: 'node18',\n clean: true,\n sourcemap: true,\n dts: false,\n outDir: 'dist',\n noExternal: [/.*/],\n});\n```\n\n| Option | Value | Purpose |\n|--------|-------|---------|\n| `entry` | `['src/index.ts']` | Single entry point for CLI application |\n| `format` | `['cjs']` | CommonJS output format for Node.js compatibility |\n| `target` | `node18` | Transpile for Node.js 18 environment |\n| `clean` | `true` | Remove previous build artifacts before each build |\n| `sourcemap` | `true` | Generate source maps for debugging |\n| `dts` | `false` | Disable TypeScript declaration generation |\n| `outDir` | `'dist'` | Output directory for compiled files |\n| `noExternal` | `[/.*/]` | Bundle all dependencies into output |\n\n资料来源：[tsup.config.ts:1-11]()\n\n### Build Scripts\n\nThe npm scripts in `package.json` define the development workflow:\n\n```json\n{\n \"scripts\": {\n \"build\": \"tsup\",\n \"dev\": \"tsx watch src/index.ts\",\n \"test\": \"vitest run\",\n \"install:vibe\": \"npx -y agent-add -- --pack vibe/manifest.json\"\n }\n}\n```\n\n| Script | Command | Usage |\n|--------|---------|-------|\n| `build` | `tsup` | Compile TypeScript to JavaScript |\n| `dev` | `tsx watch src/index.ts` | Development mode with hot reload |\n| `test` | `vitest run` | Execute unit and integration tests |\n| `install:vibe` | `agent-add -- --pack vibe/manifest.json` | Install development assets via pack manifest |\n\n资料来源：[package.json:27-31]()\n\n## Package Configuration\n\n### Engine Requirements\n\n```json\n\"engines\": {\n \"node\": \">=18\"\n}\n```\n\nThe project requires Node.js 18 or higher due to ES module features and modern JavaScript APIs used throughout the codebase. 资料来源：[package.json:35-37]()\n\n### Core Dependencies\n\nThe project relies on several key runtime dependencies:\n\n| Dependency | Version | Purpose |\n|------------|---------|---------|\n| `commander` | ^14.0.3 | CLI argument parsing |\n| `smol-toml` | ^1.6.1 | TOML format parsing for Codex/Vibe hosts |\n| `yaml` | ^2.8.2 | YAML frontmatter parsing for sub-agents |\n| `zod` | ^4.3.6 | Manifest schema validation |\n\nDevelopment dependencies include TypeScript, vitest for testing, and tsx for development execution. 资料来源：[package.json:11-24]()\n\n## Host Adapter Configuration\n\n### Host Adapter Type System\n\nThe host configuration system uses a TypeScript interface defined in `src/hosts/types.ts`:\n\n```typescript\ninterface AssetCapability {\n supported: boolean;\n reason?: string;\n configFile?: string;\n installDir?: string;\n writeStrategy?: 'append-with-marker' | 'create-file-in-dir';\n}\n\ninterface HostAdapter {\n id: string;\n displayName: string;\n docs: string;\n assets: Record;\n}\n```\n\n资料来源：[src/hosts/types.ts]()\n\n### Host Capability Matrix\n\nThe project supports 18 distinct hosts, each with unique capability profiles:\n\n| Host ID | MCP | Prompt | Skill | Command | Sub-agent |\n|---------|-----|--------|-------|---------|-----------|\n| `cursor` | ✅ | ✅ | ✅ | ✅ | ✅ |\n| `claude-code` | ✅ | ✅ | ❌ | ✅ | ✅ |\n| `claude-desktop` | ✅ | ❌ | ❌ | ❌ | ❌ |\n| `windsurf` | ✅ | ✅ | ❌ | ❌ | ❌ |\n| `codex` | ✅ | ❌ | ❌ | ❌ | ❌ |\n| `vibe` | ✅ | ❌ | ❌ | ❌ | ❌ |\n\nEach host adapter hardcodes its configuration in a dedicated file under `src/hosts/.ts` and registers in `src/hosts/index.ts` through the host registry Map. 资料来源：[src/hosts/README.md](), [src/hosts/index.ts]()\n\n### Write Strategy Configuration\n\nHosts configure one of two write strategies for prompt assets:\n\n```mermaid\ngraph TD\n A[Prompt Asset] --> B{Write Strategy}\n B --> C[append-with-marker]\n B --> D[create-file-in-dir]\n C --> E[HTML comment markers
Idempotent append]\n D --> F[Standalone file creation
Skip if exists]\n```\n\n**Append with Marker Strategy**: Used by Cursor, Claude Code, and similar hosts. Content is wrapped in HTML comment markers:\n\n```html\n\n# Code Review Rules\n...\n\n```\n\n**Create File in Dir Strategy**: Used by Windsurf, Roo Code, and similar hosts. Creates `.md` in the rules directory, skipping if already exists. 资料来源：[src/assets/prompt.ts]()\n\n## Asset Type Configuration\n\n### MCP Asset Configuration\n\nMCP assets support two JSON formats:\n\n**Format A - Inner Config (Single Server)**:\n```json\n{\n \"command\": \"npx\",\n \"args\": [\"@playwright/mcp@latest\"],\n \"env\": {}\n}\n```\n\n**Format B - Full Config with mcpServers Wrapper**:\n```json\n{\n \"mcpServers\": {\n \"playwright\": {\n \"command\": \"npx\",\n \"args\": [\"@playwright/mcp@latest\"]\n }\n }\n}\n```\n\nThe system automatically detects `.toml` extension and dispatches to the TOML handler path for Codex and Vibe hosts. 资料来源：[src/assets/mcp.ts]()\n\n### Skill Asset Configuration\n\nSkills require a specific directory structure with a mandatory `SKILL.md` file:\n\n```markdown\n\n---\nname: my-skill\ndescription: A reusable agent skill.\n---\n\n# Skill: my-skill\n\nThis skill does something useful.\n```\n\nThe skill handler validates the presence of `SKILL.md` before installation and recursively copies the directory to the host's skills directory. 资料来源：[src/assets/skill.ts](), [README.md]()\n\n### Sub-agent Asset Configuration\n\nSub-agents support host specialization through the `agent-add//` syntax in YAML frontmatter:\n\n```markdown\n---\nname: playwright-tester\ndescription: A playwright testing agent.\nagent-get/cursor/model: fast\nagent-get/claude-code/model: haiku\n---\n\n# Playwright Test Agent\n```\n\nThe handler promotes matching `agent-add//*` values to top-level keys and removes all `agent-add/*` prefixed keys during installation. 资料来源：[src/assets/sub-agent.ts]()\n\n## Manifest Schema Configuration\n\nThe pack manifest uses JSON Schema validation via Zod:\n\n```typescript\nconst ManifestSchema = z.object({\n name: z.string().regex(/^[a-zA-Z0-9_-]+\\/[a-zA-Z0-9_-]+$/),\n assets: z.array(AssetDescriptorSchema).min(1),\n});\n```\n\n| Field | Type | Constraints |\n|-------|------|-------------|\n| `name` | string | Format `namespace/pack-name`, regex `[a-zA-Z0-9_-]/[a-zA-Z0-9_-]` |\n| `assets` | array | Minimum 1 item |\n| `assets[].type` | enum | `mcp`, `skill`, `prompt`, `command`, `subAgent` |\n| `assets[].source` | string | URI or local path |\n\n资料来源：[src/manifest/schema.ts]()\n\n## Source Resolution Configuration\n\n### Supported Source Types\n\n```mermaid\ngraph LR\n A[Source Input] --> B{Source Type Detection}\n B --> C[local]\n B --> D[git-ssh]\n B --> E[git-https]\n B --> F[http-file]\n B --> G[inline-json]\n B --> H[inline-md]\n```\n\n| Source Type | Detection Rule | Supported Asset Types |\n|-------------|----------------|------------------------|\n| `local` | File path exists on filesystem | All |\n| `git-ssh` | Starts with `git@` | All |\n| `git-https` | Starts with `https://` or `http://` | All |\n| `http-file` | Direct HTTP/HTTPS URL | MCP, Prompt, Command, Sub-agent |\n| `inline-json` | Starts with `{` | MCP only |\n| `inline-md` | Contains `\\n` | Prompt, Command, Sub-agent |\n\n**Note**: Skill assets do not support inline sources or direct HTTP URLs—exit code 2 is returned for these invalid sources. 资料来源：[src/source/inline.ts](), [src/installer.ts:52-57]()\n\n### Asset Name Inference Rules\n\n| Source Pattern | Name Extraction Rule | Example |\n|----------------|---------------------|---------|\n| Inline Markdown | First `# Heading` → kebab-case | `# Code Review` → `code-review` |\n| Git URL with `#path` | Last segment after `#`, strip extension | `...git#skills/pdf` → `pdf` |\n| Git URL without `#` | Repo name, strip `.git` suffix | `...playwright.git` → `playwright` |\n| Local path / HTTP | Filename, strip extension | `./mcps/playwright.json` → `playwright` |\n\n资料来源：[src/source/infer-name.ts]()\n\n## Environment Configuration\n\n### AGENT_ADD_HOME Environment Variable\n\nThe `AGENT_ADD_HOME` environment variable overrides `os.homedir()` return value in `src/assets/mcp.ts`. This redirects Claude Desktop and Codex host install paths to temporary directories for test isolation:\n\n```typescript\nconst getHomeDir = (): string => {\n return process.env.AGENT_ADD_HOME || os.homedir();\n};\n```\n\n资料来源：[src/assets/mcp.ts]()\n\n## Installation Flow Configuration\n\n### Core Data Flow\n\n```mermaid\ngraph TD\n A[CLI flags / --pack Manifest] --> B[Explicit flag capability check]\n B -->|exit 2 if unsupported| C[AssetDescriptor array]\n C --> D[ResolvedSource array]\n D --> E[InstallJob array]\n E --> F[InstallResult array]\n F --> G[Summary output]\n \n B -.->|--pack skips check| B\n```\n\nThe installation pipeline follows these stages:\n\n1. **Input Parsing**: CLI flags or pack manifest → `AssetDescriptor[]`\n2. **Capability Check**: Verify host supports requested asset types (exits 2 if unsupported)\n3. **Source Resolution**: `AssetDescriptor[]` → `ResolvedSource[]` with local paths and temp directories\n4. **Validation**: Each asset validated based on type-specific rules\n5. **Job Creation**: `ResolvedSource[]` → `InstallJob[]` (skip unsupported assets)\n6. **Handler Execution**: Process each job via type-specific handler\n7. **Result Aggregation**: Collect `InstallResult[]` with statuses: written, exists, updated, conflict, skipped, error\n\n资料来源：[src/installer.ts](), [src/cli.ts]()\n\n### Explicit Flag Capability Checking\n\nThe installer checks explicit flag capability declarations before building jobs. When a host declares `supported: false` for an asset type:\n\n1. Outputs error with reason and README link\n2. Exits with code 2\n\nThis check is **skipped** for `--pack` sources, allowing pack manifests to include assets that may not be supported by all hosts. 资料来源：[src/installer.ts](), [src/hosts/README.md]()\n\n## License\n\nThis project is licensed under the Mozilla Public License 2.0 (MPL-2.0).\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：pea3nut/agent-add\n\n摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：v1.1.0。\n\n## 1. 安装坑 · 来源证据：v1.1.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.1.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5c106a51ec5d4f999b8bcef8e68a89ec | https://github.com/pea3nut/agent-add/releases/tag/1.1.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 2. 安装坑 · 社区讨论暴露的待验证问题：I built a CLI that installs MCP, skills, prompts, commands and sub ...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：I built a CLI that installs MCP, skills, prompts, commands and sub ... 6 Apr 2026 · Project & Supported Tools. The source code is hosted on GitHub: https://github.com/pea3nut/agent-add ... r/mcp - I built a tool that auto- ...\n- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- 证据：social_signal:reddit | ssig_6d54ef81557a451081be71b052d0e31b | https://www.reddit.com/r/ClaudeAI/comments/1sdrk6k/i_built_a_cli_that_installs_mcp_skills_prompts/ | I built a CLI that installs MCP, skills, prompts, commands and sub ...\n\n## 3. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | host_targets=mcp_host, claude, claude_code, cursor, chatgpt\n\n## 4. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | README/documentation is current enough for a first validation pass.\n\n## 5. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | last_activity_observed missing\n\n## 6. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | no_demo; severity=medium\n\n## 8. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | issue_or_pr_quality=unknown\n\n## 9. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | release_recency=unknown\n\n\n", "markdown_key": "agent-add", "pages": "draft", "source_refs": [ { "evidence_id": "art_7871f43a97e049c0ba0df6fa5a5b6e88", "kind": "docs", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/pea3nut/agent-add#readme" } ], "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "agent-add 说明书", "toc": [ "https://github.com/pea3nut/agent-add 项目说明书", "目录", "Introduction", "Purpose and Scope", "Supported Hosts", "Supported Asset Types", "Architecture Overview", "Core Data Flow", "Doramagic 踩坑日志" ] } }, "quality_gate": { "blocking_gaps": [], "category_confidence": "medium", "compile_status": "ready_for_review", "five_assets_present": true, "install_sandbox_verified": true, "missing_evidence": [], "next_action": "publish to Doramagic.ai project surfaces", "prompt_preview_boundary_ok": true, "publish_status": "publishable", "quick_start_verified": true, "repo_clone_verified": true, "repo_commit": "bb3a8156c755094c0f42fb9b0685ecd66ebf4991", "repo_inspection_error": null, "repo_inspection_files": [ "package.json", "README.md", "docs/README.zh-CN.md", "docs/README.ja.md", "src/index.ts", "src/installer.ts", "src/cli.ts", "src/manifest/schema.ts", "src/manifest/parser.ts", "src/hosts/kiro.ts", "src/hosts/augment.ts", "src/hosts/trae.ts", "src/hosts/qwen-code.ts", "src/hosts/github-copilot.ts", "src/hosts/claude-desktop.ts", "src/hosts/roo-code.ts", "src/hosts/kimi.ts", "src/hosts/index.ts", "src/hosts/tabnine.ts", "src/hosts/openclaw.ts", "src/hosts/gemini.ts", "src/hosts/kilo-code.ts", "src/hosts/types.ts", "src/hosts/opencode.ts", "src/hosts/vibe.ts", "src/hosts/README.md", "src/hosts/codex.ts", "src/hosts/claude-code.ts", "src/hosts/windsurf.ts", "src/hosts/cursor.ts", "src/source/git.ts", "src/source/local.ts", "src/source/infer-name.ts", "src/source/index.ts", "src/source/http-file.ts", "src/source/inline.ts", "src/source/expand-directory.ts", "src/utils/detect-hosts.ts", "src/utils/summary.ts", "src/utils/fs.ts" ], "repo_inspection_verified": true, "review_reasons": [ "community_discussion_evidence_below_public_threshold" ], "tag_count_ok": true, "unsupported_claims": [] }, "schema_version": "0.1", "user_assets": { "ai_context_pack": { "asset_id": "ai_context_pack", "filename": "AI_CONTEXT_PACK.md", "markdown": "# agent-add - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 agent-add 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`tests/fixtures/skill/my-skill/SKILL.md` Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`tests/fixtures/skill/my-skill/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `npx -y agent-add \\` 证据：`README.md` Claim：`clm_0005` supported 0.86, `clm_0006` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86 等\n- `npx -y agent-add --host claude-code --mcp 'https://github.com/modelcontextprotocol/servers.git#.mcp.json'` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `npx -y agent-add --host cursor --mcp 'https://github.com/modelcontextprotocol/servers.git#.mcp.json'` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `npx -y agent-add --host codex --mcp 'https://github.com/modelcontextprotocol/servers.git#.mcp.json'` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `npx -y agent-add --mcp 'https://github.com/modelcontextprotocol/servers.git#.mcp.json'` 证据：`README.md` Claim：`clm_0009` supported 0.86\n- `npx -y agent-add --host claude-code \\` 证据：`README.md` Claim：`clm_0006` supported 0.86, `clm_0010` supported 0.86\n- `npx -y agent-add --host cursor \\` 证据：`README.md` Claim：`clm_0007` supported 0.86, `clm_0011` supported 0.86\n- `npx -y agent-add [OPTIONS]` 证据：`README.md` Claim：`clm_0012` supported 0.86\n- `npx -y agent-add --mcp '{\"playwright\":{\"command\":\"npx\",\"args\":[\"-y\",\"@playwright/mcp\"]}}'` 证据：`README.md` Claim：`clm_0013` supported 0.86\n- `npx -y agent-add --mcp '{\"mcpServers\":{\"playwright\":{\"command\":\"npx\",\"args\":[\"-y\",\"@playwright/mcp\"]}}}'` 证据：`README.md` Claim：`clm_0014` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`tests/fixtures/skill/my-skill/SKILL.md` Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`tests/fixtures/skill/my-skill/SKILL.md` Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0005` supported 0.86, `clm_0006` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`tests/fixtures/skill/my-skill/SKILL.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`tests/fixtures/skill/my-skill/SKILL.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0016` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0017` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`tests/fixtures/skill/my-skill/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：104\n- 重要文件覆盖：36/104\n- 证据索引条目：36\n- 角色 / Skill 条目：1\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 agent-add 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 agent-add 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 agent-add 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 1 个角色 / Skill / 项目文档条目。\n\n- **my-skill**（skill）：A test skill for scenario testing. 激活提示：当用户任务与“my-skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`tests/fixtures/skill/my-skill/SKILL.md`\n\n## 证据索引\n\n- 共索引 36 条证据。\n\n- **agent-add**（documentation）：Install MCP, Skills, slash commands, sub-agents and more into any AI tool like Claude Code, Cursor, etc. 证据：`README.md`\n- **Host Capability Matrix**（documentation）：This file is the single source of truth for all host adapter configurations in agent-add . Every adapter in src/hosts/ .ts must match the paths and capabilities documented here. 证据：`src/hosts/README.md`\n- **bad-skill**（documentation）：This directory is intentionally missing a SKILL.md file. 证据：`tests/fixtures/skill/bad-skill/README.md`\n- **Package**（package_manifest）：{ \"name\": \"agent-add\", \"version\": \"1.1.0\", \"description\": \"Cross-host AI Agent Pack installer — install MCP, Skill, Prompt, Command, Sub-agent in one command\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/pea3nut/agent-add.git\" }, \"bugs\": { \"url\": \"https://github.com/pea3nut/agent-add/issues\" }, \"homepage\": \"https://github.com/pea3nut/agent-add\", \"bin\": { \"agent-add\": \"bin/agent-add.js\" }, \"files\": \"bin\", \"docs\", \"dist\" , \"scripts\": { \"build\": \"tsup\", \"dev\": \"tsup --watch\", \"prepublishOnly\": \"npm run build\", \"test\": \"vitest run tests/unit tests/integration\", \"test:contract\": \"vitest run tests/contract\", \"test:integration\": \"vitest run tests/integration\", \"lint\": \"tsc --noEmit\",… 证据：`package.json`\n- **Skill: my-skill**（skill_instruction）：This is a test skill used in scenario tests. 证据：`tests/fixtures/skill/my-skill/SKILL.md`\n- **License**（source_file）：Mozilla Public License Version 2.0 ================================== 证据：`LICENSE`\n- **agent-add**（documentation）：MCP、Skill、スラッシュコマンド、サブエージェントなどを Claude Code や Cursor などの AI ツールにワンコマンドでインストール 证据：`docs/README.ja.md`\n- **agent-add**（documentation）：一条命令，将 MCP、Skill、斜杆命令、子代理等安装到任意 AI 工具，如 Claude Code、Cursor 等 证据：`docs/README.zh-CN.md`\n- **agent-add**（documentation）：Cross-host AI Agent Pack installer CLI tool. Install MCP, Skill, Prompt, Command, Sub-agent assets into different AI agent hosts Cursor, Claude Code, Claude Desktop, etc. with a single command. 证据：`vibe/system-prompt.md`\n- **Scenario Run Config**（documentation）：config: The CLI binary is pre-built at bin/agent-add.js relative to the project root. Every feature file sets PROJECT ROOT=$ git rev-parse --show-toplevel in a Background block. Run each CLI step with: node \"$PROJECT ROOT/bin/agent-add.js\" 证据：`tests/features/scenario-run-config.md`\n- **Command A**（documentation）：Command A test batch command a 证据：`tests/fixtures/command/batch/cmd-a.md`\n- **Command B**（documentation）：Command B test batch command b 证据：`tests/fixtures/command/batch/cmd-b.md`\n- **Command C**（documentation）：Command C test batch command c 证据：`tests/fixtures/command/batch/cmd-c.md`\n- **my-command**（documentation）：This is a test command used in scenario tests. Run this command to perform a test action. 证据：`tests/fixtures/command/my-command.md`\n- **My Test Prompt v2**（documentation）：Always respond concisely and professionally. Use bullet points for lists. Include code examples when relevant. 证据：`tests/fixtures/prompt/my-prompt-v2.md`\n- **My Test Prompt**（documentation）：Always respond concisely. Use bullet points for lists. 证据：`tests/fixtures/prompt/my-prompt.md`\n- **Code Review Prompt**（documentation）：When reviewing code: - Check for security issues - Verify error handling 证据：`tests/fixtures/prompt/second-prompt.md`\n- **my-agent**（documentation）：This is a test sub-agent used in scenario tests. 证据：`tests/fixtures/sub-agent/my-agent.md`\n- **Task: Verify and Update src/hosts/README.md**（documentation）：Task: Verify and Update src/hosts/README.md 证据：`vibe/tasks/verify-host-readme.md`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2022\", \"module\": \"commonjs\", \"moduleResolution\": \"node\", \"lib\": \"ES2022\" , \"strict\": true, \"esModuleInterop\": true, \"skipLibCheck\": true, \"outDir\": \"dist\", \"rootDir\": \"src\", \"declaration\": true, \"declarationMap\": true, \"sourceMap\": true, \"resolveJsonModule\": true }, \"include\": \"src/ / \" , \"exclude\": \"node modules\", \"dist\", \"tests\" } 证据：`tsconfig.json`\n- **Manifest**（structured_config）：{ \"name\": \"agent-add/dev-pack\", \"assets\": { \"type\": \"skill\", \"source\": \"https://github.com/pea3nut/scenario-test.git skills/scenario-test\" }, { \"type\": \"command\", \"source\": \"https://github.com/pea3nut/scenario-test.git commands/scenario-exec.md\" }, { \"type\": \"subAgent\", \"source\": \"https://github.com/pea3nut/scenario-test.git agents/scenario-case-runner.md\" }, { \"type\": \"command\", \"source\": \"./vibe/tasks/verify-host-readme.md\" }, { \"type\": \"prompt\", \"source\": \"./vibe/system-prompt.md\" } } 证据：`vibe/manifest.json`\n- **Svc A**（structured_config）：{\"svc-a\":{\"command\":\"echo\",\"args\": \"a\" }} 证据：`tests/fixtures/mcp/batch/svc-a.json`\n- **Svc B**（structured_config）：{\"svc-b\":{\"command\":\"echo\",\"args\": \"b\" }} 证据：`tests/fixtures/mcp/batch/svc-b.json`\n- **Filesystem**（structured_config）：{ \"command\": \"npx\", \"args\": \"@anthropic/mcp-filesystem@latest\", \"/tmp\" , \"env\": {} } 证据：`tests/fixtures/mcp/filesystem.json`\n- **Playwright With Env**（structured_config）：{ \"command\": \"npx\", \"args\": \"@playwright/mcp@latest\" , \"env\": { \"BROWSER\": \"chromium\", \"HEADLESS\": \"true\" } } 证据：`tests/fixtures/mcp/playwright-with-env.json`\n- **Playwright**（structured_config）：{ \"command\": \"npx\", \"args\": \"@playwright/mcp@latest\" , \"env\": {} } 证据：`tests/fixtures/mcp/playwright.json`\n- **Codex Manifest**（structured_config）：{ \"name\": \"test/codex-pack\", \"assets\": { \"type\": \"mcp\", \"source\": \"./fixtures/mcp/playwright.json\" }, { \"type\": \"prompt\", \"source\": \"./fixtures/prompt/my-prompt.md\" }, { \"type\": \"skill\", \"source\": \"./fixtures/skill/my-skill\" }, { \"type\": \"command\", \"source\": \"./fixtures/command/my-command.md\" }, { \"type\": \"subAgent\", \"source\": \"./fixtures/sub-agent/my-agent.md\" } } 证据：`tests/fixtures/pack/codex-manifest.json`\n- **Manifest**（structured_config）：{ \"name\": \"test/test-pack\", \"version\": \"0.1.0\", \"description\": \"A test pack covering all asset types for scenario testing\", \"assets\": { \"type\": \"mcp\", \"name\": \"playwright\", \"source\": \"./fixtures/mcp/playwright.json\" }, { \"type\": \"skill\", \"name\": \"my-skill\", \"source\": \"./fixtures/skill/my-skill\" }, { \"type\": \"prompt\", \"name\": \"my-prompt\", \"source\": \"./fixtures/prompt/my-prompt.md\" }, { \"type\": \"command\", \"name\": \"my-command\", \"source\": \"./fixtures/command/my-command.md\" }, { \"type\": \"subAgent\", \"name\": \"my-agent\", \"source\": \"./fixtures/sub-agent/my-agent.md\" } } 证据：`tests/fixtures/pack/manifest.json`\n- **Multi Source Manifest**（structured_config）：{ \"name\": \"test/multi-source-pack\", \"assets\": { \"type\": \"mcp\", \"source\": \"./fixtures/mcp/playwright.json\", \"./fixtures/mcp/filesystem.json\" }, { \"type\": \"prompt\", \"source\": \"./fixtures/prompt/my-prompt.md\", \"./fixtures/prompt/second-prompt.md\" } } 证据：`tests/fixtures/pack/multi-source-manifest.json`\n- **Logs**（source_file）：Logs logs .log npm-debug.log yarn-debug.log yarn-error.log lerna-debug.log 证据：`.gitignore`\n- **!/usr/bin/env node**（source_file）：!/usr/bin/env node require '../dist/index.js' ; 证据：`bin/agent-add.js`\n- **Install MCP from JSON config file**（source_file）：import { Command } from 'commander'; import select from '@inquirer/select'; import { getHost, getValidHostIds } from './hosts/index.js'; import { detectHosts, isHostDetected } from './utils/detect-hosts.js'; import { runInstaller } from './installer.js'; import { printSummary } from './utils/summary.js'; import type { CliInput } from './installer.js'; 证据：`src/cli.ts`\n- **Index**（source_file）：import { createProgram } from './cli.js'; 证据：`src/index.ts`\n- **Installer**（source_file）：import fs from 'fs'; import path from 'path'; import type { AssetType, HostConfig } from './hosts/types.js'; import type { AssetDescriptor } from './manifest/schema.js'; import type { InstallJob, InstallResult, ResolvedSource } from './assets/types.js'; import { resolveSource } from './source/index.js'; import { inferName } from './source/infer-name.js'; import { expandDirectory } from './source/expand-directory.js'; import { loadManifest } from './manifest/parser.js'; import { mcpHandler } from './assets/mcp.js'; import { skillHandler } from './assets/skill.js'; import { promptHandler } from './assets/prompt.js'; import { commandHandler } from './assets/command.js'; import { subAgentHandle… 证据：`src/installer.ts`\n- **Tsup.Config**（source_file）：import { defineConfig } from 'tsup'; 证据：`tsup.config.ts`\n- **Vitest.Config**（source_file）：import { defineConfig } from 'vitest/config'; 证据：`vitest.config.ts`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `src/hosts/README.md`, `tests/fixtures/skill/bad-skill/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `src/hosts/README.md`, `tests/fixtures/skill/bad-skill/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **Introduction**：importance `high`\n - source_paths: README.md, package.json\n- **Getting Started**：importance `high`\n - source_paths: bin/agent-add.js, src/cli.ts\n- **System Architecture**：importance `high`\n - source_paths: src/index.ts, src/installer.ts, src/hosts/index.ts, src/source/index.ts\n- **Host Integration**：importance `high`\n - source_paths: src/hosts/types.ts, src/hosts/index.ts, src/hosts/cursor.ts, src/hosts/claude-code.ts, src/hosts/windsurf.ts\n- **Source Resolution**：importance `high`\n - source_paths: src/source/index.ts, src/source/git.ts, src/source/http-file.ts, src/source/local.ts, src/source/inline.ts\n- **Asset Types**：importance `high`\n - source_paths: src/manifest/schema.ts, src/manifest/parser.ts, vibe/manifest.json\n- **Manifest System**：importance `medium`\n - source_paths: src/manifest/schema.ts, src/manifest/parser.ts\n- **CLI Interface**：importance `high`\n - source_paths: src/cli.ts, bin/agent-add.js\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `bb3a8156c755094c0f42fb9b0685ecd66ebf4991`\n- inspected_files: `package.json`, `README.md`, `docs/README.zh-CN.md`, `docs/README.ja.md`, `src/index.ts`, `src/installer.ts`, `src/cli.ts`, `src/manifest/schema.ts`, `src/manifest/parser.ts`, `src/hosts/kiro.ts`, `src/hosts/augment.ts`, `src/hosts/trae.ts`, `src/hosts/qwen-code.ts`, `src/hosts/github-copilot.ts`, `src/hosts/claude-desktop.ts`, `src/hosts/roo-code.ts`, `src/hosts/kimi.ts`, `src/hosts/index.ts`, `src/hosts/tabnine.ts`, `src/hosts/openclaw.ts`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：v1.1.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.1.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_5c106a51ec5d4f999b8bcef8e68a89ec | https://github.com/pea3nut/agent-add/releases/tag/1.1.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 社区讨论暴露的待验证问题：I built a CLI that installs MCP, skills, prompts, commands and sub ...\n\n- Trigger: I built a CLI that installs MCP, skills, prompts, commands and sub ... 6 Apr 2026 · Project & Supported Tools. The source code is hosted on GitHub: https://github.com/pea3nut/agent-add ... r/mcp - I built a tool that auto- ...\n- Host AI rule: Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- Why it matters: 这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- Evidence: social_signal:reddit | ssig_6d54ef81557a451081be71b052d0e31b | https://www.reddit.com/r/ClaudeAI/comments/1sdrk6k/i_built_a_cli_that_installs_mcp_skills_prompts/ | I built a CLI that installs MCP, skills, prompts, commands and sub ...\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | host_targets=mcp_host, claude, claude_code, cursor, chatgpt\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n", "summary": "给宿主 AI 的上下文和工作边界。", "title": "AI Context Pack / 带给我的 AI" }, "boundary_risk_card": { "asset_id": "boundary_risk_card", "filename": "BOUNDARY_RISK_CARD.md", "markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：pea3nut/agent-add\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host, claude, claude_code, cursor, chatgpt\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 来源证据：v1.1.0（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 社区讨论暴露的待验证问题：I built a CLI that installs MCP, skills, prompts, commands and sub ...（medium）：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- 可能修改宿主 AI 配置（medium）：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n", "summary": "安装、权限、验证和推荐前风险。", "title": "Boundary & Risk Card / 边界与风险卡" }, "human_manual": { "asset_id": "human_manual", "filename": "HUMAN_MANUAL.md", "markdown": "# https://github.com/pea3nut/agent-add 项目说明书\n\n生成时间：2026-05-15 10:35:27 UTC\n\n## 目录\n\n- [Introduction](#introduction)\n- [Getting Started](#getting-started)\n- [System Architecture](#system-architecture)\n- [Host Integration](#host-integration)\n- [Source Resolution](#source-resolution)\n- [Asset Types](#asset-types)\n- [Manifest System](#manifest-system)\n- [CLI Interface](#cli-interface)\n- [Testing](#testing)\n- [Project Configuration](#configuration)\n\n\n\n## Introduction\n\n### 相关页面\n\n相关主题：[Getting Started](#getting-started), [System Architecture](#system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n- [package.json](https://github.com/pea3nut/agent-add/blob/main/package.json)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n- [src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n- [src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n- [src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n- [vibe/system-prompt.md](https://github.com/pea3nut/agent-add/blob/main/vibe/system-prompt.md)\n
\n\n# Introduction\n\nagent-add is a unified CLI tool that streamlines the installation and management of AI coding agent assets across multiple host environments. It eliminates the need to manually configure MCP servers, skills, prompts, commands, and sub-agents by automating asset discovery, validation, and deployment to the appropriate host-specific directories.\n\n## Purpose and Scope\n\nagent-add addresses the fragmented ecosystem of AI coding assistants by providing a single command-line interface that works with 18 different host environments. Rather than maintaining separate installation instructions for Cursor, Claude Code, Windsurf, and other tools, developers and asset distributors can use agent-add to distribute assets universally.\n\n**Core capabilities include:**\n\n- **Asset Installation**: Install MCP servers, skills, prompts, commands, and sub-agents from local paths, Git URLs, or HTTP endpoints\n- **Host Abstraction**: Automatic detection and adaptation for each host's unique configuration format and directory structure\n- **Pack Distribution**: Bundle multiple assets into a single JSON manifest for team-wide distribution\n- **Atomic Operations**: Safe file writes using temp file + rename patterns to prevent corruption\n- **Idempotent Updates**: Marker-based append strategy ensures repeated installations do not create duplicates\n\n资料来源：[README.md:1-50](https://github.com/pea3nut/agent-add/blob/main/README.md)\n\n## Supported Hosts\n\nagent-add supports the following 18 AI coding host environments:\n\n| Host ID | Configuration Format | Install Directory |\n|---------|---------------------|-------------------|\n| `cursor` | JSON | `.cursor/` |\n| `claude-code` | JSON | `.claude/` |\n| `claude-desktop` | JSON | `~/Library/Application Support/Claude/` |\n| `windsurf` | JSON | `.windsurf/rules/` |\n| `github-copilot` | JSON | `.github/copilot/` |\n| `gemini` | JSON | `.gemini/` |\n| `roo-code` | JSON | `.roo/rules/` |\n| `kilo-code` | JSON | `.kilocode/` |\n| `qwen-code` | JSON | `.qwen/` |\n| `opencode` | JSON | `.opencode/` |\n| `augment` | JSON | `.augment/` |\n| `kiro` | JSON | `.kiro/` |\n| `tabnine` | JSON | `.tabnine/` |\n| `kimi` | JSON | `.kimi/` |\n| `trae` | JSON | `.trae/` |\n| `openclaw` | JSON | `.openclaw/` |\n| `codex` | TOML | `.codex/` |\n| `vibe` | TOML | `.vibe/` |\n\n资料来源：[vibe/system-prompt.md:30-35](https://github.com/pea3nut/agent-add/blob/main/vibe/system-prompt.md)\n\n## Supported Asset Types\n\nagent-add manages five distinct asset types, each with host-specific installation strategies:\n\n| Asset Type | Description | Install Behavior |\n|------------|-------------|------------------|\n| `mcp` | Model Context Protocol server configurations | JSON shallow merge or TOML array append |\n| `skill` | Reusable agent skill directories | Recursive directory copy |\n| `prompt` | System prompts or rule files | Append-with-marker or create-file-in-dir |\n| `command` | Slash commands | Create in commands directory |\n| `subAgent` | Sub-agent configurations | Create in agents directory |\n\n资料来源：[src/installer.ts:1-50](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n\n## Architecture Overview\n\nThe codebase follows a layered architecture pattern with clear separation of concerns:\n\n```mermaid\ngraph TD\n A[CLI Input] --> B[CLI Parser
src/cli.ts]\n B --> C[Installer Core
src/installer.ts]\n C --> D[Source Resolution
src/source/]\n D --> E[Validation]\n E --> F[Host Adapter
src/hosts/]\n F --> G[Asset Handler
src/assets/]\n G --> H[Filesystem]\n \n I[Pack Manifest] -.-> C\n J[18 Host Adapters] -.-> F\n K[5 Asset Handlers] -.-> G\n```\n\n**Layer responsibilities:**\n\n| Layer | Module | Responsibility |\n|-------|--------|----------------|\n| Input | `src/cli.ts` | Commander.js argument parsing, TTY detection, interactive host selection |\n| Core | `src/installer.ts` | Orchestration: input parsing → capability check → source resolution → validation → handler execution → summary |\n| Resolution | `src/source/` | Local file access, Git URL handling, HTTP fetching, inline content parsing |\n| Adaptation | `src/hosts/` | Host-specific directory paths, capability declarations, write strategies |\n| Execution | `src/assets/` | Type-specific installation logic (MCP merge, skill copy, prompt append, etc.) |\n\n资料来源：[vibe/system-prompt.md:45-65](https://github.com/pea3nut/agent-add/blob/main/vibe/system-prompt.md)\n\n## Core Data Flow\n\nThe installation pipeline follows a sequential process from CLI invocation to filesystem write:\n\n```mermaid\ngraph LR\n A[CLI flags / --pack Manifest] --> B[Explicit flag capability check
exit 2 if unsupported]\n B --> C[AssetDescriptor[]
type + source]\n C --> D[ResolvedSource[]
localPath + tempDir]\n D --> E[InstallJob[]
skip unsupported assets]\n E --> F[InstallResult[]
written / exists / updated / conflict / skipped / error]\n F --> G[Summary output]\n```\n\n**Processing stages:**\n\n1. **Input Collection**: Gather all asset sources from CLI flags and pack manifests\n2. **Capability Validation**: Verify each asset type is supported by the target host (exit 2 if explicit flag unsupported)\n3. **Source Resolution**: Convert sources to local file paths (git clone, http download, inline temp files)\n4. **Asset Validation**: Validate file existence, format compliance, and required metadata\n5. **Job Creation**: Build installation jobs, skipping assets with unsupported capabilities\n6. **Execution**: Dispatch to appropriate asset handler based on type\n7. **Result Reporting**: Output summary with status for each asset\n\n资料来源：[src/cli.ts:1-80](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n\n## Write Strategies\n\nDifferent asset types use different write strategies based on host capabilities:\n\n```mermaid\ngraph TD\n A[Asset Type] --> B{Write Strategy}\n B --> C[append-with-marker]\n B --> D[create-file-in-dir]\n B --> E[atomic-json-merge]\n B --> F[directory-copy]\n \n C --> G[HTML comment markers
]\n D --> H[Create new file
Skip if exists]\n E --> I[Temp file + rename
JSON shallow merge]\n F --> J[Recursive copy
SKILL.md required]\n```\n\n| Strategy | Used By | Behavior |\n|----------|---------|----------|\n| `append-with-marker` | Prompt (Cursor, Claude Code) | Wraps content in HTML comment markers, idempotent append |\n| `create-file-in-dir` | Prompt (Windsurf, Roo Code), Command, Sub-agent | Creates `.md` in rules/commands/agents directory |\n| `atomic-json-merge` | MCP (JSON hosts) | Shallow merge with temp file + rename for safety |\n| `toml-array-append` | MCP (Codex, Vibe) | Append to `[[mcp_servers]]` array |\n| `directory-copy` | Skill | Recursive copy to host's skills directory |\n\n资料来源：[src/installer.ts:50-120](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n\n## Source Resolution\n\nagent-add accepts assets from multiple source types with automatic detection:\n\n| Source Format | Example | Name Inference |\n|---------------|---------|---------------|\n| Git URL + `#path` | `https://github.com/user/repo.git#skills/pdf` | Last segment after `#` (strip extension) |\n| Git URL without `#` | `https://github.com/user/playwright.git` | Repo name (strip `.git`) |\n| Local path | `./mcps/playwright.json` | Filename (strip extension) |\n| HTTP URL | `https://example.com/config.json` | Filename (strip extension) |\n| Inline JSON | `{\"playwright\":{...}}` | Top-level key as name |\n| Inline Markdown | `# Code Review\\n\\nRules...` | First `# Heading` in kebab-case |\n\n资料来源：[src/source/infer-name.ts:1-50](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n\n## Installation and Usage\n\n### Quick Install\n\n```bash\n# Install a single MCP server\nnpx -y agent-add --host cursor --mcp 'https://github.com/modelcontextprotocol/servers.git#mcp/playwright'\n\n# Install multiple assets\nnpx -y agent-add --host cursor \\\n --mcp './configs/mcp.json' \\\n --skill './skills/pdf' \\\n --prompt './rules/code-review.md'\n\n# Install from a pack manifest\nnpx -y agent-add --host claude-code --pack './manifests/frontend-pack.json'\n```\n\n### CLI Options\n\n| Flag | Description | Can Repeat |\n|------|-------------|------------|\n| `--host ` | Target host ID (required in CI, optional in TTY) | No |\n| `--pack ` | Install from a pack manifest | Yes |\n| `--mcp ` | Install MCP server configuration | Yes |\n| `--skill ` | Install skill directory | Yes |\n| `--prompt ` | Install prompt/rule file | Yes |\n| `--command ` | Install slash command | Yes |\n| `--sub-agent ` | Install sub-agent file | Yes |\n\n资料来源：[src/cli.ts:40-60](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n\n## Key Design Decisions\n\nThe architecture reflects several intentional design choices:\n\n**Atomic JSON Writes**: MCP configuration uses temp file + rename pattern to prevent corruption from interrupted writes. 资料来源：[vibe/system-prompt.md:70-72](https://github.com/pea3nut/agent-add/blob/main/vibe/system-prompt.md)\n\n**Marker-Based Idempotency**: Prompt append mode uses `` HTML comment markers, ensuring repeated installations update existing blocks rather than creating duplicates.\n\n**Explicit Flag Rejection**: When using explicit flags like `--mcp`, agent-add validates host capability and exits with code 2 if unsupported. Pack sources skip unsupported assets silently instead.\n\n**Non-TTY Strict Mode**: CI environments must explicitly specify `--host` to prevent ambiguous behavior in automated pipelines.\n\n**Inline Content Support**: Prompt/Command/Sub-agent assets support inline content via newline detection, while MCP supports inline JSON via brace detection. HTTP and inline sources are explicitly rejected for Skill type assets.\n\n资料来源：[src/installer.ts:80-100](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n\n## Project Structure\n\n```\nagent-add/\n├── bin/\n│ └── agent-add.js # Compiled entry point\n├── src/\n│ ├── index.ts # Main entry, program creation\n│ ├── cli.ts # Commander definition + TTY detection\n│ ├── installer.ts # Orchestration core\n│ ├── hosts/ # Host adapter layer (18 hosts)\n│ │ ├── types.ts # HostAdapter, AssetCapability types\n│ │ ├── index.ts # Host registry (Map)\n│ │ └── .ts # Per-host adapter implementations\n│ ├── assets/ # 5 asset type handlers\n│ │ ├── mcp.ts # JSON/TOML MCP handling\n│ │ ├── skill.ts # Directory copy + validation\n│ │ ├── prompt.ts # Append or create-file strategy\n│ │ ├── command.ts # Command file creation\n│ │ └── subAgent.ts # Sub-agent file creation\n│ ├── source/ # Source resolution\n│ │ ├── infer-name.ts # Asset name inference\n│ │ └── expand-directory.ts # Directory expansion\n│ ├── manifest/ # Pack manifest handling\n│ │ └── parser.ts # Zod schema validation\n│ └── utils/ # Shared utilities\n│ └── unwrap-mcp-servers.ts\n├── tests/\n│ ├── unit/ # Unit tests per module\n│ ├── features/ # Gherkin scenario tests\n│ └── fixtures/ # Static test fixtures\n└── vibe/ # Development assets\n ├── manifest.json # Dev pack manifest\n └── tasks/ # AI task definitions\n```\n\n资料来源：[README.md:80-100](https://github.com/pea3nut/agent-add/blob/main/README.md)\n\n## Development\n\n```bash\n# Setup\nnpm install\nnpm run build\n\n# Run tests\nnpm test # All unit + integration tests\nnpm run test:contract # CLI black-box contract tests only\nnpx vitest run tests/unit/hosts/cursor.test.ts # Single file\n\n# Run scenario tests (Gherkin)\n# Use /scenario-exec command in your AI tool:\n/scenario-exec tests/features/core\n/scenario-exec tests/features/host\n```\n\n资料来源：[README.md:100-120](https://github.com/pea3nut/agent-add/blob/main/README.md)\n\n---\n\n\n\n## Getting Started\n\n### 相关页面\n\n相关主题：[Introduction](#introduction), [CLI Interface](#cli-interface)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n- [src/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/index.ts)\n- [src/manifest/parser.ts](https://github.com/pea3nut/agent-add/blob/main/src/manifest/parser.ts)\n- [src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n- [src/source/expand-directory.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/expand-directory.ts)\n
\n\n# Getting Started\n\n## Overview\n\n`agent-add` is a CLI tool that automates the installation of AI agent assets—including MCP servers, skills, prompts, commands, and sub-agents—across 18 different AI coding assistant hosts. It provides a unified interface for installing community assets from Git repositories, local paths, HTTP URLs, or inline content.\n\nThe tool handles host-specific installation logic, validates assets before installation, and supports batch installation via pack manifests. 资料来源：[src/index.ts:1-7]()\n\n## Prerequisites\n\n- **Node.js**: v18 or later\n- **npm** or **pnpm** for package management\n- Access to the target host's configuration directory\n\n## Installation\n\n### Using npx (Recommended for One-time Use)\n\n```bash\nnpx -y agent-add --help\n```\n\n### Global Installation\n\n```bash\nnpm install -g agent-add\n# or\npnpm add -g agent-add\n```\n\n### Local Installation\n\n```bash\nnpm install\nnpm run build\n```\n\nThe CLI entry point is located at `bin/agent-add.js`. 资料来源：[README.md](https://github.com/pea3nut/agent-add)\n\n## Basic Usage\n\n### Interactive Mode\n\nWhen run in a TTY environment without specifying a host, `agent-add` prompts for target selection:\n\n```bash\nnpx -y agent-add\n```\n\nThe CLI detects available hosts in the current directory and presents an interactive selection menu. 资料来源：[src/cli.ts:56-77]()\n\n### Non-interactive Mode\n\nIn CI environments or when a host must be specified explicitly:\n\n```bash\nnpx -y agent-add --host [asset-flags...]\n```\n\nIf `--host` is omitted in non-TTY environments, the CLI exits with error code 2. 资料来源：[src/cli.ts:46-55]()\n\n## Supported Hosts\n\nThe following 18 hosts are supported:\n\n| Host ID | Type | Notes |\n|---------|------|-------|\n| `cursor` | JSON | Cursor IDE |\n| `claude-code` | Markdown | Claude Code CLI |\n| `claude-desktop` | JSON | Claude Desktop |\n| `windsurf` | JSON | Windsurf IDE |\n| `github-copilot` | JSON | GitHub Copilot |\n| `gemini` | JSON | Google Gemini |\n| `roo-code` | JSON | Roo Code |\n| `kilo-code` | JSON | Kilo Code |\n| `qwen-code` | JSON | Qwen Code |\n| `opencode` | JSON | OpenCode |\n| `augment` | JSON | Augment |\n| `kiro` | JSON | Kiro |\n| `tabnine` | JSON | Tabnine |\n| `kimi` | JSON | Kimi |\n| `trae` | JSON | Trae |\n| `openclaw` | JSON | OpenClaw |\n| `codex` | TOML | Codex |\n| `vibe` | TOML | Vibe |\n\n资料来源：[README.md](https://github.com/pea3nut/agent-add)\n\n## Asset Types\n\n### 1. MCP Server\n\nInstalls Model Context Protocol server configurations.\n\n```bash\nagent-add --host cursor --mcp 'https://github.com/modelcontextprotocol/servers.git#mcp/playwright'\n```\n\n### 2. Skill\n\nInstalls reusable agent skill directories containing `SKILL.md`.\n\n```bash\nagent-add --host cursor --skill './my-skill'\nagent-add --host cursor --skill 'https://github.com/anthropics/skills.git#skills/webapp-testing'\n```\n\n> **Note**: Skills must target directory sources (local paths or Git URLs). Inline content or direct HTTP(S) URLs are not supported. 资料来源：[src/installer.ts:80-84]()\n\n### 3. Prompt\n\nInstalls system prompts or rule files.\n\n```bash\nagent-add --host claude-code --prompt 'https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/nextjs-react-tailwind/.cursorrules'\n```\n\n### 4. Command\n\nInstalls slash commands for AI assistants.\n\n```bash\nagent-add --host cursor --command 'https://github.com/wshobson/commands.git#tools/security-scan.md'\n```\n\n### 5. Sub-agent\n\nInstalls specialized agent configurations.\n\n```bash\nagent-add --host cursor --sub-agent 'https://github.com/VoltAgent/awesome-claude-code-subagents.git#categories/01-core-development/backend-developer.md'\n```\n\n## Source Specification\n\n`agent-add` supports multiple source types for each asset:\n\n| Source Type | Syntax Example | Name Inference |\n|-------------|-----------------|----------------|\n| Git URL with path | `...git#skills/pdf` | Last segment after `#`, stripped extension |\n| Git URL without path | `...playwright.git` | Repository name (strip `.git`) |\n| Local path | `./mcps/playwright.json` | Filename (strip extension) |\n| HTTP URL | `https://example.com/config.json` | Filename (strip extension) |\n| Inline JSON | `{\"playwright\":{...}}` | Single top-level key |\n| Inline Markdown | `# Heading\\nContent` | First `# Heading`, kebab-cased |\n\n资料来源：[src/source/infer-name.ts:1-41]()\n\n## Pack Manifests\n\nBundles multiple assets for distribution via a JSON manifest:\n\n```json\n{\n \"name\": \"my-team/frontend-pack\",\n \"assets\": [\n { \"type\": \"mcp\", \"source\": \"https://github.com/modelcontextprotocol/servers.git#.mcp.json\" },\n { \"type\": \"skill\", \"source\": \"https://github.com/anthropics/skills.git#skills/pdf\" },\n { \"type\": \"prompt\", \"source\": \"https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/nextjs-react-tailwind/.cursorrules\" }\n ]\n}\n```\n\nInstall with:\n\n```bash\nagent-add --host cursor --pack './my-pack.json'\n```\n\nPack names must follow `namespace/pack-name` format with only `[a-zA-Z0-9_-]` characters. 资料来源：[src/manifest/parser.ts:1-31]()\n\n## Workflow Diagram\n\n```mermaid\ngraph TD\n A[CLI Input] --> B{Source Type Detection}\n B -->|Git URL| C[Clone to temp]\n B -->|Local Path| D[Resolve absolute path]\n B -->|HTTP URL| E[Download to temp]\n B -->|Inline| F[Write temp file]\n C --> G[Validate Asset]\n D --> G\n E --> G\n F --> G\n G -->|Invalid| H[Exit 2 with error]\n G -->|Valid| I{Check Host Capability}\n I -->|Unsupported| J[Skip asset]\n I -->|Supported| K[Install to Host]\n K --> L[Print Summary]\n J --> L\n```\n\n## Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| 0 | Success (all assets installed or already up-to-date) |\n| 1 | Partial failure (conflicts or errors occurred) |\n| 2 | Fatal error (invalid input, missing host, validation failure) |\n\n资料来源：[src/cli.ts:27-34]()\n\n## Examples\n\n### Install MCP Server from GitHub\n\n```bash\nnpx -y agent-add --host cursor --mcp 'https://github.com/modelcontextprotocol/servers.git#mcp/playwright'\n```\n\n### Install Multiple Assets\n\n```bash\nagent-add --host claude-code \\\n --mcp 'https://github.com/modelcontextprotocol/servers.git#mcp/playwright' \\\n --prompt 'https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/nextjs-react-tailwind/.cursorrules' \\\n --command 'https://github.com/wshobson/commands.git#tools/security-scan.md'\n```\n\n### Install Pack Manifest\n\n```bash\nagent-add --host cursor --pack 'https://github.com/VoltAgent/awesome-claude-code-subagents.git#manifests/backend-dev.json'\n```\n\n### Inline MCP Configuration\n\n```bash\nagent-add --host cursor --mcp '{\"playwright\":{\"command\":\"npx\",\"args\":[\"@playwright/mcp@latest\"]}}'\n```\n\n## Directory Expansion\n\nFor directories containing multiple assets, `agent-add` automatically expands them:\n\n```bash\nagent-add --host cursor --mcp './mcp-servers/'\n```\n\nEach `.json` file in the directory becomes a separate MCP asset. For skills, it scans for subdirectories containing `SKILL.md`. 资料来源：[src/source/expand-directory.ts:1-43]()\n\n## Validation\n\nBefore installation, `agent-add` validates:\n\n- **MCP**: File must exist and have `.json` extension\n- **Skill**: Directory must contain `SKILL.md`; cannot use inline or HTTP sources\n- **Prompt/Command/Sub-agent**: File must exist\n\n资料来源：[src/installer.ts:78-107]()\n\n## Next Steps\n\n- Review the [Asset Developer Guide](https://github.com/pea3nut/agent-add#asset-developer-guide) for creating distributable assets\n- Explore the [Host Adapter Architecture](https://github.com/pea3nut/agent-add#architecture-overview) for adding new hosts\n- Run `agent-add --help` for complete CLI reference\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Host Integration](#host-integration), [Source Resolution](#source-resolution)\n\n
\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/index.ts)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n- [src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n- [src/hosts/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/index.ts)\n- [src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n- [src/source/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/index.ts)\n- [src/assets/mcp.ts](https://github.com/pea3nut/agent-add/blob/main/src/assets/mcp.ts)\n- [src/assets/skill.ts](https://github.com/pea3nut/agent-add/blob/main/src/assets/skill.ts)\n- [src/assets/prompt.ts](https://github.com/pea3nut/agent-add/blob/main/src/assets/prompt.ts)\n- [src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n
\n\n# System Architecture\n\nagent-add is a cross-host AI agent pack installer CLI tool that enables developers to install MCP (Model Context Protocol), Skill, Prompt, Command, and Sub-agent assets into various AI agent hosts with a single command. The system is built with TypeScript 5.x in strict mode, targeting Node.js 18+ as a CommonJS bundle.\n\n## Overview\n\nThe architecture follows a layered, pipeline-based design that separates concerns between CLI interface, orchestration logic, host adapters, and asset handlers. The system is stateless—no install state files are maintained—relying instead on filesystem-based idempotency checks.\n\n```mermaid\ngraph TD\n subgraph CLI[\"CLI Layer\"]\n CLI_ENTRY[\"src/index.ts
Entry Point\"]\n CLI_CMD[\"src/cli.ts
Commander + TTY Detection\"]\n end\n\n subgraph Core[\"Core Pipeline\"]\n INST[\"src/installer.ts
Orchestration Core\"]\n VALIDATE[\"Validation Layer\"]\n RESOLVE[\"src/source/index.ts
Source Resolution\"]\n end\n\n subgraph Adapters[\"Host Adapter Layer\"]\n REGISTRY[\"src/hosts/index.ts
Host Registry\"]\n CURSOR[\"cursor.ts\"]\n CLAUDE_CODE[\"claude-code.ts\"]\n VIBE[\"vibe.ts\"]\n CODEX[\"codex.ts\"]\n end\n\n subgraph Handlers[\"Asset Handler Layer\"]\n MCP[\"assets/mcp.ts\"]\n SKILL[\"assets/skill.ts\"]\n PROMPT[\"assets/prompt.ts\"]\n COMMAND[\"assets/command.ts\"]\n SUBAGENT[\"assets/sub-agent.ts\"]\n end\n\n CLI_ENTRY --> CLI_CMD\n CLI_CMD --> INST\n INST --> VALIDATE\n INST --> RESOLVE\n RESOLVE --> REGISTRY\n REGISTRY --> CURSOR\n REGISTRY --> CLAUDE_CODE\n REGISTRY --> VIBE\n REGISTRY --> CODEX\n INST --> MCP\n INST --> SKILL\n INST --> PROMPT\n INST --> COMMAND\n INST --> SUBAGENT\n```\n\n资料来源：[src/index.ts:1-7]()\n\n## Directory Structure\n\n```\nagent-add/\n├── src/\n│ ├── index.ts # Entry point\n│ ├── cli.ts # Commander definition + TTY detection\n│ ├── installer.ts # Orchestration core\n│ ├── hosts/ # Host adapter layer\n│ │ ├── index.ts # Host registry (Map)\n│ │ ├── types.ts # HostAdapter, AssetCapability, WriteStrategy\n│ │ ├── README.md # Capability matrix (single source of truth)\n│ │ └── .ts # Per-host adapter (18 hosts)\n│ ├── assets/ # Asset type handlers\n│ │ ├── mcp.ts # JSON shallow merge + atomic write\n│ │ ├── skill.ts # Directory copy + SKILL.md validation\n│ │ ├── prompt.ts # Marker append or create-file-in-dir\n│ │ ├── command.ts # Command file handler\n│ │ └── sub-agent.ts # Sub-agent with host specialization\n│ └── source/ # Source resolution system\n│ ├── index.ts # Source resolution entry\n│ ├── infer-name.ts # Asset name inference\n│ ├── local.ts # Local file resolution\n│ ├── git.ts # Git URL cloning\n│ └── http.ts # HTTP/HTTPS download\n├── tests/\n│ ├── unit/ # Unit tests (vitest)\n│ ├── integration/ # Integration tests\n│ ├── features/ # Gherkin scenario tests\n│ └── fixtures/ # Static test fixtures\n└── dist/ # Built output\n```\n\n资料来源：[README.md:1-45]()\n\n## Core Data Flow\n\nThe installation pipeline follows a strict sequential flow from CLI input to final installation result:\n\n```mermaid\ngraph LR\n A[\"CLI Flags /
--pack Manifest\"] --> B[\"Explicit Flag
Capability Check\"]\n B --> C[\"AssetDescriptor[]
(type + source)\"]\n C --> D[\"ResolvedSource[]
(localPath + tempDir)\"]\n D --> E[\"InstallJob[]
(skip unsupported)\"]\n E --> F[\"InstallResult[]
(written/exists/updated/
conflict/skipped/error)\"]\n F --> G[\"Summary Output\"]\n```\n\n### Pipeline Stages\n\n| Stage | Input | Output | Key Operations |\n|-------|-------|--------|-----------------|\n| CLI Parsing | `process.argv` | `CliInput` object | TTY detection, host selection |\n| Capability Check | `CliInput` | `AssetDescriptor[]` | Validates `--host` exists, checks explicit flags against host capabilities |\n| Source Resolution | `AssetDescriptor[]` | `ResolvedSource[]` | Downloads Git/HTTP, extracts archives, writes inline sources to temp |\n| Job Creation | `ResolvedSource[]` | `InstallJob[]` | Filters assets unsupported by target host |\n| Handler Execution | `InstallJob[]` | `InstallResult[]` | Writes files using host-specific strategies |\n| Summary | `InstallResult[]` | Console output | Formatted install summary |\n\n资料来源：[src/installer.ts:1-200]()\n\n## Host Adapter Layer\n\nThe host adapter layer provides a unified interface for interacting with different AI agent hosts. Each host has specific capabilities, installation paths, and write strategies.\n\n### Host Registry\n\nThe `src/hosts/index.ts` file maintains a `Map` that maps host IDs to their adapter implementations:\n\n```typescript\nconst hostRegistry = new Map([\n ['cursor', new CursorAdapter()],\n ['claude-code', new ClaudeCodeAdapter()],\n ['claude-desktop', new ClaudeDesktopAdapter()],\n ['windsurf', new WindsurfAdapter()],\n ['github-copilot', new GitHubCopilotAdapter()],\n ['gemini', new GeminiAdapter()],\n ['roo-code', new RooCodeAdapter()],\n ['kilo-code', new KiloCodeAdapter()],\n ['qwen-code', new QwenCodeAdapter()],\n ['opencode', new OpenCodeAdapter()],\n ['augment', new AugmentAdapter()],\n ['kiro', new KiroAdapter()],\n ['tabnine', new TabnineAdapter()],\n ['kimi', new KimiAdapter()],\n ['trae', new TraeAdapter()],\n ['openclaw', new OpenClawAdapter()],\n ['codex', new CodexAdapter()],\n ['vibe', new VibeAdapter()],\n]);\n```\n\n资料来源：[src/hosts/index.ts]()\n资料来源：[src/hosts/README.md:1-100]()\n\n### Supported Hosts\n\n| Host ID | MCP | Prompt | Skill | Command | Sub-agent | Config Format |\n|---------|-----|--------|-------|---------|-----------|---------------|\n| cursor | ✅ | ✅ | ✅ | ✅ | ✅ | JSON |\n| claude-code | ✅ | ✅ | ❌ | ❌ | ❌ | JSON |\n| claude-desktop | ✅ | ❌ | ❌ | ❌ | ❌ | JSON |\n| windsurf | ✅ | ✅ | ✅ | ❌ | ❌ | JSON |\n| github-copilot | ✅ | ❌ | ❌ | ❌ | ❌ | JSON |\n| codex | ✅ | ✅ | ❌ | ❌ | ❌ | TOML |\n| vibe | ✅ | ✅ | ❌ | ❌ | ❌ | TOML |\n\n资料来源：[src/hosts/README.md:1-150]()\n\n### HostAdapter Interface\n\nEach host adapter implements the `HostAdapter` interface with asset-specific capabilities:\n\n```typescript\ninterface HostAdapter {\n readonly id: string;\n readonly displayName: string;\n readonly docs: string;\n readonly assets: Record;\n}\n\ninterface AssetCapability {\n supported: boolean;\n reason?: string;\n configFile?: string;\n installDir?: string;\n writeStrategy?: WriteStrategy;\n baseRulesFile?: string;\n}\n```\n\n资料来源：[src/hosts/types.ts]()\n\n### Write Strategies\n\nThe system supports different write strategies for different asset types and hosts:\n\n| Strategy | Description | Used By |\n|----------|-------------|---------|\n| `append-with-marker` | Appends content wrapped in HTML comment markers (``) | Cursor, Claude Code |\n| `create-file-in-dir` | Creates standalone `.md` file in rules directory | Windsurf, Roo Code, Kilo Code |\n| `json-merge` | Shallow JSON merge for MCP config | Most hosts |\n| `toml-merge` | TOML merge for Codex/Vibe | codex, vibe |\n\n资料来源：[src/hosts/types.ts]()\n资料来源：[src/assets/prompt.ts]()\n资料来源：[src/assets/mcp.ts]()\n\n## Asset Handler Layer\n\nEach asset type has a dedicated handler that implements the `AssetHandler` interface:\n\n```mermaid\ngraph TD\n H[\"InstallJob\"] --> MCP[\"MCP Handler\"]\n H --> SKILL[\"Skill Handler\"]\n H --> PROMPT[\"Prompt Handler\"]\n H --> COMMAND[\"Command Handler\"]\n H --> SUBAGENT[\"Sub-agent Handler\"]\n\n MCP --> MCP_WRITE[\"Atomic JSON/TOML Write\"]\n SKILL --> SKILL_COPY[\"Directory Copy + Validation\"]\n PROMPT --> PROMPT_STRAT[\"Marker Append or Create File\"]\n COMMAND --> COMMAND_WRITE[\"YAML Frontmatter Parse\"]\n SUBAGENT --> SUB_WRITE[\"Host Specialization Processing\"]\n```\n\n### MCP Handler\n\nThe MCP handler supports both JSON and TOML formats with automatic format detection:\n\n- **JSON format A (inner config)**: Single server without wrapper\n- **JSON format B (full config)**: With `mcpServers` wrapper\n- **TOML format**: Auto-detected by `.toml` extension\n\nKey behavior:\n- Shallow merge for existing configurations\n- Atomic write using temp file + rename pattern\n- TOML auto-dispatches for Codex and Vibe hosts\n\n资料来源：[src/assets/mcp.ts]()\n资料来源：[README.md:50-80]()\n\n### Skill Handler\n\nThe Skill handler installs entire skill directories:\n\n- Recursively copies directory contents to host's skills directory\n- Validates `SKILL.md` exists within the source directory\n- Asset name becomes the subdirectory name under skills root\n- **Note**: Does not support inline sources, HTTP URLs, or git subpaths\n\n资料来源：[src/assets/skill.ts]()\n资料来源：[src/installer.ts:50-100]()\n\n### Prompt Handler\n\nThe Prompt handler supports two write strategies:\n\n1. **Append Mode** (Cursor, Claude Code): Content is wrapped in idempotent HTML markers\n ```html\n \n # Code Review Rules\n ...\n \n ```\n\n2. **Standalone File Mode** (Windsurf, Roo Code): Creates `.md` in rules directory\n\n资料来源：[src/assets/prompt.ts]()\n资料来源：[README.md:80-120]()\n\n### Sub-agent Handler\n\nThe Sub-agent handler supports host specialization using YAML frontmatter:\n\n```yaml\n---\nname: playwright-tester\ndescription: A playwright testing agent.\nagent-add/cursor/model: fast\nagent-add/claude-code/model: haiku\n---\n\n# Playwright Test Agent\n```\n\nDuring installation:\n1. Matching `agent-add//*` values are promoted to top-level\n2. All `agent-add/*` prefixed keys are removed\n3. Resulting frontmatter is host-specific\n\n资料来源：[src/assets/sub-agent.ts]()\n资料来源：[README.md:140-180]()\n\n## Source Resolution System\n\nThe source resolution system handles multiple source types and normalizes them to local filesystem paths:\n\n```mermaid\ngraph TD\n S[\"Source String\"] --> TYPE{\"Source Type Detection\"}\n \n TYPE -->|Starts with `{` | INLINE_JSON[\"Inline JSON\"]\n TYPE -->|Contains `\\n` | INLINE_MD[\"Inline Markdown\"]\n TYPE -->|Starts with `http` | HTTP[\"HTTP/HTTPS URL\"]\n TYPE -->|Contains `://` or `.git` | GIT[\"Git URL\"]\n TYPE -->|Otherwise | LOCAL[\"Local Path\"]\n \n INLINE_JSON --> TEMP[\"Write to Temp File\"]\n INLINE_MD --> TEMP\n HTTP --> DOWNLOAD[\"Download via fetch\"]\n GIT --> CLONE[\"Git Clone/Shallow Clone\"]\n LOCAL --> RESOLVE[\"path.resolve()\"]\n \n DOWNLOAD --> CACHE[\"Cache in Temp Dir\"]\n CLONE --> CACHE\n TEMP --> CACHE\n RESOLVE --> CACHE\n \n CACHE --> RESULT[\"ResolvedSource\"]\n```\n\n### Supported Source Types\n\n| Source Type | Detection | Processing |\n|-------------|-----------|------------|\n| Inline JSON | Starts with `{` | Parse, validate, write to temp |\n| Inline Markdown | Contains `\\n` | Extract name from `# Heading`, write to temp |\n| HTTP File | `https://` or `http://` | Download via fetch, save to temp |\n| Git URL | Contains `://` or `.git` | Shallow clone to temp directory |\n| Local Path | Default | Resolve relative to cwd |\n\n### Name Inference Rules\n\nAsset names are inferred from sources using these rules:\n\n| Source Pattern | Inference Rule | Example |\n|----------------|----------------|---------|\n| Git URL + `#path` | Last segment after `#`, kebab-case | `...git#skills/pdf` → `pdf` |\n| Git URL without `#` | Repo name, strip `.git` | `...playwright.git` → `playwright` |\n| HTTP URL | Filename, strip extension | `./mcps/playwright.json` → `playwright` |\n| Local path | Filename, strip extension | `playwright.json` → `playwright` |\n| Inline JSON | Top-level key name | `{\"playwright\":{...}}` → `playwright` |\n| Inline Markdown | First `# Heading`, kebab-case | `# Code Review` → `code-review` |\n\n资料来源：[src/source/infer-name.ts:1-50]()\n\n## CLI Layer\n\n### Entry Point\n\n```typescript\nimport { createProgram } from './cli.js';\n\nconst program = createProgram();\nprogram.parseAsync(process.argv).catch((err: Error) => {\n process.stderr.write(`agent-add error: ${err.message}\\n`);\n process.exit(2);\n});\n```\n\n资料来源：[src/index.ts:1-7]()\n\n### CLI Options\n\n| Flag | Type | Description | Repeatable |\n|------|------|-------------|------------|\n| `--pack ` | string | Install Agent Pack manifest | Yes |\n| `--mcp ` | string | Install MCP config | Yes |\n| `--skill ` | string | Install Skill directory | Yes |\n| `--prompt ` | string | Install Prompt file | Yes |\n| `--command ` | string | Install Command file | Yes |\n| `--sub-agent ` | string | Install Sub-agent file | Yes |\n| `--host ` | string | Target host ID | No |\n| `-V, --version` | - | Show version | - |\n| `-h, --help` | - | Show help | - |\n\n资料来源：[src/cli.ts]()\n资料来源：[README.md:200-220]()\n\n### TTY Detection\n\nNon-TTY environments (CI/CD) require explicit `--host` specification:\n\n```typescript\nif (!process.stdout.isTTY && !cliInput.host) {\n process.stderr.write(\n `agent-add error: Non-TTY environment detected. ` +\n `Specify --host explicitly. Valid hosts: ${validIds.join(', ')}\\n`,\n );\n process.exit(2);\n}\n```\n\n资料来源：[src/cli.ts]()\n资料来源：[README.md:30-35]()\n\n## Validation Layer\n\nThe validation layer performs asset-specific validation before installation:\n\n| Asset Type | Validations |\n|------------|-------------|\n| MCP | File must exist, extension must be `.json` |\n| Skill | Must be directory (not HTTP/inline), must contain `SKILL.md` |\n| Prompt | None (Markdown has no required structure) |\n| Command | None (Markdown with optional YAML frontmatter) |\n| Sub-agent | None (Markdown with optional YAML frontmatter) |\n\n资料来源：[src/installer.ts:100-150]()\n\n### Explicit Flag Capability Check\n\nWhen a user explicitly specifies an asset type flag (e.g., `--mcp`), the system checks if the target host supports that asset type. If `supported: false`, the installation exits with code 2 and provides a helpful error message with documentation link.\n\n**Exception**: Assets from `--pack` manifests skip this check, as pack authors may include host-specific assets.\n\n资料来源：[src/installer.ts:30-60]()\n\n## Error Handling\n\n| Error Type | Exit Code | Action |\n|------------|-----------|--------|\n| Capability not supported | 2 | Exit with error message + README link |\n| Validation failure | 2 | Exit with source path |\n| No matching files in directory | 2 | Exit with source path |\n| Inline source for Skill | 2 | Exit with reason |\n| Install conflict | 1 | Exit 1 (not 2, partial success) |\n| Install error | 1 | Exit 1 (not 2, partial success) |\n\n资料来源：[src/installer.ts:150-200]()\n资料来源：[src/cli.ts:60-80]()\n\n## Testing Architecture\n\nThe project uses a three-layer test strategy:\n\n```mermaid\ngraph TD\n T[\"npm test\"] --> U[\"Unit Tests\"]\n T --> I[\"Integration Tests\"]\n T --> CONTRACT[\"Contract Tests\"]\n \n U --> V[\"vitest unit/\"]\n I --> VITEST_INT[\"vitest integration/\"]\n CONTRACT --> BLACKBOX[\"CLI black-box tests\"]\n \n SCENARIO[\"Gherkin Scenarios\"] -.-> MANUAL[\"AI Agent Manual Trigger\"]\n SCENARIO --> FEATURES[\"tests/features/\"]\n FEATURES --> ISOLATED[\"Isolated Temp Dir Execution\"]\n```\n\n| Test Layer | Command | Purpose |\n|------------|---------|---------|\n| Unit | `npm test` | Component-level testing with mocks |\n| Integration | `npm run test:integration` | Full flow testing with filesystem |\n| Contract | `npm run test:contract` | CLI black-box behavior verification |\n| Scenario | `/scenario-exec tests/features/` | Gherkin feature files, AI-executed |\n\n资料来源：[README.md:15-30]()\n资料来源：[README.md:230-250]()\n\n## Environment Variables\n\n| Variable | Purpose |\n|----------|---------|\n| `AGENT_ADD_HOME` | Overrides `os.homedir()` for test isolation, redirects Claude Desktop/Codex host install paths to temp directories |\n\n资料来源：[system-prompt.md:10-12]()\n资料来源：[src/assets/mcp.ts]()\n\n## Key Design Decisions\n\n### Atomic Writes\n\nMCP configuration uses a temp file + rename pattern to ensure atomicity:\n\n```typescript\n// 1. Write to temp file\n// 2. Rename to target (atomic on POSIX)\n// 3. On failure, temp file is orphaned (not a partial write)\n```\n\n资料来源：[src/assets/mcp.ts]()\n\n### Idempotent Marker Blocks\n\nPrompt append mode uses HTML comment markers for safe re-installation:\n\n```html\n\n# Code Review Rules\n...\n\n```\n\nIf markers exist, content between them is replaced; otherwise, markers are appended.\n\n资料来源：[src/assets/prompt.ts]()\n资料来源：[README.md:100-110]()\n\n### TOML Auto-Dispatch\n\nThe MCP handler detects `.toml` extension and routes to TOML-specific merge logic:\n\n```typescript\nif (resolved.localPath.endsWith('.toml')) {\n // Use smol-toml for read/write\n} else {\n // Use JSON shallow merge\n}\n```\n\n资料来源：[src/assets/mcp.ts]()\n资料来源：[package.json:20-25]()\n\n## Technology Stack\n\n| Component | Technology | Version |\n|-----------|------------|---------|\n| Language | TypeScript | 5.x (strict mode) |\n| Runtime | Node.js | 18+ |\n| Build | tsup (esbuild) | 8.x |\n| Testing | vitest | 4.x |\n| CLI | commander | 14.x |\n| TOML | smol-toml | 1.x |\n| Config validation | zod | 4.x |\n| YAML parsing | yaml | 2.x |\n| Interactive prompts | @inquirer/select | 5.x |\n\n资料来源：[package.json:1-50]()\n\n---\n\n\n\n## Host Integration\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [Asset Types](#asset-types)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n- [src/hosts/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/index.ts)\n- [src/hosts/cursor.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/cursor.ts)\n- [src/hosts/claude-code.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/claude-code.ts)\n- [src/hosts/windsurf.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/windsurf.ts)\n- [src/hosts/github-copilot.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/github-copilot.ts)\n- [src/hosts/README.md](https://github.com/pea3nut/agent-add/blob/main/src/hosts/README.md)\n
\n\n# Host Integration\n\n## Overview\n\nThe Host Integration layer is the core abstraction in `agent-add` that enables cross-host compatibility. It provides a unified interface for installing assets (MCP servers, Skills, Prompts, Commands, and Sub-agents) across 18 different AI agent hosts including Cursor, Claude Code, Windsurf, and GitHub Copilot.\n\nEach supported host has a dedicated adapter class that encapsulates:\n- Host detection mechanisms\n- Asset installation paths\n- Configuration file formats\n- Write strategies for different asset types\n- Platform-specific considerations\n\nThis architecture allows `agent-add` to abstract away the complexities of each host's unique file system structure and configuration format, presenting a single CLI interface to end users.\n\n## Architecture\n\n### System Architecture\n\n```mermaid\ngraph TD\n subgraph \"CLI Layer\"\n CLI[CLI Input Parsing]\n end\n \n subgraph \"Core Engine\"\n INST[Installer]\n VAL[Validator]\n end\n \n subgraph \"Host Adapter Layer\"\n REG[Host Registry]\n CA[Cursor Adapter]\n CCA[Claude Code Adapter]\n WA[Windsurf Adapter]\n OHA[Other Host Adapters]\n end\n \n subgraph \"Asset Handlers\"\n MCP[MCP Handler]\n SKILL[Skill Handler]\n PROMPT[Prompt Handler]\n CMD[Command Handler]\n SUB[Sub-agent Handler]\n end\n \n CLI --> INST\n INST --> VAL\n VAL --> REG\n REG --> CA\n REG --> CCA\n REG --> WA\n REG --> OHA\n \n CA --> MCP\n CA --> SKILL\n CA --> PROMPT\n CA --> CMD\n CA --> SUB\n \n CCA --> MCP\n CCA --> SKILL\n CCA --> PROMPT\n CCA --> CMD\n CCA --> SUB\n```\n\n### Data Flow\n\n```mermaid\nsequenceDiagram\n participant CLI as CLI Input\n participant INST as Installer\n participant HOST as Host Adapter\n participant HAND as Asset Handler\n participant FS as File System\n \n CLI->>INST: Parse flags + --pack manifest\n INST->>INST: Capability check\n INST->>INST: Source resolution\n INST->>INST: Asset validation\n INST->>HOST: Get capabilities for asset type\n HOST-->>INST: Return AssetCapability\n INST->>INST: Create InstallJob[]\n INST->>HAND: Execute install job\n HAND->>FS: Write with strategy\n FS-->>HAND: Confirm write\n HAND-->>INST: InstallResult\n INST->>INST: Format summary output\n```\n\n## HostAdapter Interface\n\nThe `HostAdapter` interface defines the contract all host implementations must follow.\n\n### Interface Definition\n\n```typescript\n// src/hosts/types.ts\nexport interface HostAdapter {\n readonly id: string;\n readonly displayName: string;\n readonly docs: string;\n readonly detection: {\n paths: string[];\n };\n readonly assets: Record;\n}\n```\n\n### Property Specification\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `id` | `string` | Unique identifier for the host (e.g., `\"cursor\"`, `\"claude-code\"`) |\n| `displayName` | `string` | Human-readable name (e.g., `\"Claude Code\"`) |\n| `docs` | `string` | URL to official documentation |\n| `detection.paths` | `string[]` | Directory paths that indicate this host is active |\n| `assets` | `Record` | Capability definitions for each asset type |\n\n资料来源：[src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n\n## AssetCapability Types\n\nEach asset type has its own capability configuration within the host adapter.\n\n### AssetType Enum\n\n```typescript\n// src/hosts/types.ts\nexport type AssetType = 'mcp' | 'skill' | 'prompt' | 'command' | 'subAgent';\n```\n\n### Capability Structure\n\n```typescript\n// src/hosts/types.ts\nexport interface AssetCapability {\n supported: boolean;\n reason?: string; // Required when supported=false\n configFile?: ConfigFileSpec; // For MCP\n configKey?: string; // For MCP\n targetFile?: string; // For Prompt (append mode)\n installDir?: string; // For Skill/Command/Sub-agent\n entryFile?: string; // For Skill\n fileExtension?: string; // For Command/Sub-agent\n writeStrategy?: WriteStrategy; // Strategy for writing files\n}\n\nexport interface ConfigFileSpec {\n darwin?: string;\n linux?: string;\n win32?: string;\n}\n```\n\n### Supported Asset Types\n\n| Asset Type | Purpose | Install Method |\n|------------|---------|----------------|\n| `mcp` | Model Context Protocol servers | Modify config file (JSON or TOML) |\n| `skill` | Reusable agent skill directories | Copy directory recursively |\n| `prompt` | System prompts / rule files | Append or create standalone file |\n| `command` | Custom slash commands | Copy markdown file |\n| `subAgent` | Sub-agent configurations | Copy configuration file |\n\n资料来源：[src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n\n## Write Strategies\n\nThe `writeStrategy` property determines how assets are installed to the host's filesystem.\n\n### Strategy Types\n\n| Strategy | Description | Supported Asset Types |\n|----------|-------------|----------------------|\n| `inject-json-key` | Inject configuration into existing JSON/TOML file | MCP, Prompt (append mode) |\n| `append-with-marker` | Append content wrapped in HTML comment markers | Prompt |\n| `copy-file` | Copy file directly to target directory | Skill, Command, Sub-agent |\n| `create-file-in-dir` | Create file at `installDir/.md` | Prompt (standalone mode) |\n\n### Marker Block Format\n\nWhen using `append-with-marker`, content is wrapped in HTML comment markers for idempotent updates:\n\n```html\n\n# Code Review Rules\n\nAlways review for security issues first.\n\n```\n\n### JSON Injection\n\nThe `inject-json-key` strategy performs shallow merging of MCP server configurations:\n\n```typescript\n// Before\n{ \"mcpServers\": { \"existing-server\": {} } }\n\n// After (injecting playwright)\n{ \"mcpServers\": { \"existing-server\": {}, \"playwright\": { \"command\": \"npx\", \"args\": [\"@playwright/mcp@latest\"] } } }\n```\n\n## Host Registry\n\nThe host registry maps host IDs to their adapter instances.\n\n```mermaid\nclassDiagram\n class HostRegistry {\n +hostRegistry: Map~string, HostAdapter~\n +getHost(id: string): HostAdapter\n +getValidHostIds(): string[]\n }\n \n class HostAdapter {\n <>\n +id: string\n +displayName: string\n +docs: string\n +assets: Record~AssetType, AssetCapability~\n }\n \n HostRegistry --> HostAdapter\n```\n\n### Registry Implementation\n\n```typescript\n// src/hosts/index.ts\nconst hostRegistry = new Map([\n ['cursor', new CursorAdapter()],\n ['claude-code', new ClaudeCodeAdapter()],\n ['windsurf', new WindsurfAdapter()],\n ['github-copilot', new GitHubCopilotAdapter()],\n // ... 14 more hosts\n]);\n```\n\n### Currently Supported Hosts\n\nThe system supports 18 hosts across multiple platforms:\n\n| Host ID | Display Name | Config Format |\n|---------|--------------|---------------|\n| `cursor` | Cursor AI | JSON |\n| `claude-code` | Claude Code | JSON |\n| `claude-desktop` | Claude Desktop | JSON |\n| `windsurf` | Windsurf | TOML |\n| `github-copilot` | GitHub Copilot | JSON |\n| `gemini` | Google Gemini | JSON |\n| `roo-code` | Roo Code | JSON |\n| `kilo-code` | Kilo Code | JSON |\n| `qwen-code` | Qwen Code | JSON |\n| `opencode` | OpenCode | JSON |\n| `augment` | Augment Code | JSON |\n| `kiro` | Kiro | JSON |\n| `tabnine` | Tabnine | JSON |\n| `kimi` | Kimi | JSON |\n| `trae` | Trae | JSON |\n| `openclaw` | OpenClaw | JSON |\n| `codex` | Codex CLI | TOML |\n| `vibe` | Vibe | TOML |\n\n## Example Host Adapters\n\n### Claude Code Adapter\n\n```typescript\n// src/hosts/claude-code.ts\nexport class ClaudeCodeAdapter implements HostAdapter {\n readonly id = 'claude-code';\n readonly displayName = 'Claude Code';\n readonly docs = 'https://code.claude.com/docs/en';\n readonly detection = {\n paths: ['.claude/'],\n };\n readonly assets: Record = {\n mcp: {\n supported: true,\n configFile: '.mcp.json',\n configKey: 'mcpServers',\n writeStrategy: 'inject-json-key',\n },\n skill: {\n supported: true,\n installDir: '.claude/skills/',\n entryFile: 'SKILL.md',\n writeStrategy: 'copy-file',\n },\n prompt: {\n supported: true,\n targetFile: 'CLAUDE.md',\n writeStrategy: 'append-with-marker',\n },\n command: {\n supported: true,\n installDir: '.claude/commands/',\n fileExtension: '.md',\n writeStrategy: 'copy-file',\n },\n subAgent: {\n supported: true,\n installDir: '.claude/agents/',\n fileExtension: '.md',\n writeStrategy: 'copy-file',\n },\n };\n}\n```\n\n资料来源：[src/hosts/claude-code.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/claude-code.ts)\n\n### Cursor Adapter\n\n```typescript\n// src/hosts/cursor.ts\nexport class CursorAdapter implements HostAdapter {\n readonly id = 'cursor';\n readonly displayName = 'Cursor';\n readonly docs = 'https://www.cursor.com/docs';\n readonly detection = {\n paths: ['.cursor/'],\n };\n readonly assets: Record = {\n mcp: {\n supported: true,\n configFile: {\n darwin: '~/Library/Application Support/Cursor/config/mcp.json',\n linux: '~/.config/Cursor/config/mcp.json',\n win32: '%APPDATA%\\\\Cursor\\\\config\\\\mcp.json',\n },\n configKey: 'mcpServers',\n writeStrategy: 'inject-json-key',\n },\n skill: {\n supported: true,\n installDir: '.cursor/skills/',\n entryFile: 'SKILL.md',\n writeStrategy: 'copy-file',\n },\n prompt: {\n supported: true,\n targetFile: 'AGENTS.md',\n writeStrategy: 'append-with-marker',\n },\n command: {\n supported: true,\n installDir: '.cursor/commands/',\n fileExtension: '.md',\n writeStrategy: 'copy-file',\n },\n subAgent: {\n supported: true,\n installDir: '.cursor/agents/',\n fileExtension: '.md',\n writeStrategy: 'copy-file',\n },\n };\n}\n```\n\n资料来源：[src/hosts/cursor.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/cursor.ts)\n\n### Unsupported Assets\n\nHosts that don't support certain asset types use the `NOT_SUPPORTED` helper:\n\n```typescript\n// src/hosts/github-copilot.ts\nconst NOT_SUPPORTED = (reason: string): AssetCapability => ({\n supported: false,\n reason,\n});\n\nexport class GitHubCopilotAdapter implements HostAdapter {\n // ...\n readonly assets: Record = {\n mcp: {\n supported: true,\n configFile: '.github/copilot-instruqt.md',\n writeStrategy: 'inject-json-key',\n },\n command: NOT_SUPPORTED('GitHub Copilot does not support custom slash commands via files.'),\n // ...\n };\n}\n```\n\n## Adding a New Host\n\n### Contribution Workflow\n\n```mermaid\ngraph LR\n A[Create Adapter] --> B[Register in index.ts]\n B --> C[Update README.md]\n C --> D[Add Unit Tests]\n D --> E[Verify with scenario tests]\n```\n\n### Step 1: Create the Adapter File\n\nCreate `src/hosts/.ts` with a class implementing `HostAdapter`:\n\n```typescript\n// src/hosts/new-host.ts\nimport type { HostAdapter, AssetCapability, AssetType } from './types.js';\n\nconst NOT_SUPPORTED = (reason: string): AssetCapability => ({\n supported: false,\n reason,\n});\n\nexport class NewHostAdapter implements HostAdapter {\n readonly id = 'new-host';\n readonly displayName = 'New Host';\n readonly docs = 'https://docs.newhost.com';\n readonly detection = {\n paths: ['.newhost/'],\n };\n readonly assets: Record = {\n mcp: {\n supported: true,\n configFile: '.newhost/mcp.json',\n configKey: 'mcpServers',\n writeStrategy: 'inject-json-key',\n },\n prompt: NOT_SUPPORTED('New Host does not support prompts.'),\n skill: NOT_SUPPORTED('New Host does not support skills.'),\n command: NOT_SUPPORTED('New Host does not support commands.'),\n subAgent: NOT_SUPPORTED('New Host does not support sub-agents.'),\n };\n}\n```\n\n### Step 2: Register the Adapter\n\nAdd to the registry in `src/hosts/index.ts`:\n\n```typescript\nimport { NewHostAdapter } from './new-host.js';\n\nconst hostRegistry = new Map([\n // ... existing entries\n ['new-host', new NewHostAdapter()],\n]);\n```\n\n### Step 3: Update Documentation\n\nAdd a row to the capability matrix in `src/hosts/README.md`:\n\n| Host | MCP | Prompt | Skill | Command | Sub-agent |\n|------|-----|--------|-------|---------|-----------|\n| New Host | ✅ `.newhost/mcp.json` | ❌ | ❌ | ❌ | ❌ |\n\n### Step 4: Add Unit Tests\n\nCreate `tests/unit/hosts/new-host.test.ts`:\n\n```typescript\nimport { describe, it, expect } from 'vitest';\nimport { NewHostAdapter } from '../../../src/hosts/new-host.js';\n\ndescribe('NewHostAdapter', () => {\n const adapter = new NewHostAdapter();\n\n it('should have correct id', () => {\n expect(adapter.id).toBe('new-host');\n });\n\n it('should have correct displayName', () => {\n expect(adapter.displayName).toBe('New Host');\n });\n\n it('should support MCP', () => {\n expect(adapter.assets.mcp.supported).toBe(true);\n expect(adapter.assets.mcp.configFile).toBe('.newhost/mcp.json');\n });\n});\n```\n\n## Key Design Decisions\n\n### Atomic JSON Writes\n\nMCP configurations use a temp file + rename pattern to ensure atomicity:\n\n```mermaid\ngraph TD\n A[New Config] --> B[Write to temp file]\n B --> C[Rename temp to target]\n C --> D{Success?}\n D -->|Yes| E[Complete]\n D -->|No| F[Rollback temp file]\n```\n\n### Platform-Specific Paths\n\nMCP config files use platform-specific paths:\n\n```typescript\nconfigFile: {\n darwin: '~/Library/Application Support/Cursor/config/mcp.json',\n linux: '~/.config/Cursor/config/mcp.json',\n win32: '%APPDATA%\\\\Cursor\\\\config\\\\mcp.json',\n}\n```\n\n### TOML vs JSON Auto-Detection\n\nThe system auto-detects TOML format based on file extension:\n\n```typescript\n// src/assets/mcp.ts\nif (path.extname(configFile) === '.toml') {\n // Use smol-toml for read/write\n} else {\n // Use standard JSON\n}\n```\n\n### Explicit Flag Capability Checking\n\nThe installer validates that explicitly requested asset types are supported before attempting installation:\n\n```typescript\n// src/installer.ts\nif (!capability.supported) {\n skippedResults.push({\n job: { assetType, assetName, resolvedSource, host },\n status: 'skipped',\n reason: capability.reason,\n });\n}\n```\n\n## Summary\n\nThe Host Integration system provides a scalable architecture for supporting multiple AI agent hosts through a consistent adapter pattern. Key benefits include:\n\n- **Single Source of Truth**: All host capabilities defined in adapter classes and documented in `src/hosts/README.md`\n- **Extensibility**: New hosts can be added by implementing the `HostAdapter` interface\n- **Type Safety**: TypeScript strict mode ensures adapter implementations match specifications\n- **Testability**: Each adapter has corresponding unit tests verifying exact field values\n- **Platform Abstraction**: Platform-specific paths handled transparently\n- **Format Flexibility**: Supports both JSON and TOML configuration formats\n\n---\n\n\n\n## Source Resolution\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [Asset Types](#asset-types)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/source/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/index.ts)\n- [src/source/git.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/git.ts)\n- [src/source/http-file.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/http-file.ts)\n- [src/source/local.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/local.ts)\n- [src/source/inline.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/inline.ts)\n- [src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n
\n\n# Source Resolution\n\n## Overview\n\nSource Resolution is the core subsystem responsible for transforming user-provided source strings into concrete filesystem paths that the installer can process. It acts as an abstraction layer that normalizes diverse input formats—including local paths, Git URLs, HTTP URLs, and inline content—into a unified `ResolvedSource` data structure.\n\nThe resolution pipeline accepts asset sources in multiple formats and outputs temporary directories containing the asset content, ready for downstream handlers to install into host-specific locations. This design decouples asset specification from asset installation, enabling users to reference assets through various convenient syntaxes without understanding host-specific installation mechanics.\n\n资料来源：[src/source/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/index.ts)\n\n## Architecture\n\nThe Source Resolution module is located in `src/source/` and comprises six specialized modules:\n\n| Module | Purpose |\n|--------|---------|\n| `index.ts` | Main entry point; orchestrates resolution pipeline |\n| `git.ts` | Resolves Git URLs (SSH and HTTPS) with sparse checkout support |\n| `http-file.ts` | Downloads assets from HTTP/HTTPS URLs |\n| `local.ts` | Resolves local filesystem paths |\n| `inline.ts` | Handles inline JSON and Markdown content |\n| `infer-name.ts` | Extracts asset names from source strings |\n\n资料来源：[src/source/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/index.ts)\n\n## Resolution Pipeline\n\nThe resolution process follows a sequential pipeline that attempts each resolver until one successfully produces a `ResolvedSource`:\n\n```mermaid\ngraph TD\n A[User Source String] --> B{Starts with ./ or / or ~?}\n B -->|Yes| C[Local Resolver]\n B -->|No| D{Starts with http:// or https://?}\n D -->|Yes| E[HTTP Resolver]\n D -->|No| F{Starts with git@ or ends with .git?}\n F -->|Yes| G[Git Resolver]\n F -->|No| H{Starts with {?}\n H -->|Yes| I[Inline JSON Resolver]\n H -->|No| J{Contains \\n?}\n J -->|Yes| K[Inline Markdown Resolver]\n J -->|No| L[Error: Unknown source format]\n \n C --> M[ResolvedSource]\n E --> M\n G --> M\n I --> M\n K --> M\n```\n\nEach resolver returns a `ResolvedSource` object containing the original source, resolved local path, and content type:\n\n```typescript\ninterface ResolvedSource {\n originalSource: string; // The user's original input\n localPath: string; // Absolute path to resolved content\n type: SourceType; // 'local' | 'git' | 'http-file' | 'inline-json' | 'inline-md'\n tempDir?: string; // Temp directory if content was downloaded/generated\n}\n```\n\n资料来源：[src/source/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/index.ts)\n\n## Source Types\n\n### Local Files and Directories\n\nThe local resolver handles filesystem paths beginning with `./`, `../`, `/`, or `~`. It performs the following operations:\n\n1. **Path normalization**: Expands `~` to home directory and resolves relative paths to absolute paths\n2. **Existence verification**: Confirms the path exists on the filesystem\n3. **Directory detection**: For directory sources, scans for matching asset files\n\n```typescript\n// Supported path formats\n'./mcps/playwright.json' // Relative path\n'/absolute/path/to/file' // Absolute path\n'~/dotfiles/mcp.json' // Home directory expansion\n'../shared/rules.md' // Parent directory relative path\n```\n\n资料来源：[src/source/local.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/local.ts)\n\n### Git URLs\n\nThe Git resolver supports both SSH and HTTPS Git URLs with optional path fragment syntax for sparse checkout:\n\n| Format | Example | Behavior |\n|--------|---------|----------|\n| SSH | `git@github.com:user/repo.git#path/to/asset` | Clones via SSH, extracts specified path |\n| HTTPS | `https://github.com/user/repo.git#path/to/asset` | Clones via HTTPS, extracts specified path |\n| Without fragment | `git@github.com:user/repo.git` | Clones entire repository |\n\n**Sparse Checkout Behavior**\n\nWhen a `#path` fragment is specified, the resolver performs a sparse checkout, downloading only the specified directory or file. This is particularly useful for monorepos where only specific assets are needed.\n\n```typescript\n// Example: Extract only the playwright skill from a monorepo\ngit@github.com:anthropics/skills.git#skills/playwright\n```\n\nThe resolver supports both formats:\n- **Directory path**: Extracts all files within the directory\n- **File path**: Extracts a single file\n\n资料来源：[src/source/git.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/git.ts)\n\n### HTTP/HTTPS URLs\n\nThe HTTP resolver downloads files directly from web URLs. It supports:\n\n- Direct file downloads from any HTTP/HTTPS endpoint\n- Automatic filename extraction from URL path\n- Integrity verification of downloaded content\n\n**Supported Asset Types for HTTP:**\n\n| Asset Type | HTTP Support |\n|------------|--------------|\n| MCP | ✅ Yes |\n| Skill | ❌ No (validation rejects) |\n| Prompt | ✅ Yes |\n| Command | ✅ Yes |\n| Sub-agent | ✅ Yes |\n\n资料来源：[src/source/http-file.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/http-file.ts)\n\n### Inline Content\n\nInline sources allow embedding asset content directly in the command line, eliminating the need for separate files or remote URLs. The system auto-detects content type based on format.\n\n#### Inline JSON (MCP Only)\n\nSources beginning with `{` are treated as inline JSON. The format supports MCP configuration in two structures:\n\n**Format A: Inner config (single server)**\n```json\n{\"command\":\"npx\",\"args\":[\"@playwright/mcp@latest\"]}\n```\nAsset name is inferred from the MCP config filename.\n\n**Format B: Wrapped config with `mcpServers`**\n```json\n{\"mcpServers\":{\"playwright\":{\"command\":\"npx\",\"args\":[\"@playwright/mcp@latest\"]}}}\n```\nThe wrapper is automatically unwrapped and the inner server name becomes the asset name.\n\n```bash\n# Example command\nnpx -y agent-add --host cursor \\\n --mcp '{\"playwright\":{\"command\":\"npx\",\"args\":[\"@playwright/mcp\"]}}'\n```\n\n资料来源：[src/source/inline.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/inline.ts)\n\n#### Inline Markdown (Prompt/Command/Sub-agent)\n\nSources containing `\\n` (newline) are treated as inline Markdown. This applies to:\n\n- **Prompt files**: System prompts and rule files\n- **Command files**: Slash commands\n- **Sub-agent files**: Agent configurations\n\nThe asset name is inferred from the first `# Heading` in the content, converted to kebab-case:\n\n```markdown\n# Code Review Rules\n\nAlways review for security first.\n```\n→ Asset name: `code-review-rules`\n\n```bash\n# Example command\nnpx -y agent-add --host claude-code \\\n --prompt $'# Code Review Rules\\n\\nAlways review for security issues first.'\n```\n\n资料来源：[src/source/inline.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/inline.ts)\n资料来源：[src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n\n## Asset Name Inference\n\nThe `infer-name.ts` module extracts consistent asset names from diverse source formats. This ensures uniform naming regardless of how the asset is referenced.\n\n### Name Inference Rules\n\n| Source Type | Rule | Example Input | Inferred Name |\n|-------------|------|---------------|---------------|\n| Inline JSON | Extract top-level key | `{\"playwright\":{...}}` | `playwright` |\n| Inline Markdown | First `# Heading` → kebab-case | `# Code Review` | `code-review` |\n| Git URL + `#path` | Last segment, strip extension | `...git#skills/pdf` | `pdf` |\n| Git URL without `#` | Repository name, strip `.git` | `...playwright.git` | `playwright` |\n| Local path / HTTP | Filename, strip extension | `./mcps/playwright.json` | `playwright` |\n\n### Inline JSON Parsing\n\nWhen processing inline JSON sources:\n\n1. Parse the JSON string into an object\n2. If the object has an `mcpServers` wrapper, unwrap it\n3. Extract the top-level key as the asset name\n4. If multiple keys exist, throw an error (inline JSON supports single MCP only)\n\n```typescript\n// Single server (inner format) - name from source metadata\n{\"command\":\"npx\",\"args\":[\"@playwright/mcp\"]} // ❌ No name, requires filename inference\n\n// Single server (wrapped format) - name from key\n{\"mcpServers\":{\"playwright\":{...}}} // ✅ Name is \"playwright\"\n```\n\n资料来源：[src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n\n## Temporary File Management\n\nSource Resolution manages temporary directories to ensure clean operation:\n\n1. **Downloaded content**: HTTP and Git downloads are stored in temporary directories\n2. **Inline content**: Generated files (from inline JSON/Markdown) are written to temp files\n3. **Cleanup**: Temp directories are cleaned up after installation completes\n\nThe `AGENT_ADD_HOME` environment variable can override the default temp directory location, useful for test isolation:\n\n```bash\nAGENT_ADD_HOME=/tmp/test-home npx -y agent-add --host cursor --mcp '{\"test\":{...}}'\n```\n\n资料来源：[src/source/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/index.ts)\n\n## Integration with Installation Pipeline\n\nSource Resolution integrates into the broader installation workflow as follows:\n\n```mermaid\ngraph LR\n A[CLI Input] --> B[Source Resolution]\n B --> C[ResolvedSource]\n C --> D[Validation]\n D --> E[InstallJob Creation]\n E --> F[Asset Handler Execution]\n F --> G[InstallResult]\n \n B -.->|Inline sources| H[Temp File Generation]\n B -.->|Git/HTTP sources| I[Download to Temp]\n```\n\nAfter resolution, the `installer.ts` module performs validation based on asset type:\n\n- **MCP**: File must exist and have `.json` extension\n- **Skill**: Must be a directory containing `SKILL.md`\n- **Prompt/Command/Sub-agent**: No additional validation at this stage\n\n```typescript\n// From src/installer.ts - validation logic\nif (assetType === 'skill') {\n if (resolved.type === 'http-file' || resolved.type === 'inline-json' || resolved.type === 'inline-md') {\n return 'Skill assets must point to directory sources (local path or Git URL)';\n }\n const skillMdPath = path.join(resolved.localPath, 'SKILL.md');\n // ...\n}\n```\n\n资料来源：[src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n\n## Error Handling\n\nThe resolution system provides specific error messages for common failures:\n\n| Error Condition | Message |\n|-----------------|---------|\n| Inline JSON parse failure | `内联 JSON 解析失败。格式应为 {\"\":{...}}` |\n| Inline JSON not object | `内联 JSON 必须为对象类型` |\n| Multiple keys in inline JSON | Error listing unsupported multiple keys |\n| Directory empty (skill) | `No matching files found in directory` |\n| SKILL.md missing | `Skill 目录内缺少 SKILL.md 文件` |\n| MCP file missing | `MCP 来源文件不存在` |\n| MCP wrong extension | `MCP 来源文件扩展名必须为 .json` |\n| HTTP for Skill | `Skill 资产必须指向目录来源` |\n\nAll errors result in process exit with code 2, ensuring CI/CD pipelines fail fast on configuration issues.\n\n资料来源：[src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n资料来源：[src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n\n---\n\n\n\n## Asset Types\n\n### 相关页面\n\n相关主题：[Manifest System](#manifest-system), [Host Integration](#host-integration)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/manifest/schema.ts](https://github.com/pea3nut/agent-add/blob/main/src/manifest/schema.ts)\n- [src/manifest/parser.ts](https://github.com/pea3nut/agent-add/blob/main/src/manifest/parser.ts)\n- [vibe/manifest.json](https://github.com/pea3nut/agent-add/blob/main/vibe/manifest.json)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n- [src/assets/mcp.ts](https://github.com/pea3nut/agent-add/blob/main/src/assets/mcp.ts)\n- [src/assets/skill.ts](https://github.com/pea3nut/agent-add/blob/main/src/assets/skill.ts)\n- [src/assets/prompt.ts](https://github.com/pea3nut/agent-add/blob/main/src/assets/prompt.ts)\n- [src/assets/command.ts](https://github.com/pea3nut/agent-add/blob/main/src/assets/command.ts)\n- [src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n
\n\n# Asset Types\n\nAsset Types define the categories of installable resources that agent-add can distribute to AI coding assistant hosts. The system supports five distinct asset types, each with specific file formats, validation rules, and installation behaviors.\n\n## Overview\n\nagent-add categorizes all distributable resources into five asset types. Each type has a dedicated handler responsible for installation logic, validation, and host-specific write strategies.\n\n```mermaid\ngraph TD\n A[User Input / Pack Manifest] --> B{Asset Type Detection}\n B -->|JSON| C[MCP Server]\n B -->|Directory + SKILL.md| D[Skill]\n B -->|Markdown| E[Prompt]\n B -->|Markdown + Frontmatter| F[Command]\n B -->|Markdown + Agent Meta| G[Sub-agent]\n \n C --> H[Validation]\n D --> H\n E --> H\n F --> H\n G --> H\n \n H --> I[Host Adapter]\n I --> J[Write Strategy]\n J --> K[Host Filesystem]\n```\n\n## Supported Asset Types\n\n| Asset Type | Identifier | Source Format | Validation Requirement |\n|------------|------------|---------------|------------------------|\n| MCP Server | `mcp` | JSON file | `.json` extension required |\n| Skill | `skill` | Directory | Must contain `SKILL.md` |\n| Prompt | `prompt` | Markdown file | First `# Heading` required |\n| Command | `command` | Markdown with YAML frontmatter | Optional description field |\n| Sub-agent | `subAgent` | Markdown with YAML frontmatter | Optional host specialization |\n\n资料来源：[src/manifest/schema.ts]() and [src/manifest/parser.ts:30-35]()\n\n## MCP Server (`mcp`)\n\nMCP Servers provide Model Context Protocol configurations that enable AI assistants to interact with external tools and services.\n\n### Supported JSON Formats\n\nagent-add auto-detects two MCP configuration formats:\n\n**Format A: Inner Config (Single Server)**\n\n```json\n{\n \"command\": \"npx\",\n \"args\": [\"@playwright/mcp@latest\"],\n \"env\": {}\n}\n```\n\nThe asset name is inferred from the filename: `playwright.json` → name is `playwright`.\n\n**Format B: Full Config with `mcpServers` Wrapper**\n\n```json\n{\n \"mcpServers\": {\n \"playwright\": {\n \"command\": \"npx\",\n \"args\": [\"@playwright/mcp@latest\"]\n }\n }\n}\n```\n\nagent-add automatically unwraps the `mcpServers` object and extracts the inner server name and configuration. This format currently supports a single server only.\n\n资料来源：[README.md - Asset Developer Guide](README.md)\n\n### Installation Behavior\n\n- **JSON shallow merge**: New servers are merged into existing configuration\n- **Atomic write**: Uses temp file + rename for safe writes\n- **TOML support**: `.toml` extension auto-dispatches to TOML parsing path for Codex and Vibe hosts\n\n```mermaid\ngraph LR\n A[MCP JSON Input] --> B{Extension Check}\n B -->|.json| C[JSON Handler]\n B -->|.toml| D[TOML Handler]\n C --> E[Shallow Merge]\n D --> E\n E --> F[Atomic Write]\n F --> G[host mcp config]\n```\n\n## Skill (`skill`)\n\nSkills are reusable agent capabilities distributed as directory bundles.\n\n### Structure Requirements\n\nA valid Skill asset must be a directory containing a `SKILL.md` file at its root:\n\n```\nhelpers/\n├── utils.py\n└── templates/\n └── report.md\n```\n\nThe `SKILL.md` file defines the skill metadata:\n\n```markdown\n---\nname: my-skill\ndescription: A reusable agent skill.\n---\n\n# Skill: my-skill\n\nThis skill does something useful.\n```\n\n### Installation Behavior\n\n- **Directory copy**: Entire directory is recursively copied to host's skills directory\n- **Location**: Installed to `.cursor/skills/my-skill/` (path varies by host)\n- **Validation**: Refuses installation if `SKILL.md` is missing\n\n资料来源：[src/installer.ts:85-93]()\n\n### Source Restrictions\n\nSkills have strict source requirements:\n\n| Allowed Source | Description |\n|----------------|-------------|\n| Local directory path | `~/path/to/skill` |\n| Git URL | `https://github.com/user/repo.git#path/to/skill` |\n\n| Prohibited Source | Reason |\n|-------------------|--------|\n| HTTP(S) URL | Not supported |\n| Inline JSON | Not supported |\n| Inline Markdown | Not supported |\n\n资料来源：[src/installer.ts:85-93]()\n\n## Prompt (`prompt`)\n\nPrompts are rule files or system prompts that define agent behavior guidelines.\n\n### Installation Strategies\n\nPrompts use different write strategies based on host capabilities:\n\n**Append Mode** (Cursor, Claude Code, etc.)\n\nContent is wrapped in HTML comment markers and appended idempotently:\n\n```html\n\n# Code Review Rules\n\nAlways review for security issues first.\nUse bullet points for lists.\n\n```\n\n**Standalone File Mode** (Windsurf, Roo Code, etc.)\n\nCreates a `.md` file in the rules directory:\n\n```\n.windsurf/rules/code-review-rules.md\n```\n\n资料来源：[README.md - Prompt File]()\n\n### Naming Convention\n\nThe asset name is inferred from the first `# Heading` in the Markdown content:\n\n```markdown\n# Code Review Rules\n```\n\n→ Asset name: `code-review-rules`\n\n## Command (`command`)\n\nCommands are slash commands that users can invoke directly in the AI assistant interface.\n\n### File Format\n\nCommands are Markdown files with optional YAML frontmatter:\n\n```markdown\n---\ndescription: Run a comprehensive code review.\n---\n\n# code-review\n\nReview the current file for bugs, security issues, and style violations.\n```\n\n### Installation Behavior\n\n- **Installation directory**: Host-specific commands directory (e.g., `.cursor/commands/`)\n- **File extension**: `.md`\n- **Naming**: Derived from filename or `# Heading`\n\n## Sub-agent (`subAgent`)\n\nSub-agents are specialized AI agents with their own configuration and instructions.\n\n### File Format\n\nSub-agents use Markdown with YAML frontmatter, supporting host specialization:\n\n```markdown\n---\nname: playwright-tester\ndescription: A playwright testing agent.\nagent-add/cursor/model: fast\nagent-add/claude-code/model: haiku\n---\n\n# Playwright Test Agent\n\nPlan and generate Playwright tests.\n```\n\n### Host Specialization Syntax\n\nThe `agent-add//` syntax allows different frontmatter values per host:\n\n```mermaid\ngraph TD\n A[Sub-agent File] --> B[Installation Time]\n B --> C{Current Host}\n C -->|Cursor| D[Extract agent-add/cursor/*]\n C -->|Claude Code| E[Extract agent-add/claude-code/*]\n \n D --> F[Promote to top-level keys]\n E --> F\n F --> G[Remove agent-add/* prefixes]\n G --> H[Install Result]\n```\n\n**After installing to Cursor:**\n\n```markdown\n---\nname: playwright-tester\ndescription: A playwright testing agent.\nmodel: fast\n---\n\n# Playwright Test Agent\n```\n\n**After installing to Claude Code:**\n\n```markdown\n---\nname: playwright-tester\ndescription: A playwright testing agent.\nmodel: haiku\n---\n\n# Playwright Test Agent\n```\n\n## Asset Validation\n\nEach asset type undergoes validation before installation:\n\n```mermaid\ngraph TD\n A[Resolved Source] --> B{Asset Type}\n \n B -->|skill| C{Directory Check}\n C -->|Missing SKILL.md| D[Error: Exit 2]\n C -->|Valid| E[Pass]\n \n B -->|mcp| F{File Check}\n F -->|File not exist| G[Error: Exit 2]\n F -->|.json extension?| H[Error: Exit 2]\n F -->|Valid| E\n \n B -->|prompt| I{Name from Heading}\n I -->|No heading| J[Error: Exit 2]\n I -->|Valid| E\n \n B -->|command| I\n B -->|subAgent| I\n```\n\n资料来源：[src/installer.ts:71-101]()\n\n### Validation Rules by Type\n\n| Asset Type | Checks |\n|------------|--------|\n| `mcp` | File exists, `.json` extension |\n| `skill` | Directory exists, contains `SKILL.md` |\n| `prompt` | First `# Heading` exists (for name inference) |\n| `command` | First `# Heading` exists |\n| `subAgent` | First `# Heading` exists |\n\n## Pack Manifest Integration\n\nAsset types are bundled in pack manifests for distribution:\n\n```json\n{\n \"name\": \"my-team/frontend-pack\",\n \"assets\": [\n { \"type\": \"mcp\", \"source\": \"https://github.com/modelcontextprotocol/servers.git#.mcp.json\" },\n { \"type\": \"skill\", \"source\": \"https://github.com/anthropics/skills.git#skills/pdf\" },\n { \"type\": \"prompt\", \"source\": \"https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/nextjs-react-tailwind/.cursorrules\" },\n { \"type\": \"command\", \"source\": \"https://github.com/wshobson/commands.git#tools/security-scan.md\" },\n { \"type\": \"subAgent\", \"source\": \"https://github.com/VoltAgent/awesome-claude-code-subagents.git#categories/01-core-development/backend-developer.md\" }\n ]\n}\n```\n\n### Asset Name Inference Rules\n\nWhen a pack manifest doesn't specify an asset name, it is inferred from the source:\n\n| Source Pattern | Name Inference |\n|----------------|----------------|\n| Git URL + `#path` | Last segment after `#`, strip extension |\n| Git URL without `#` | Repo name, strip `.git` suffix |\n| Local path / HTTP | Filename, strip extension |\n| Inline JSON `{...}` | Top-level key as MCP name |\n| Inline Markdown with `\\n` | First `# Heading` in kebab-case |\n\n资料来源：[src/source/infer-name.ts]()\n\n---\n\n\n\n## Manifest System\n\n### 相关页面\n\n相关主题：[Asset Types](#asset-types), [CLI Interface](#cli-interface)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/manifest/parser.ts](https://github.com/pea3nut/agent-add/blob/main/src/manifest/parser.ts)\n- [src/manifest/schema.ts](https://github.com/pea3nut/agent-add/blob/main/src/manifest/schema.ts)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n- [src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n- [vibe/manifest.json](https://github.com/pea3nut/agent-add/blob/main/vibe/manifest.json)\n- [README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n
\n\n# Manifest System\n\nThe Manifest System is a core component of agent-add that enables batch installation of multiple assets through a single JSON configuration file. It provides a declarative way to define, distribute, and install a collection of AI agent assets (MCPs, Skills, Prompts, Commands, and Sub-agents) as a single package.\n\n## Overview\n\nAgent Packs are JSON files that bundle multiple assets together, allowing developers and teams to share complete asset collections with a single reference. The Manifest System handles parsing, validation, and processing of these pack manifests.\n\n```mermaid\ngraph TD\n A[Pack Manifest JSON] --> B[Manifest Parser]\n B --> C{Validation}\n C -->|Pass| D[Asset Descriptor Array]\n C -->|Fail| E[Error Exit 2]\n D --> F[Source Resolver]\n F --> G[Install Jobs]\n G --> H[Asset Handlers]\n H --> I[Host Installation]\n```\n\n## Manifest File Format\n\n### Schema Structure\n\nThe manifest schema is defined using Zod for runtime validation. The file path to the schema definition is:\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `name` | `string` | Yes | Pack identifier in `namespace/pack-name` format. Only `[a-zA-Z0-9_-]` characters allowed |\n| `assets` | `Asset[]` | Yes | Array of asset definitions, minimum 1 item |\n\n### Asset Definition\n\nEach asset in the `assets` array has the following structure:\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `type` | `string` | Yes | Asset type: `mcp`, `skill`, `prompt`, `command`, or `subAgent` |\n| `source` | `string` | Yes | Source location (Git URL, local path, or HTTP URL) |\n\n资料来源：[README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n\n### Example Manifest\n\n```json\n{\n \"name\": \"my-team/frontend-pack\",\n \"assets\": [\n { \"type\": \"mcp\", \"source\": \"https://github.com/modelcontextprotocol/servers.git#/.mcp.json\" },\n { \"type\": \"skill\", \"source\": \"https://github.com/anthropics/skills.git#skills/pdf\" },\n { \"type\": \"prompt\", \"source\": \"https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/nextjs-react-tailwind/.cursorrules\" },\n { \"type\": \"command\", \"source\": \"https://github.com/wshobson/commands.git#tools/security-scan.md\" },\n { \"type\": \"subAgent\", \"source\": \"https://github.com/VoltAgent/awesome-claude-code-subagents.git#categories/01-core-development/backend-developer.md\" }\n ]\n}\n```\n\n资料来源：[README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n\n## Source Syntax for Manifests\n\nThe manifest parser supports multiple source formats that are resolved to local paths:\n\n```mermaid\ngraph LR\n A[Source String] --> B{Format Detection}\n B --> C[#path segment]\n B --> D[Git URL .git suffix]\n B --> E[Local/HTTP path]\n \n C --> F[kebab-case name from path]\n D --> G[repo name without .git]\n E --> H[filename without extension]\n```\n\n### Source Resolution Rules\n\n| Source Format | Name Extraction Rule | Example |\n|--------------|---------------------|---------|\n| Git URL with `#path` | Take last segment after `#`, strip extension | `...git#skills/pdf` → `pdf` |\n| Git URL without `#` | Take repo name, strip `.git` suffix | `...playwright.git` → `playwright` |\n| Local path / HTTP URL | Take filename, strip extension | `./mcps/playwright.json` → `playwright` |\n\n资料来源：[src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n\n### Inline Sources\n\nManifests support two inline source formats:\n\n| Format | Detection | Name Source |\n|--------|-----------|-------------|\n| `inline-json` | Starts with `{` | Single top-level JSON key |\n| `inline-md` | Contains `\\n` (newlines) | First `# Heading` in Markdown, converted to kebab-case |\n\nBoth inline sources are written to temporary files before following the normal installation flow.\n\n## Parser Implementation\n\n### Entry Point\n\nThe manifest parser is invoked from the installer orchestrator. When `--pack` flags are detected, the parser processes each manifest file:\n\n```mermaid\nsequenceDiagram\n participant CLI as CLI Input\n participant Inst as Installer\n participant MP as Manifest Parser\n participant SR as Source Resolver\n \n CLI->>Inst: pack: [manifest.json, ...]\n Inst->>MP: parseManifest(filePath)\n MP->>MP: Read JSON file\n MP->>MP: Zod validation\n alt Valid\n MP-->>Inst: ManifestData[]\n else Invalid\n MP->>Inst: Error + Exit 2\n end\n Inst->>SR: Resolve each asset source\n```\n\n### Validation Flow\n\nThe parser performs comprehensive validation using Zod schema validation:\n\n1. **Schema validation**: Checks required fields and types\n2. **Name format validation**: Ensures `name` matches `namespace/pack-name` pattern\n3. **Asset type validation**: Verifies all `type` fields are in the allowed set\n4. **Error reporting**: Provides specific error messages with field paths\n\n资料来源：[src/manifest/parser.ts](https://github.com/pea3nut/agent-add/blob/main/src/manifest/parser.ts)\n\n### Error Handling\n\nThe parser provides structured error messages for common validation failures:\n\n| Error Condition | Message |\n|-----------------|---------|\n| Invalid asset type | `Unsupported asset type: ''. Supported: mcp, skill, prompt, command, subAgent` |\n| Invalid name format | `Manifest name must match namespace/pack-name format` |\n| Missing required field | `Manifest missing required field: ` |\n| JSON parse failure | `Invalid Manifest format` |\n\n资料来源：[src/manifest/parser.ts](https://github.com/pea3nut/agent-add/blob/main/src/manifest/parser.ts)\n\n## Integration with Installer\n\n### Processing Pipeline\n\n```mermaid\ngraph TD\n subgraph Input Processing\n A[Pack Manifests] --> B[Parse Each Manifest]\n B --> C[Extract Asset Descriptors]\n end\n \n subgraph Resolution\n C --> D[Resolve Sources]\n D --> E[Validate Each Asset]\n end\n \n subgraph Job Creation\n E --> F{Capability Check}\n F -->|Supported| G[Create Install Job]\n F -->|Unsupported| H[Skip Result]\n end\n \n subgraph Execution\n G --> I[Execute Handler]\n I --> J[Install Result]\n end\n```\n\n### Manifest Processing in Installer\n\nThe installer processes manifests in the following sequence:\n\n1. **Parse**: Each manifest file is parsed to extract asset descriptors\n2. **Resolve**: Asset sources are resolved to local file paths\n3. **Validate**: Each asset is validated according to its type requirements\n4. **Filter**: Assets unsupported by the target host are skipped\n5. **Execute**: Valid assets are processed by appropriate handlers\n\n资料来源：[src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n\n### Skip Behavior for Pack Sources\n\nUnlike explicit flag sources, pack sources that target unsupported asset types are **silently skipped** rather than causing errors. This design allows pack authors to create cross-host compatible manifests without requiring per-host manifest files.\n\n> Note: This is different from explicit flags, which exit with error code 2 if the asset type is unsupported.\n\n## CLI Usage\n\n### Installing a Pack\n\n```bash\n# Single pack installation\nnpx -y agent-add --host cursor --pack ./manifest.json\n\n# Multiple packs\nnpx -y agent-add --host claude-code \\\n --pack ./frontend-pack.json \\\n --pack ./backend-pack.json\n\n# Combined with explicit assets\nnpx -y agent-add --host cursor \\\n --pack ./team-pack.json \\\n --mcp ./local-mcp.json\n```\n\n### All `--pack` Flag Options\n\n| Flag | Description | Collectable |\n|------|-------------|-------------|\n| `--pack ` | Install an Agent Pack manifest | Yes (repeatable) |\n\nAll asset flags can be repeated and freely combined with `--pack`.\n\n## Development and Testing\n\n### Test Coverage\n\nThe manifest system is tested through:\n\n| Test Type | Location | Purpose |\n|-----------|----------|---------|\n| Unit tests | `tests/unit/` | Parser validation, name inference |\n| Contract tests | `tests/contract/` | CLI black-box behavior |\n| Feature tests | `tests/features/` | End-to-end scenarios |\n\n### Running Tests\n\n```bash\n# All unit + integration tests\nnpm test\n\n# Contract tests only\nnpm run test:contract\n\n# Single manifest parser test\nnpx vitest run tests/unit/manifest/parser.test.ts\n```\n\n### Development Setup\n\n```bash\nnpm install\nnpm run build\nnpm run install:vibe # Installs dev assets via pack manifest\n```\n\nThe `install:vibe` command installs assets defined in `vibe/manifest.json`, demonstrating the pack manifest system in action.\n\n## Related Components\n\n| Component | File | Role |\n|-----------|------|------|\n| Schema | `src/manifest/schema.ts` | Zod schema definition for ManifestData |\n| Parser | `src/manifest/parser.ts` | Parsing and validation logic |\n| Name Inference | `src/source/infer-name.ts` | Extracts asset names from sources |\n| Installer | `src/installer.ts` | Orchestrates manifest processing |\n| CLI | `src/cli.ts` | Command-line argument handling |\n\n## Key Design Decisions\n\n| Decision | Rationale |\n|----------|-----------|\n| Pack sources skip unsupported types | Enables cross-host manifest sharing without per-host variants |\n| Explicit flags error on unsupported types | Forces developers to handle host compatibility explicitly |\n| Atomic JSON writes for MCP | Ensures config file integrity during concurrent operations |\n| Temp file + rename strategy | Provides atomicity for manifest-based MCP installations |\n| Zod for schema validation | Runtime type checking with detailed error messages |\n\n---\n\n\n\n## CLI Interface\n\n### 相关页面\n\n相关主题：[Getting Started](#getting-started), [Manifest System](#manifest-system)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n- [src/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/index.ts)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n- [bin/agent-add.js](https://github.com/pea3nut/agent-add/blob/main/bin/agent-add.js)\n- [package.json](https://github.com/pea3nut/agent-add/blob/main/package.json)\n
\n\n# CLI Interface\n\nThe CLI Interface is the primary user-facing component of agent-add, responsible for command-line argument parsing, host detection, input validation, and orchestrating the installation workflow. It serves as the entry point for all asset installation operations.\n\n## Overview\n\nagent-add provides a unified command-line interface for installing MCP servers, Skills, Prompts, Commands, and Sub-agents across 18 different AI agent hosts. The CLI handles argument parsing using the `commander` library and delegates actual installation logic to the `installer` module.\n\n```mermaid\ngraph TD\n A[User CLI Command] --> B[bin/agent-add.js]\n B --> C[src/index.ts]\n C --> D[src/cli.ts - createProgram]\n D --> E[program.parseAsync process.argv]\n E --> F[Input Validation]\n F --> G[runInstaller cliInput, host, cwd]\n G --> H[printSummary results]\n H --> I[Exit: 0=success, 1=conflict/error, 2=validation]\n```\n\n资料来源：[src/index.ts:1-8](https://github.com/pea3nut/agent-add/blob/main/src/index.ts)\n\n## Entry Points\n\n### Binary Entry Point\n\nThe CLI binary is defined at `bin/agent-add.js` and serves as the executable entry point for the npm package. It is registered in `package.json` under the `bin` field.\n\n```javascript\n#!/usr/bin/env node\nimport '../dist/index.js';\n```\n\n资料来源：[bin/agent-add.js](https://github.com/pea3nut/agent-add/blob/main/bin/agent-add.js)\n\n### Module Entry Point\n\nThe TypeScript module entry at `src/index.ts` creates the program and handles top-level error catching:\n\n```typescript\nimport { createProgram } from './cli.js';\n\nconst program = createProgram();\nprogram.parseAsync(process.argv).catch((err: Error) => {\n process.stderr.write(`agent-add error: ${err.message}\\n`);\n process.exit(2);\n});\n```\n\n资料来源：[src/index.ts:1-8](https://github.com/pea3nut/agent-add/blob/main/src/index.ts)\n\n## Command Structure\n\n### Global Options\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `--host ` | string | Target host ID (cursor, claude-code, claude-desktop, etc.) |\n| `-V, --version` | boolean | Show version number |\n| `-h, --help` | boolean | Show help information |\n\n### Asset Installation Flags\n\nAll asset flags can be repeated to install multiple assets of the same type and can be freely combined with `--pack`:\n\n| Flag | Type | Description |\n|------|------|-------------|\n| `--pack ` | string[] | Install an Agent Pack manifest |\n| `--mcp ` | string[] | Install an MCP server config |\n| `--skill ` | string[] | Install a Skill directory |\n| `--prompt ` | string[] | Install a Prompt file |\n| `--command ` | string[] | Install a Command file |\n| `--sub-agent ` | string[] | Install a Sub-agent file |\n\n资料来源：[src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n\n## Command Definition\n\nThe `createProgram()` function in `src/cli.ts` defines the Commander program structure:\n\n```typescript\nfunction createProgram() {\n const program = new Command();\n\n program\n .name('agent-add')\n .description('Install AI agent assets into different hosts')\n .argument('[sources...]', 'Sources to install')\n .option('--pack ', 'Install an Agent Pack manifest', collect, [])\n .option('--mcp ', 'Install an MCP server', collect, [])\n .option('--skill ', 'Install a Skill directory', collect, [])\n .option('--prompt ', 'Install a Prompt file', collect, [])\n .option('--command ', 'Install a Command file', collect, [])\n .option('--sub-agent ', 'Install a Sub-agent file', collect, [])\n .option('--host ', 'Target host ID', collect, [])\n .action(async (options) => { /* ... */ });\n\n return program;\n}\n```\n\n资料来源：[src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n\n## Input Collection\n\nThe `collect()` helper function accumulates multiple values when flags are repeated:\n\n```typescript\nfunction collect(value: string, previous: string[]): string[] {\n return [...previous, value];\n}\n```\n\nThis enables usage patterns like:\n```bash\nagent-add --mcp server1.json --mcp server2.json --skill ./my-skill\n```\n\n资料来源：[src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n\n## Input Validation Flow\n\n```mermaid\ngraph TD\n A[Parse CLI Options] --> B{Has Asset Flags?}\n B -->|No| C[Error: No asset flags provided]\n C --> D[Exit 2]\n B -->|Yes| E{Host Specified?}\n E -->|No| F{TTY Mode?}\n F -->|Yes| G[Interactive Host Selection]\n F -->|No| H[Error: --host required in CI]\n G --> I[Selected Host]\n E -->|Yes| I\n I --> J[runInstaller cliInput, host, cwd]\n J --> K[printSummary]\n K --> L{Results contain errors?}\n L -->|Yes| M[Exit 1]\n L -->|No| N[Exit 0]\n```\n\n### Asset Flag Validation\n\nBefore proceeding, the CLI verifies at least one asset flag is provided:\n\n```typescript\nconst hasAssetFlags =\n cliInput.pack.length > 0 ||\n cliInput.mcp.length > 0 ||\n cliInput.skill.length > 0 ||\n cliInput.prompt.length > 0 ||\n cliInput.command.length > 0 ||\n cliInput.subAgent.length > 0;\n\nif (!hasAssetFlags) {\n process.stderr.write(\n 'agent-add error: No asset flags provided. Use --pack, --mcp, --skill, --prompt, --command, or --sub-agent.\\n',\n );\n process.exit(2);\n}\n```\n\n资料来源：[src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n\n## Host Selection\n\n### Explicit Host Specification\n\nWhen `--host` is explicitly provided, it is used directly:\n\n```typescript\nif (cliInput.host) {\n hostId = cliInput.host;\n}\n```\n\n### Interactive Host Selection\n\nIn TTY (interactive) mode, if no host is specified, the CLI presents an interactive selection menu:\n\n```typescript\nelse if (process.stdout.isTTY) {\n const selected = await inquirer.prompt([{\n type: 'select',\n name: 'host',\n message: 'Select your AI agent host:',\n choices: getValidHostIds(),\n }]);\n hostId = selected.host;\n}\n```\n\n### Non-TTY Strict Mode\n\nIn CI/non-interactive environments, the CLI requires explicit host specification and exits with code 2 if missing:\n\n```typescript\nelse {\n const validIds = getValidHostIds().join(', ');\n process.stderr.write(\n `agent-add error: --host flag required in non-TTY environment. Valid hosts: ${validIds}\\n`,\n );\n process.exit(2);\n}\n```\n\n资料来源：[src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n\n## CliInput Data Model\n\nThe `CliInput` interface defines the internal representation of parsed CLI arguments:\n\n```typescript\ninterface CliInput {\n pack: string[];\n mcp: string[];\n skill: string[];\n prompt: string[];\n command: string[];\n subAgent: string[];\n host?: string;\n}\n```\n\nThis is populated from the command options and passed to the installer:\n\n```typescript\nconst cliInput: CliInput = {\n mcp: options.mcp,\n skill: options.skill,\n prompt: options.prompt,\n command: options.command,\n subAgent: options.subAgent,\n pack: options.pack,\n host: options.host,\n};\n```\n\n资料来源：[src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n\n## Error Handling\n\n### Top-Level Error Handler\n\nThe entry point catches all unhandled errors and exits with code 2:\n\n```typescript\nprogram.parseAsync(process.argv).catch((err: Error) => {\n process.stderr.write(`agent-add error: ${err.message}\\n`);\n process.exit(2);\n});\n```\n\n### Action-Level Error Handling\n\nThe main action also handles install results for conflicts and errors:\n\n```typescript\nconst hasConflicts = summary.results.some((r) => r.status === 'conflict');\nconst hasErrors = summary.results.some((r) => r.status === 'error');\n\nif (hasErrors || hasConflicts) {\n process.exit(1);\n}\n```\n\n## Exit Codes\n\n| Code | Meaning | Trigger |\n|------|---------|---------|\n| 0 | Success | All assets installed without errors or conflicts |\n| 1 | Partial failure | Install completed but had conflicts or errors |\n| 2 | Validation failure | Invalid input, missing flags, or unsupported operations |\n\n资料来源：[src/index.ts:6](https://github.com/pea3nut/agent-add/blob/main/src/index.ts) and [src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n\n## Usage Examples\n\n### Install Single Asset\n\n```bash\nnpx -y agent-add --host cursor --mcp ./playwright.json\n```\n\n### Install Multiple Assets\n\n```bash\nnpx -y agent-add --host claude-code \\\n --mcp ./mcp/servers.json \\\n --skill ./skills/pdf \\\n --prompt 'https://raw.githubusercontent.com/.../rules.md'\n```\n\n### Install via Pack Manifest\n\n```bash\nnpx -y agent-add --host cursor --pack ./manifest.json\n```\n\n### Interactive Mode\n\n```bash\nnpx -y agent-add --mcp ./server.json\n# (Prompts for host selection if in TTY mode)\n```\n\n资料来源：[README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n\n## Package Configuration\n\nThe CLI binary is registered in `package.json`:\n\n```json\n{\n \"bin\": {\n \"agent-add\": \"./bin/agent-add.js\"\n },\n \"type\": \"module\",\n \"engines\": {\n \"node\": \">=18\"\n }\n}\n```\n\n资料来源：[package.json](https://github.com/pea3nut/agent-add/blob/main/package.json)\n\n---\n\n\n\n## Testing\n\n### 相关页面\n\n相关主题：[Project Configuration](#configuration)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/pea3nut/agent-add/blob/main/package.json)\n- [README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n- [vibe/manifest.json](https://github.com/pea3nut/agent-add/blob/main/vibe/manifest.json)\n- [vibe/system-prompt.md](https://github.com/pea3nut/agent-add/blob/main/vibe/system-prompt.md)\n- [vibe/tasks/verify-host-readme.md](https://github.com/pea3nut/agent-add/blob/main/vibe/tasks/verify-host-readme.md)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n
\n\n# Testing\n\n## Overview\n\nThe agent-add project employs a multi-layered testing strategy to ensure reliability across different host environments and asset types. The testing infrastructure validates the CLI tool's functionality through unit tests, integration tests, contract tests, and scenario-based tests executed by AI agents.\n\n## Test Architecture\n\nThe testing framework is built on **Vitest** with a three-tier approach:\n\n```mermaid\ngraph TD\n A[Test Suite] --> B[Unit Tests]\n A --> C[Integration Tests]\n A --> D[Contract Tests]\n A --> E[Scenario Tests]\n \n B --> B1[vitest run]\n C --> C1[vitest run]\n D --> D1[Black-box CLI tests]\n E --> E1[AI Agent execution]\n \n style A fill:#e1f5fe\n style D fill:#fff3e0\n style E fill:#f3e5f5\n```\n\n## Test Configuration\n\nThe Vitest configuration is defined in `vitest.config.ts`:\n\n| Configuration Aspect | Value |\n|---------------------|-------|\n| Test Runner | Vitest 4.1.0 |\n| TypeScript Target | Node.js 18+ |\n| Test Location | `tests/` directory |\n| Run Command | `npm test` |\n\n## Test Categories\n\n### Unit Tests\n\nUnit tests verify individual components in isolation. Each host adapter has corresponding unit tests.\n\n**Test Location:** `tests/unit/hosts/.test.ts`\n\n**Example - Cursor Host Test:**\n```typescript\nnpx vitest run tests/unit/hosts/cursor.test.ts\n```\n\nUnit tests verify:\n- Adapter `id`, `displayName`, and `docs` values\n- Asset capabilities match the README matrix\n- Supported capabilities have required fields\n\n### Integration Tests\n\nIntegration tests validate the interaction between components.\n\n**Command:** `npm run test:integration`\n\n### Contract Tests\n\nContract tests perform black-box CLI testing without requiring the full test suite.\n\n**Command:** `npm run test:contract`\n\n### Scenario Tests\n\nScenario tests use Gherkin `.feature` files executed by AI agents via [scenario-test](https://github.com/pea3nut/scenario-test).\n\n**Location Structure:**\n```\ntests/\n├── features/\n│ ├── scenario-run-config.md # Run configuration\n│ ├── core/ # Core behavior tests (7 .feature files)\n│ └── host/ # Host compatibility tests (3 .feature files)\n└── fixtures/ # Static test fixtures\n```\n\n**Execution Commands:**\n```bash\n/scenario-exec tests/features/core\n/scenario-exec tests/features/host\n```\n\nEach scenario runs in an isolated temporary directory. The run configuration is defined in `tests/features/scenario-run-config.md`.\n\n## Test Fixtures\n\nStatic test fixtures support different asset types:\n\n```\ntests/fixtures/\n├── mcp/\n├── skill/\n├── prompt/\n├── command/\n├── sub-agent/\n└── pack/\n```\n\nFixtures are used by both unit tests and scenario tests to provide consistent test data.\n\n## Development Testing Workflow\n\n### Setup\n\nBefore running tests, build the project:\n\n```bash\nnpm install\nnpm run build\n```\n\n### Running Tests\n\n| Command | Purpose |\n|---------|---------|\n| `npm test` | All unit + integration tests |\n| `npm run test:contract` | CLI black-box contract tests only |\n| `npm run test:integration` | Integration tests |\n| `npx vitest run tests/unit/hosts/cursor.test.ts` | Single unit test file |\n\n### Vibe Development Assets\n\nThe project uses a custom testing manifest for development:\n\n**File:** `vibe/manifest.json`\n\n```json\n{\n \"name\": \"agent-add/dev-pack\",\n \"assets\": [\n { \"type\": \"skill\", \"source\": \"https://github.com/pea3nut/scenario-test.git#skills/scenario-test\" },\n { \"type\": \"command\", \"source\": \"https://github.com/pea3nut/scenario-test.git#commands/scenario-exec.md\" },\n { \"type\": \"subAgent\", \"source\": \"https://github.com/pea3nut/scenario-test.git#agents/scenario-case-runner.md\" },\n { \"type\": \"command\", \"source\": \"./vibe/tasks/verify-host-readme.md\" },\n { \"type\": \"prompt\", \"source\": \"./vibe/system-prompt.md\" }\n ]\n}\n```\n\nInstall dev assets via:\n```bash\nnpm run install:vibe\n```\n\nThis installs:\n- **scenario-test skill**: Provides testing infrastructure\n- **scenario-exec command**: Triggers scenario test execution\n- **scenario-case-runner sub-agent**: AI agent that executes scenarios\n- **verify-host-readme command**: Validates host README consistency\n- **system-prompt**: Development system prompt\n\n## Host README Verification\n\nThe `verify-host-readme.md` task validates consistency between the host capability matrix in `src/hosts/README.md` and actual adapter implementations.\n\n**Validation Criteria:**\n- Adapter configuration fields match README matrix values exactly\n- Unit tests assert exact values for every field\n- New host contributions must update both adapter and README\n\n## Linting and Type Checking\n\nBefore test execution, validate code quality:\n\n```bash\nnpm run lint # tsc --noEmit type checking\n```\n\n## Test Isolation\n\nThe testing framework ensures isolation through:\n\n1. **Temporary directories** - Scenario tests run in isolated temp directories\n2. **Temp file writes** - MCP config uses temp file + rename for safety\n3. **AGENT_ADD_HOME override** - Environment variable redirects install paths for test isolation\n\n## Dependencies\n\nTest infrastructure relies on:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| vitest | ^4.1.0 | Test runner |\n| tsx | ^4.21.0 | TypeScript execution |\n| typescript | ^5.9.3 | Type checking |\n| scenario-test | (external) | Scenario test framework |\n\n---\n\n\n\n## Project Configuration\n\n### 相关页面\n\n相关主题：[Testing](#testing)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/pea3nut/agent-add/blob/main/package.json)\n- [tsup.config.ts](https://github.com/pea3nut/agent-add/blob/main/tsup.config.ts)\n- [src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n- [src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n- [src/hosts/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/index.ts)\n- [src/assets/mcp.ts](https://github.com/pea3nut/agent-add/blob/main/src/assets/mcp.ts)\n- [src/assets/skill.ts](https://github.com/pea3nut/agent-add/blob/main/src/assets/skill.ts)\n- [src/assets/prompt.ts](https://github.com/pea3nut/agent-add/blob/main/src/assets/prompt.ts)\n- [src/manifest/schema.ts](https://github.com/pea3nut/agent-add/blob/main/src/manifest/schema.ts)\n
\n\n# Project Configuration\n\n## Overview\n\nThe agent-add project uses a multi-layered configuration system to support installing various asset types across 18 different AI coding hosts. The configuration architecture encompasses TypeScript compilation settings, build tooling via tsup, package metadata, host adapter definitions, asset handler configurations, and source resolution strategies.\n\nThe project targets Node.js 18+ and compiles to CommonJS format for maximum compatibility with AI coding tool environments. 资料来源：[package.json:17]()\n\n## Build System Configuration\n\n### tsup Build Configuration\n\nThe project uses [tsup](https://github.com/egoist/tsup) for TypeScript bundling, defined in `tsup.config.ts`:\n\n```typescript\nimport { defineConfig } from 'tsup';\n\nexport default defineConfig({\n entry: ['src/index.ts'],\n format: ['cjs'],\n target: 'node18',\n clean: true,\n sourcemap: true,\n dts: false,\n outDir: 'dist',\n noExternal: [/.*/],\n});\n```\n\n| Option | Value | Purpose |\n|--------|-------|---------|\n| `entry` | `['src/index.ts']` | Single entry point for CLI application |\n| `format` | `['cjs']` | CommonJS output format for Node.js compatibility |\n| `target` | `node18` | Transpile for Node.js 18 environment |\n| `clean` | `true` | Remove previous build artifacts before each build |\n| `sourcemap` | `true` | Generate source maps for debugging |\n| `dts` | `false` | Disable TypeScript declaration generation |\n| `outDir` | `'dist'` | Output directory for compiled files |\n| `noExternal` | `[/.*/]` | Bundle all dependencies into output |\n\n资料来源：[tsup.config.ts:1-11]()\n\n### Build Scripts\n\nThe npm scripts in `package.json` define the development workflow:\n\n```json\n{\n \"scripts\": {\n \"build\": \"tsup\",\n \"dev\": \"tsx watch src/index.ts\",\n \"test\": \"vitest run\",\n \"install:vibe\": \"npx -y agent-add -- --pack vibe/manifest.json\"\n }\n}\n```\n\n| Script | Command | Usage |\n|--------|---------|-------|\n| `build` | `tsup` | Compile TypeScript to JavaScript |\n| `dev` | `tsx watch src/index.ts` | Development mode with hot reload |\n| `test` | `vitest run` | Execute unit and integration tests |\n| `install:vibe` | `agent-add -- --pack vibe/manifest.json` | Install development assets via pack manifest |\n\n资料来源：[package.json:27-31]()\n\n## Package Configuration\n\n### Engine Requirements\n\n```json\n\"engines\": {\n \"node\": \">=18\"\n}\n```\n\nThe project requires Node.js 18 or higher due to ES module features and modern JavaScript APIs used throughout the codebase. 资料来源：[package.json:35-37]()\n\n### Core Dependencies\n\nThe project relies on several key runtime dependencies:\n\n| Dependency | Version | Purpose |\n|------------|---------|---------|\n| `commander` | ^14.0.3 | CLI argument parsing |\n| `smol-toml` | ^1.6.1 | TOML format parsing for Codex/Vibe hosts |\n| `yaml` | ^2.8.2 | YAML frontmatter parsing for sub-agents |\n| `zod` | ^4.3.6 | Manifest schema validation |\n\nDevelopment dependencies include TypeScript, vitest for testing, and tsx for development execution. 资料来源：[package.json:11-24]()\n\n## Host Adapter Configuration\n\n### Host Adapter Type System\n\nThe host configuration system uses a TypeScript interface defined in `src/hosts/types.ts`:\n\n```typescript\ninterface AssetCapability {\n supported: boolean;\n reason?: string;\n configFile?: string;\n installDir?: string;\n writeStrategy?: 'append-with-marker' | 'create-file-in-dir';\n}\n\ninterface HostAdapter {\n id: string;\n displayName: string;\n docs: string;\n assets: Record;\n}\n```\n\n资料来源：[src/hosts/types.ts]()\n\n### Host Capability Matrix\n\nThe project supports 18 distinct hosts, each with unique capability profiles:\n\n| Host ID | MCP | Prompt | Skill | Command | Sub-agent |\n|---------|-----|--------|-------|---------|-----------|\n| `cursor` | ✅ | ✅ | ✅ | ✅ | ✅ |\n| `claude-code` | ✅ | ✅ | ❌ | ✅ | ✅ |\n| `claude-desktop` | ✅ | ❌ | ❌ | ❌ | ❌ |\n| `windsurf` | ✅ | ✅ | ❌ | ❌ | ❌ |\n| `codex` | ✅ | ❌ | ❌ | ❌ | ❌ |\n| `vibe` | ✅ | ❌ | ❌ | ❌ | ❌ |\n\nEach host adapter hardcodes its configuration in a dedicated file under `src/hosts/.ts` and registers in `src/hosts/index.ts` through the host registry Map. 资料来源：[src/hosts/README.md](), [src/hosts/index.ts]()\n\n### Write Strategy Configuration\n\nHosts configure one of two write strategies for prompt assets:\n\n```mermaid\ngraph TD\n A[Prompt Asset] --> B{Write Strategy}\n B --> C[append-with-marker]\n B --> D[create-file-in-dir]\n C --> E[HTML comment markers
Idempotent append]\n D --> F[Standalone file creation
Skip if exists]\n```\n\n**Append with Marker Strategy**: Used by Cursor, Claude Code, and similar hosts. Content is wrapped in HTML comment markers:\n\n```html\n\n# Code Review Rules\n...\n\n```\n\n**Create File in Dir Strategy**: Used by Windsurf, Roo Code, and similar hosts. Creates `.md` in the rules directory, skipping if already exists. 资料来源：[src/assets/prompt.ts]()\n\n## Asset Type Configuration\n\n### MCP Asset Configuration\n\nMCP assets support two JSON formats:\n\n**Format A - Inner Config (Single Server)**:\n```json\n{\n \"command\": \"npx\",\n \"args\": [\"@playwright/mcp@latest\"],\n \"env\": {}\n}\n```\n\n**Format B - Full Config with mcpServers Wrapper**:\n```json\n{\n \"mcpServers\": {\n \"playwright\": {\n \"command\": \"npx\",\n \"args\": [\"@playwright/mcp@latest\"]\n }\n }\n}\n```\n\nThe system automatically detects `.toml` extension and dispatches to the TOML handler path for Codex and Vibe hosts. 资料来源：[src/assets/mcp.ts]()\n\n### Skill Asset Configuration\n\nSkills require a specific directory structure with a mandatory `SKILL.md` file:\n\n```markdown\n\n---\nname: my-skill\ndescription: A reusable agent skill.\n---\n\n# Skill: my-skill\n\nThis skill does something useful.\n```\n\nThe skill handler validates the presence of `SKILL.md` before installation and recursively copies the directory to the host's skills directory. 资料来源：[src/assets/skill.ts](), [README.md]()\n\n### Sub-agent Asset Configuration\n\nSub-agents support host specialization through the `agent-add//` syntax in YAML frontmatter:\n\n```markdown\n---\nname: playwright-tester\ndescription: A playwright testing agent.\nagent-get/cursor/model: fast\nagent-get/claude-code/model: haiku\n---\n\n# Playwright Test Agent\n```\n\nThe handler promotes matching `agent-add//*` values to top-level keys and removes all `agent-add/*` prefixed keys during installation. 资料来源：[src/assets/sub-agent.ts]()\n\n## Manifest Schema Configuration\n\nThe pack manifest uses JSON Schema validation via Zod:\n\n```typescript\nconst ManifestSchema = z.object({\n name: z.string().regex(/^[a-zA-Z0-9_-]+\\/[a-zA-Z0-9_-]+$/),\n assets: z.array(AssetDescriptorSchema).min(1),\n});\n```\n\n| Field | Type | Constraints |\n|-------|------|-------------|\n| `name` | string | Format `namespace/pack-name`, regex `[a-zA-Z0-9_-]/[a-zA-Z0-9_-]` |\n| `assets` | array | Minimum 1 item |\n| `assets[].type` | enum | `mcp`, `skill`, `prompt`, `command`, `subAgent` |\n| `assets[].source` | string | URI or local path |\n\n资料来源：[src/manifest/schema.ts]()\n\n## Source Resolution Configuration\n\n### Supported Source Types\n\n```mermaid\ngraph LR\n A[Source Input] --> B{Source Type Detection}\n B --> C[local]\n B --> D[git-ssh]\n B --> E[git-https]\n B --> F[http-file]\n B --> G[inline-json]\n B --> H[inline-md]\n```\n\n| Source Type | Detection Rule | Supported Asset Types |\n|-------------|----------------|------------------------|\n| `local` | File path exists on filesystem | All |\n| `git-ssh` | Starts with `git@` | All |\n| `git-https` | Starts with `https://` or `http://` | All |\n| `http-file` | Direct HTTP/HTTPS URL | MCP, Prompt, Command, Sub-agent |\n| `inline-json` | Starts with `{` | MCP only |\n| `inline-md` | Contains `\\n` | Prompt, Command, Sub-agent |\n\n**Note**: Skill assets do not support inline sources or direct HTTP URLs—exit code 2 is returned for these invalid sources. 资料来源：[src/source/inline.ts](), [src/installer.ts:52-57]()\n\n### Asset Name Inference Rules\n\n| Source Pattern | Name Extraction Rule | Example |\n|----------------|---------------------|---------|\n| Inline Markdown | First `# Heading` → kebab-case | `# Code Review` → `code-review` |\n| Git URL with `#path` | Last segment after `#`, strip extension | `...git#skills/pdf` → `pdf` |\n| Git URL without `#` | Repo name, strip `.git` suffix | `...playwright.git` → `playwright` |\n| Local path / HTTP | Filename, strip extension | `./mcps/playwright.json` → `playwright` |\n\n资料来源：[src/source/infer-name.ts]()\n\n## Environment Configuration\n\n### AGENT_ADD_HOME Environment Variable\n\nThe `AGENT_ADD_HOME` environment variable overrides `os.homedir()` return value in `src/assets/mcp.ts`. This redirects Claude Desktop and Codex host install paths to temporary directories for test isolation:\n\n```typescript\nconst getHomeDir = (): string => {\n return process.env.AGENT_ADD_HOME || os.homedir();\n};\n```\n\n资料来源：[src/assets/mcp.ts]()\n\n## Installation Flow Configuration\n\n### Core Data Flow\n\n```mermaid\ngraph TD\n A[CLI flags / --pack Manifest] --> B[Explicit flag capability check]\n B -->|exit 2 if unsupported| C[AssetDescriptor array]\n C --> D[ResolvedSource array]\n D --> E[InstallJob array]\n E --> F[InstallResult array]\n F --> G[Summary output]\n \n B -.->|--pack skips check| B\n```\n\nThe installation pipeline follows these stages:\n\n1. **Input Parsing**: CLI flags or pack manifest → `AssetDescriptor[]`\n2. **Capability Check**: Verify host supports requested asset types (exits 2 if unsupported)\n3. **Source Resolution**: `AssetDescriptor[]` → `ResolvedSource[]` with local paths and temp directories\n4. **Validation**: Each asset validated based on type-specific rules\n5. **Job Creation**: `ResolvedSource[]` → `InstallJob[]` (skip unsupported assets)\n6. **Handler Execution**: Process each job via type-specific handler\n7. **Result Aggregation**: Collect `InstallResult[]` with statuses: written, exists, updated, conflict, skipped, error\n\n资料来源：[src/installer.ts](), [src/cli.ts]()\n\n### Explicit Flag Capability Checking\n\nThe installer checks explicit flag capability declarations before building jobs. When a host declares `supported: false` for an asset type:\n\n1. Outputs error with reason and README link\n2. Exits with code 2\n\nThis check is **skipped** for `--pack` sources, allowing pack manifests to include assets that may not be supported by all hosts. 资料来源：[src/installer.ts](), [src/hosts/README.md]()\n\n## License\n\nThis project is licensed under the Mozilla Public License 2.0 (MPL-2.0).\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：pea3nut/agent-add\n\n摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：v1.1.0。\n\n## 1. 安装坑 · 来源证据：v1.1.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.1.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5c106a51ec5d4f999b8bcef8e68a89ec | https://github.com/pea3nut/agent-add/releases/tag/1.1.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 2. 安装坑 · 社区讨论暴露的待验证问题：I built a CLI that installs MCP, skills, prompts, commands and sub ...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：I built a CLI that installs MCP, skills, prompts, commands and sub ... 6 Apr 2026 · Project & Supported Tools. The source code is hosted on GitHub: https://github.com/pea3nut/agent-add ... r/mcp - I built a tool that auto- ...\n- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- 证据：social_signal:reddit | ssig_6d54ef81557a451081be71b052d0e31b | https://www.reddit.com/r/ClaudeAI/comments/1sdrk6k/i_built_a_cli_that_installs_mcp_skills_prompts/ | I built a CLI that installs MCP, skills, prompts, commands and sub ...\n\n## 3. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | host_targets=mcp_host, claude, claude_code, cursor, chatgpt\n\n## 4. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | README/documentation is current enough for a first validation pass.\n\n## 5. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | last_activity_observed missing\n\n## 6. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | no_demo; severity=medium\n\n## 8. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | issue_or_pr_quality=unknown\n\n## 9. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | release_recency=unknown\n\n\n", "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "Human Manual / 人类版说明书" }, "pitfall_log": { "asset_id": "pitfall_log", "filename": "PITFALL_LOG.md", "markdown": "# Pitfall Log / 踩坑日志\n\n项目：pea3nut/agent-add\n\n摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：v1.1.0。\n\n## 1. 安装坑 · 来源证据：v1.1.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.1.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5c106a51ec5d4f999b8bcef8e68a89ec | https://github.com/pea3nut/agent-add/releases/tag/1.1.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 2. 安装坑 · 社区讨论暴露的待验证问题：I built a CLI that installs MCP, skills, prompts, commands and sub ...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：I built a CLI that installs MCP, skills, prompts, commands and sub ... 6 Apr 2026 · Project & Supported Tools. The source code is hosted on GitHub: https://github.com/pea3nut/agent-add ... r/mcp - I built a tool that auto- ...\n- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- 证据：social_signal:reddit | ssig_6d54ef81557a451081be71b052d0e31b | https://www.reddit.com/r/ClaudeAI/comments/1sdrk6k/i_built_a_cli_that_installs_mcp_skills_prompts/ | I built a CLI that installs MCP, skills, prompts, commands and sub ...\n\n## 3. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | host_targets=mcp_host, claude, claude_code, cursor, chatgpt\n\n## 4. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | README/documentation is current enough for a first validation pass.\n\n## 5. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | last_activity_observed missing\n\n## 6. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | no_demo; severity=medium\n\n## 8. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | issue_or_pr_quality=unknown\n\n## 9. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | release_recency=unknown\n", "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。", "title": "Pitfall Log / 踩坑日志" }, "prompt_preview": { "asset_id": "prompt_preview", "filename": "PROMPT_PREVIEW.md", "markdown": "# agent-add - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for pea3nut/agent-add.\n\nProject:\n- Name: agent-add\n- Repository: https://github.com/pea3nut/agent-add\n- Summary:
\n- Host target: mcp_host, claude, claude_code, cursor\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet:
\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. introduction: Introduction. Produce one small intermediate artifact and wait for confirmation.\n2. getting-started: Getting Started. Produce one small intermediate artifact and wait for confirmation.\n3. system-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. host-integration: Host Integration. Produce one small intermediate artifact and wait for confirmation.\n5. source-resolution: Source Resolution. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/pea3nut/agent-add#readme\n- tests/fixtures/skill/my-skill/SKILL.md\n- README.md\n- package.json\n- bin/agent-add.js\n- src/cli.ts\n- src/index.ts\n- src/installer.ts\n- src/hosts/index.ts\n- src/source/index.ts\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n", "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。", "title": "Prompt Preview / 安装前试用 Prompt" }, "quick_start": { "asset_id": "quick_start", "filename": "QUICK_START.md", "markdown": "# Quick Start / 官方入口\n\n项目：pea3nut/agent-add\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx -y agent-add\n```\n\n来源：https://github.com/pea3nut/agent-add#readme\n\n## 来源\n\n- docs: https://github.com/pea3nut/agent-add#readme\n", "summary": "从项目官方 README 或安装文档提取的开工入口。", "title": "Quick Start / 官方入口" } }, "validation_id": "dval_3e340640c8434f42816f732f71099d5f" }