，Anthropic 正式推出了 Claude Code 插件系统(Plugins),这是一个轻量级的扩展机制,允许我们将自定义命令、子 Agent、MCP 服务器和 Hooks 打包成可共享的插件包。
今天,我想和大家分享我在实践中总结的插件开发经验。
为什么需要插件系统?
在插件系统出现之前,开发者经常面临一个尴尬的问题:你精心配置了自定义命令、Agent 和 MCP 服务器,但当团队成员问"如何在我的机器上设置相同的环境"时,你却不知道如何复现自己的配置。插件系统正是为了解决这个痛点而生。
插件的常见应用场景包括:
-
执行标准:工程领导可以使用插件确保代码审查或测试工作流中特定的 Hooks 运行
-
用户支持:开源维护者可以提供帮助开发者正确使用包的命令
-
工作流共享:开发者可以轻松分享生产力提升的工作流
-
工具连接:团队可以通过 MCP 服务器连接内部工具和数据源
-
自定义打包:框架作者可以为特定用例打包多个协同工作的自定义功能
插件系统核心概念
插件市场 vs 插件
一个完整的插件生态系统包含两个核心部分:插件市场和插件本身。
插件市场(Marketplace) 是插件的目录,类似于应用商店。你可以通过添加市场来发现和安装插件。市场可以是:
-
GitHub 仓库
-
本地开发目录
-
团队内部共享的目录
插件(Plugin) 则是实际提供功能的包,可以包含:
-
Commands(命令):自定义斜杠命令
-
Agents(子 Agent):专门用途的 AI 助手
-
Hooks(钩子):在工作流关键点触发的事件处理器
-
Skills(技能):模型自主调用的能力扩展
-
MCP Servers:Model Context Protocol 集成
插件市场目录结构
my-marketplace/ # 插件市场根目录
├── .claude-plugin/
│ └── marketplace.json # 市场配置文件
└── my-first-plugin/ # 插件目录
├── .claude-plugin/
│ └── plugin.json
├── commands/ # 自定义命令
├── agents/ # 自定义 Agent
├── skills/ # Agent Skills
├── hooks/ # 钩子
└── .mcp.json # MCP 服务器配置
marketplace.json 配置详解
{
"name": "my-marketplace",
"version": "1.0.0",
"description": "我的第一个插件市场",
"owner": {
"name": "作者名称",
"email": "author@example.com",
"url": "https://example.com"
},
"plugins": [
{
"name": "my-plugin",
"description": "插件描述",
"source": "./my-plugin",
"version": "1.0.0",
"author": {
"name": "插件作者",
"email": "plugin-author@example.com"
},
"category": "productivity"
}
]
}
插件目录结构
my-first-plugin/
├── .claude-plugin/
│ └── plugin.json # 插件配置
├── commands/ # 自定义命令
│ └── hello.md
├── agents/ # 自定义Agents
│ └── helper.md
├── skills/ # 自定义Skills
│ └── my-skill/
│ └── SKILL.md
├── .mcp.json # MCP服务配置
└── hooks/ # 自定义hooks
└── hooks.json
plugin.json 配置详解
{
"name": "my-plugin",
"description": "插件功能描述",
"version": "1.0.0",
"author": {
"name": "Your Name",
"email": "you@example.com"
}
}
实战:创建第一个插件
让我们从零开始创建一个完整的插件,包含命令、Agent、Hooks 和 MCP 服务器。
步骤 1:创建插件市场
首先在非项目工作区创建市场目录:
# 进入合适的目录
cd ~/Desktop/ai
# 创建市场目录
mkdir my-marketplace
cd my-marketplace
# 创建市场配置
mkdir .claude-plugin
cat > .claude-plugin/marketplace.json << 'EOF'
{
"name": "my-marketplace",
"version": "1.0.0",
"description": "个人插件市场",
"owner": {
"name": "Your Name"
},
"plugins": [
{
"name": "dev-toolkit",
"source": "./dev-toolkit",
"description": "开发工具包插件"
}
]
}
EOF
步骤 2:创建插件基础结构
# 创建插件目录
mkdir dev-toolkit
cd dev-toolkit
# 创建插件配置
mkdir .claude-plugin
cat > .claude-plugin/plugin.json << 'EOF'
{
"name": "dev-toolkit",
"description": "包含常用开发命令、Agent 和工具",
"version": "1.0.0",
"author": {
"name": "Your Name"
}
}
EOF
步骤 3:添加自定义命令
Commands 是存放在 commands/ 目录中的 Markdown 文件。
每个文件定义一个斜杠命令:
mkdir commands
# 创建问候命令
cat > commands/hello.md << 'EOF'
---
description: 用个性化信息问候用户
---
# Hello Command
热情地问候用户,询问他们今天需要什么帮助。让问候语更具个性化且鼓舞人心。
## 要求
- 问候语以 `^_^` 开始
- 询问用户当前的任务或目标
- 提供积极的鼓励
EOF
# 创建代码审查命令
cat > commands/review.md << 'EOF'
---
description: 执行全面的代码审查
---
# Code Review Command
对最近的代码更改执行详细的代码审查。
## 审查重点
1. 代码质量和可读性
2. 潜在的 bug 和边界情况
3. 性能优化机会
4. 安全问题
5. 最佳实践遵循情况
## 输出格式
- 使用 Markdown 格式
- 按优先级分类问题(Critical/High/Medium/Low)
- 为每个问题提供具体的改进建议
EOF
步骤 4:添加自定义 Agent
mkdir agents
cat > agents/architect.md << 'EOF'
---
description: 软件架构设计专家
---
# Software Architect Agent
你是一位经验丰富的软件架构师,擅长:
- 系统设计和架构模式
- 技术选型和评估
- 性能优化和扩展性设计
- 代码组织和模块化
## 工作方式
1. 深入理解需求和约束
2. 提出多个架构方案并比较利弊
3. 考虑长期可维护性和扩展性
4. 提供清晰的架构图和文档
## 专业领域
- 微服务架构
- 事件驱动架构
- 领域驱动设计(DDD)
- 云原生架构
EOF
步骤 5:添加 Hooks
Claude Code 支持 8 种 Hook 事件:UserPromptSubmit(用户提交提示时)、PreToolUse(工具执行前)、PostToolUse(工具执行后)、Notification(通知时)、Stop(响应结束时)、SubagentStop(子 Agent 完成时)、PreCompact(压缩前)和 SessionStart(会话开始时)。
mkdir hooks
cat > hooks/hooks.json << 'EOF'
{
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "prettier --write \"$CLAUDE_FILE_PATHS\"",
"suppressOutput": true
}
]
}
],
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "echo '\n✅ 任务完成!'"
}
]
}
]
}
EOF
步骤 6:添加 Agent Skills
Skills 是模型自主调用的能力,通过 SKILL.md 文件定义。Claude 在启动时会扫描所有 Skills 的元数据,当用户的任务匹配 Skill 的描述时,Claude 会自动加载相关指令:
mkdir -p skills/python-testing
cat > skills/python-testing/SKILL.md << 'EOF'
---
name: python-testing
description: Python 项目测试最佳实践,包括 pytest、coverage 和 mock
---
# Python Testing Skill
## 使用场景
当用户需要编写或改进 Python 测试时使用此 Skill。
## 测试框架
- 使用 pytest 作为主要测试框架
- 使用 pytest-cov 进行覆盖率测试
- 使用 pytest-mock 进行 mock
## 最佳实践
1. 测试文件命名:test_*.py 或 *_test.py
2. 测试函数命名:test_* 开头
3. 使用 fixtures 管理测试数据
4. 使用参数化测试减少重复代码
## 示例结构
```python
import pytest
@pytest.fixture
def sample_data():
return {"key": "value"}
def test_example(sample_data):
assert sample_data["key"] == "value"
@pytest.mark.parametrize("input,expected", [
(1, 2),
(2, 4),
])
def test_multiply(input, expected):
assert input * 2 == expected
```
## 运行测试
```bash
# 运行所有测试
pytest
# 运行带覆盖率报告
pytest --cov=src --cov-report=html
# 运行特定测试
pytest tests/test_module.py::test_function
```
EOF
步骤 7:添加 MCP 服务器
MCP 服务器配置可以放在插件根目录的 .mcp.json 文件中:
cat > .mcp.json << 'EOF'
{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp"],
"env": {}
},
"brave-search": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-brave-search"],
"env": {
"BRAVE_API_KEY": "${BRAVE_API_KEY}"
}
}
}
}
EOF
插件的 MCP 服务器在插件启用时自动启动,但需要重启 Claude Code 才能应用 MCP 服务器的更改。
步骤 8:安装和测试插件
# 回到 Claude Code
# 添加插件市场
/plugin marketplace add ~/Desktop/ai/my-marketplace
# 安装插件
/plugin install dev-toolkit@my-marketplace
# 重启 Claude Code 以加载插件
测试各个组件:
bash
# 测试命令
/hello
/review
# 测试 Agent
请 @architect 设计一个博客系统的架构
# 测试 Skill(自动触发)
帮我为这个 Python 函数编写单元测试
# 查看 MCP 服务器状态
/mcp
高级特性:自定义插件路径
除了默认目录配置,还可以使用自定义路径指定各个组件的位置。这种方式需要在 marketplace.json 中将 source 设置为 `"./"``:
{
"name": "advanced-marketplace",
"plugins": [
{
"name": "custom-plugin",
"source": "./",
"commands": [
"./custom/commands/special.md",
"./another/path/command.md"
],
"agents": "./custom/agents/",
"hooks": "./config/hooks.json",
"mcpServers": "./mcp-config.json"
}
]
}
⚠️ 重要提示:自定义路径方式和默认目录方式不可同时使用,否则会出现路径异常问题。
最佳实践和技巧
1. 插件设计原则
-
单一职责:每个插件专注于一个特定领域
-
最小化依赖:减少外部依赖,提高可移植性
-
清晰文档:为每个命令和 Agent 提供详细说明
2. Skills 编写建议
编写 Skills 时应保持简洁,YAML 元数据应特别简短,因为所有 Skills 的元数据都会预加载到上下文窗口中。SKILL.md 文件应保持在 500 行以下,详细内容可以分割到其他文件。
3. Hooks 使用技巧
Hooks 可以通过退出码控制执行流程:退出码 0 表示成功继续,退出码 2 表示阻止操作。Hooks 还可以返回结构化 JSON 进行复杂控制:
python
import json
import sys
output = {
"decision": "approve", # 或 "deny"
"reason": "通过安全检查",
"suppressOutput": True # 不在对话记录中显示
}
print(json.dumps(output))
sys.exit(0)
4. MCP 服务器配置建议
直接编辑配置文件比使用 CLI 向导更灵活,特别是对于需要大量参数(如路径和环境变量)的复杂配置。
5. 团队协作
在项目仓库的 .claude/settings.json 中配置插件市场和插件,当团队成员信任该仓库文件夹时,Claude Code 会自动安装指定的插件:
{
"marketplaces": ["your-org/team-plugins"],
"plugins": {
"formatter@team": "enabled",
"deployer@team": "enabled"
}
}
6. 本地开发流程
使用本地开发市场测试插件:
# 1. 创建开发市场
mkdir dev-marketplace
cd dev-marketplace
mkdir .claude-plugin
# 2. 添加开发中的插件
# 3. 在 Claude Code 中安装
/plugin marketplace add ./dev-marketplace
/plugin install my-plugin@dev-marketplace
# 4. 修改后重新安装测试
/plugin uninstall my-plugin
/plugin install my-plugin@dev-marketplace
社区资源和插件市场
目前有多个活跃的社区插件市场,如 claude-code-plugins-plus,拥有超过 227 个生产就绪的插件,涵盖 15 个类别。你可以:
-
浏览现有插件获取灵感
-
学习优秀插件的实现方式
-
为社区贡献自己的插件
热门社区市场:
-
jeremylongshore/claude-code-plugins-plus- 综合性插件市场 -
anthropics/skills- 官方 Skills 示例 -
ananddtyagi/claude-code-marketplace- 社区驱动的命令和插件
故障排查
插件未加载
-
检查 plugin.json 格式是否正确
-
确认插件目录结构符合规范
-
重启 Claude Code
命令未显示
-
验证命令文件在 commands/ 目录中
-
检查 Markdown 文件格式
-
使用
/help确认命令是否注册
MCP 服务器无法连接
-
检查 .mcp.json 配置
-
验证环境变量是否设置
-
使用
/mcp查看服务器状态
Skills 未触发
检查 Skill 的 description 是否清晰描述了使用场景,确保用户的请求与描述匹配。
总结
Claude Code 插件系统将 Claude Code 从强大的独立助手转变为协作平台生态系统。它让我们能够将工作流、最佳实践和工具打包成可共享的包,无论是个人使用还是团队协作,都能显著提升开发效率。
插件生态系统还很年轻,但已经展现出巨大的潜力。通过创建和分享插件,我们不仅能提升自己的生产力,还能为整个社区做出贡献。
Claude Code 官方文档:https://docs.claude.com/en/docs/claude-code
Agent Skills 工程博客:https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
社区插件市场:https://claudecodemarketplace.com/
Anthropic Skills 仓库: