agent-deploy 🚀

完整的 Agent 生态工具：导入 → Market → 部署，在不同 AI 编码工具间自由迁移

✨ What's New in v3.1

Skill / MCP Market References - Agent 支持引用市场已发布的 Skill 和 MCP Server 包：

✅ Skill Ref - skills 支持 ref + version 市场引用
✅ MCP Ref - mcp_servers 支持 ref + version + env_override 市场引用
✅ Auto Resolution - market run 自动解析并合并依赖
✅ Local Cache - 依赖包本地缓存加速后续运行
✅ Version Constraints - 支持 ^、~、>= 等语义化版本约束

Export (Phase 1) ✅

✅ Multi-Format Support - agent.json 支持多种格式（instructions、subagents、SKILL.md）
✅ Cross-Platform Deploy - 部署到 8+ AI 工具
✅ 100% Backward Compatible

Import (Phase 2) ✅

✅ Import from 4 Platforms - 从 Cursor、Claude Code、CodeBuddy、GitHub 导入
✅ Auto-Detection - 自动识别平台格式
✅ CLI & MCP Support - 命令行和 MCP 工具双模式
✅ Dry-run Mode - 预览导入结果

Market Integration (Phase 3) ✅

✅ Upload to Market - 一键上传分享 Agent
✅ Download from Market - 从 Market 下载他人分享的 Agent
✅ Auto Deploy - 自动检测并部署到 AI 工具
✅ Complete Workflow - Import → Upload → Download → Deploy

Skill / MCP Packaging (Phase 3.1) ✅

✅ Skill Pack - 打包 Skill 为独立可发布包
✅ MCP Pack - 打包 MCP Server 为独立可发布包
✅ Cache Management - 本地缓存状态查看与清理
✅ Migration Tool - Agent v2.0 → v3.1 引用格式迁移

See AGENT_FORMATS.md for format details.

Installation

Node.js (Recommended)

# Global install (for CLI)
npm install -g @openpeng/agent-deploy

# Or use directly
npx @openpeng/agent-deploy import .cursor/commands/my-agent.md

Python

pip install agent-deploy

Quick Start

Complete Workflow Example

# 1️⃣ Import from Cursor
agent-deploy import .cursor/commands/my-agent.md

# 2️⃣ Upload to Market
agent-deploy upload ./imported-agents/my-agent

# 3️⃣ Deploy to Claude Code
agent-deploy deploy ./imported-agents/my-agent -t claude_code

# Done! Now use /my-agent in Claude Code

🔽 Import Agents

CLI Mode:

# Import from Cursor
agent-deploy import .cursor/commands/my-agent.md

# Preview before import (dry-run)
agent-deploy import .claude/commands/skill.md --dry-run

# Custom output directory
agent-deploy import agent.md -o ./my-agents

# Force specific adapter
agent-deploy import agent.md -t cursor

MCP Mode:

You: Import the agent from .cursor/commands/code-reviewer.md

MCP calls import_agent and converts to agent.json v2.0 format.

Supported Import Platforms:

✅ Cursor (.cursor/commands/*.md)
✅ Claude Code (.claude/commands/*.md)
✅ CodeBuddy (.codebuddy/skills/*/SKILL.md)
✅ GitHub Copilot (.github/agents/*.md)

📤 Upload to Market

# Upload agent to market
agent-deploy upload ./imported-agents/my-agent

# With custom Market URL
agent-deploy upload ./my-agent -m http://market.example.com

# Force overwrite existing version
agent-deploy upload ./my-agent --force

# Use environment variables
export MARKET_API_URL=http://localhost:8321
export MARKET_API_KEY=your-api-key
agent-deploy upload ./my-agent

Output:

📤 Uploading agent to Market...
✅ Successfully uploaded agent!

Agent ID:     my-agent
Market URL:   http://localhost:8321/agents/my-agent

📥 Download from Market

MCP Mode:

// Call via MCP tool
download_agent({
  agent_id: "my-agent",
  output_dir: "./downloaded-agents"
})

🧩 Skill / MCP Commands (v3.1)

Pack Skill

# Pack a Skill directory into a publishable package
agent-deploy skill pack ./my-skill

# Output: ./my-skill.skill.tar.gz

Skill package structure:

my-skill/
├── skill.json          # Skill metadata (required)
├── SKILL.md            # Skill instructions (required)
├── scripts/            # Executable scripts (optional)
└── templates/          # Template files (optional)

Upload Skill

# Upload Skill to Market
agent-deploy skill upload ./my-skill

# With custom Market URL
agent-deploy skill upload ./my-skill -m http://market.example.com

# Force overwrite
agent-deploy skill upload ./my-skill --force

Pack MCP Server

# Pack an MCP Server directory into a publishable package
agent-deploy mcp pack ./my-mcp

# Output: ./my-mcp.mcp.tar.gz

MCP package structure:

my-mcp/
├── mcp-server.json     # MCP Server metadata (required)
├── mcp-config.json     # MCP configuration (required)
└── README.md           # Setup instructions (required)

Upload MCP Server

# Upload MCP Server to Market
agent-deploy mcp upload ./my-mcp

# With custom Market URL
agent-deploy mcp upload ./my-mcp -m http://market.example.com

# Force overwrite
agent-deploy mcp upload ./my-mcp --force

Cache Management

# View local cache status
agent-deploy cache status

# Clean all cached market packages
agent-deploy cache clean

# Clean cache for a specific market
agent-deploy cache clean --market http://market.example.com

Cache location: ~/.cache/agent-deploy/market/

Migration Tool (v2.0 → v3.1)

# Migrate an existing agent.json to use Skill/MCP references
agent-deploy migrate ./my-agent/agent.json

# Preview migration without writing files
agent-deploy migrate ./my-agent/agent.json --dry-run

# Specify output path
agent-deploy migrate ./my-agent/agent.json -o ./my-agent-v3/agent.json

The migration tool will:

Scan skills and mcp_servers for inline definitions
Suggest ref + version replacements for known market packages
Generate a v3.1-compatible agent.json

🚀 Deploy to AI Tools

# Auto-detect and deploy
agent-deploy deploy ./my-agent

# Deploy to specific tool
agent-deploy deploy ./my-agent -t cursor

# Deploy to multiple tools
agent-deploy deploy ./my-agent -t cursor -t claude_code

# Deploy to all detected tools
agent-deploy deploy ./my-agent --tool all

# Choose installation level
agent-deploy deploy ./my-agent -l user      # User-level
agent-deploy deploy ./my-agent -l project   # Project-level
agent-deploy deploy ./my-agent -l both      # Both

Output:

🔍 Auto-detected: cursor

📦 Deploying to cursor...
✅ Successfully deployed to cursor

📊 Deployment Summary:
   ✅ Successful: 1
   ❌ Failed: 0

🎉 Agent deployed successfully!

Next steps:
   - Open Cursor and type '//my-agent' to use the agent

MCP Configuration

Node.js MCP Server

在你的 MCP 客户端配置中添加：

{
  "mcpServers": {
    "agent-deploy": {
      "command": "node",
      "args": ["/path/to/agent-deploy/node/dist/index.js"],
      "env": {
        "MARKET_API_URL": "http://localhost:8321"
      }
    }
  }
}

Python MCP Server

{
  "mcpServers": {
    "agent-deploy": {
      "command": "python",
      "args": ["-m", "agent_deploy.server"],
      "cwd": "/path/to/agent-deploy",
      "env": {
        "PYTHONPATH": "/path/to/agent-deploy/src",
        "MARKET_API_URL": "http://localhost:8321"
      }
    }
  }
}

更多配置示例见 mcp_config.example.json。

Supported Platforms

Deploy Targets (8 platforms)

工具	格式	部署路径
Cursor	Markdown	`.cursor/commands/`
Claude Code	Markdown	`.claude/commands/`
CodeBuddy	YAML+MD	`.codebuddy/skills/`
GitHub Copilot	Markdown	`.github/agents/`
OpenCode	Markdown	`.opencode/commands/`
Windsurf	Markdown	`.windsurf/rules/`
Trae	Markdown	`.trae/rules/`
Aider	Markdown	`CONVENTIONS.md`

Import Sources (4 platforms)

工具	源格式	导入路径
Cursor	Markdown	`.cursor/commands/*.md`
Claude Code	Markdown	`.claude/commands/*.md`
CodeBuddy	YAML+MD	`.codebuddy/skills/*/SKILL.md`
GitHub Copilot	Markdown	`.github/agents/*.md`

MCP Tools

工具	说明
`import_agent`	✨ 从 AI 工具导入 Agent 到 agent.json
`upload_agent`	✨ 上传 Agent 到 Market
`download_agent`	✨ 从 Market 下载 Agent
`deploy_agent`	一键部署：检测 → 适配 → 安装
`list_installed_tools`	检测环境中已安装的 AI 工具
`adapt_agent`	将 Agent 转换为目标工具格式
`install_agent`	将适配后的 Agent 安装到目标目录

CLI Commands

# Import agents from AI tools
agent-deploy import <source> [options]
  -o, --output <dir>    Output directory (default: ./imported-agents)
  -t, --tool <name>     Force specific adapter (cursor, claude_code, etc.)
  -d, --dry-run         Preview import without writing files
  -h, --help            Show help message

# Upload agents to Market
agent-deploy upload <agent-dir> [options]
  -m, --market <url>    Market API URL (default: $MARKET_API_URL)
  -k, --api-key <key>   API Key (default: $MARKET_API_KEY)
  -f, --force           Force overwrite existing version
  -h, --help            Show help message

# Deploy agents to AI tools
agent-deploy deploy <agent-dir> [options]
  -t, --tool <name>     Target tool (can be used multiple times)
                        Special: 'auto' (default) or 'all'
  -l, --level <level>   Installation level: user, project, both
  -h, --help            Show help message

# Show help
agent-deploy --help

# Show version
agent-deploy --version

Command Examples

# Import
agent-deploy import .cursor/commands/my-agent.md
agent-deploy import .claude/commands/skill.md --dry-run
agent-deploy import agent.md -o ~/agents

# Upload
agent-deploy upload ./imported-agents/my-agent
agent-deploy upload ./my-agent -m http://market.example.com
agent-deploy upload ./my-agent --force

# Deploy
agent-deploy deploy ./my-agent
agent-deploy deploy ./my-agent -t cursor
agent-deploy deploy ./my-agent --tool all
agent-deploy deploy ./my-agent -l project

# Batch operations
for f in .cursor/commands/*.md; do
  agent-deploy import "$f"
done

for dir in ./imported-agents/*; do
  agent-deploy upload "$dir"
done

Development

Node.js

cd node/
npm install
npm test        # Run tests (62 tests)
npm run build   # Build TypeScript
npm run dev     # Development mode

Python

cd python/
pip install -e ".[dev]"
pytest tests/ -v

Test Coverage

62/62 tests passing ✅

Test Suite	Tests	Status
Export (adapt.test.ts)	22	✅
Server (server.test.ts)	9	✅
Import Unit (import.test.ts)	20	✅
Import MCP (import-mcp.test.ts)	11	✅

Coverage includes:

Multi-format agent loading
Platform adapters (8 export + 4 import)
Fallback strategy
Error handling
Cross-platform paths (Windows/Unix)

Documentation

User Guides

USER_GUIDE.md — 完整用户指南：场景、命令参考、FAQ、最佳实践
QUICK_START.md — 快速开始：5 分钟上手指南
SKILL.md — Agent Deploy 使用手册
AGENT_FORMATS.md — Agent 格式指南
CLI_IMPORT_GUIDE.md — CLI 导入命令详细指南

Technical Docs

PROJECT_OVERVIEW.md — 项目概览：架构、协议、API 参考、快速入门
AGENT_JSON_SPEC_V2.md — agent.json v2.0 规范
IMPORT_ADAPTER_SPEC.md — ImportAdapter 接口规范
IMPORT_AGENT_TOOL_GUIDE.md — MCP import_agent 工具指南
DEVELOPMENT.md — 开发者文档：架构、扩展指南
MAINTENANCE.md — 维护手册：发布流程、排错
CONTRIBUTING.md — 贡献指南：如何参与项目

Project Structure

agent-deploy/
├── python/                    # Python MCP Server
│   ├── src/agent_deploy/
│   │   └── server.py
│   └── tests/
├── node/                      # Node.js Implementation
│   ├── src/
│   │   ├── index.ts          # MCP Server
│   │   ├── cli.ts            # CLI Entry Point
│   │   ├── adapt.ts          # Export: agent.json → AI tools
│   │   ├── import.ts         # Import: AI tools → agent.json
│   │   ├── import-manager.ts # Import orchestration
│   │   ├── market.ts         # Market API integration
│   │   ├── detect.ts         # AI tool detection
│   │   ├── install.ts        # Agent installation
│   │   └── adapters/
│   │       ├── cursor-import.ts
│   │       ├── claude-import.ts
│   │       ├── codebuddy-import.ts
│   │       └── github-import.ts
│   └── tests/
│       ├── adapt.test.ts
│       ├── server.test.ts
│       ├── import.test.ts
│       └── import-mcp.test.ts
├── docs/
│   ├── specs/                # Specifications
│   │   └── AGENT_JSON_SPEC_V2.md
│   └── guides/               # User guides
│       ├── USER_GUIDE.md
│       ├── QUICK_START.md
│       ├── CLI_IMPORT_GUIDE.md
│       ├── IMPORT_ADAPTER_SPEC.md
│       └── IMPORT_AGENT_TOOL_GUIDE.md
├── AGENT_FORMATS.md
├── SKILL.md
├── DEVELOPMENT.md
├── MAINTENANCE.md
├── CONTRIBUTING.md
└── README.md

Workflows

Complete Lifecycle

# 1. Import from Cursor
agent-deploy import .cursor/commands/code-reviewer.md

# 2. Upload to Market
agent-deploy upload ./imported-agents/code-reviewer

# 3. Share with others
# Market URL: http://market.example.com/agents/code-reviewer

# 4. Others download from Market (via MCP)
download_agent({ agent_id: "code-reviewer" })

# 5. Deploy to their tool
agent-deploy deploy ./downloaded-agents/code-reviewer -t claude_code

Cross-Platform Migration

# Migrate from Cursor to Claude Code
agent-deploy import .cursor/commands/my-agent.md
agent-deploy deploy ./imported-agents/my-agent -t claude_code

Batch Operations

#!/bin/bash
# Import all agents from Cursor
for f in .cursor/commands/*.md; do
  agent-deploy import "$f" -o ./all-agents
done

# Upload all to Market
for dir in ./all-agents/*; do
  agent-deploy upload "$dir"
done

# Deploy all to Claude Code
for dir in ./all-agents/*; do
  agent-deploy deploy "$dir" -t claude_code
done

echo "✅ All agents migrated!"

Roadmap

Phase 1: Export ✅ Complete

Multi-format agent loading
Deploy to 8+ platforms
100% backward compatibility
Comprehensive tests

Phase 2: Import ✅ Complete

Phase 3: Market Integration ✅ Complete

Upload to Market
Download from Market
Auto-deploy to AI tools
Complete workflow (Import → Market → Deploy)

Phase 4: Skill / MCP Ecosystem (v3.1) ✅

Skill market references (ref + version)
MCP Server market references (ref + version + env_override)
Dependency auto-resolution in market run
Local cache for Skill / MCP packages
Semantic version constraints (^, ~, >=)
Skill / MCP pack & upload commands
Cache status & clean commands
Migration tool (v2.0 → v3.1)

Phase 5: Advanced Features (Future)

Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

Development environment setup
Coding standards
Testing guidelines
How to add new platform adapters
Pull request process

Quick start:

# Fork and clone
git clone https://github.com/yourusername/agent-deploy.git
cd agent-deploy/node

# Install and test
npm install
npm test

# Create a branch
git checkout -b feature/my-feature

# Make changes and test
npm test

# Submit PR
git push origin feature/my-feature

License

MIT

Credits

Author: Peng Xiao
Repository: github:openpeng/agent-deploy

Built with:

Model Context Protocol (MCP)
TypeScript / Node.js
Python

Support

Version: 3.0.0
Last Updated: 2026-06-07
Status: ✅ Production Ready (Phase 1+2+3 Complete)

Name		Name	Last commit message	Last commit date
agent-bridge		agent-bridge
agent-hub-project-docs		agent-hub-project-docs
docs		docs
legacy		legacy
node		node
.gitignore		.gitignore
AGENT_FORMATS.md		AGENT_FORMATS.md
CONTRIBUTING.md		CONTRIBUTING.md
DEVELOPMENT.md		DEVELOPMENT.md
LICENSE		LICENSE
MAINTENANCE.md		MAINTENANCE.md
README.md		README.md
SKILL.md		SKILL.md
agent.json		agent.json
mcp_config.example.json		mcp_config.example.json

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

agent-deploy 🚀

✨ What's New in v3.1

Export (Phase 1) ✅

Import (Phase 2) ✅

Market Integration (Phase 3) ✅

Skill / MCP Packaging (Phase 3.1) ✅

Installation

Node.js (Recommended)

Python

Quick Start

Complete Workflow Example

🔽 Import Agents

📤 Upload to Market

📥 Download from Market

🧩 Skill / MCP Commands (v3.1)

Pack Skill

Upload Skill

Pack MCP Server

Upload MCP Server

Cache Management

Migration Tool (v2.0 → v3.1)

🚀 Deploy to AI Tools

MCP Configuration

Node.js MCP Server

Python MCP Server

Supported Platforms

Deploy Targets (8 platforms)

Import Sources (4 platforms)

MCP Tools

CLI Commands

Command Examples

Development

Node.js

Python

Test Coverage

Documentation

User Guides

Technical Docs

Project Structure

Workflows

Complete Lifecycle

Cross-Platform Migration

Batch Operations

Roadmap

Phase 1: Export ✅ Complete

Phase 2: Import ✅ Complete

Phase 3: Market Integration ✅ Complete

Phase 4: Skill / MCP Ecosystem (v3.1) ✅

Phase 5: Advanced Features (Future)

Contributing

License

Credits

Support

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages