Claude Code Plugins 是将 Skills、Agents、Hooks、MCP 服务器打包为可共享单元的标准方式。本文是从零开发和发布 Plugin 的完整指南。
独立配置 vs Plugin：如何选择
| 方式 | Skill 命名 | 适合场景 |
|---|---|---|
独立配置（.claude/ 目录） | /hello（短名称） | 个人工作流、项目特定定制、快速实验 |
Plugin（带 .claude-plugin/plugin.json） | /plugin-name:hello（命名空间） | 与团队共享、跨项目复用、版本化发布、Marketplace 分发 |
先用独立配置快速迭代，再转为 Plugin 分享。
5 分钟创建第一个 Plugin
前置要求
- Claude Code v1.0.33 或更高（
claude --version确认）
第一步：创建目录结构
bash
mkdir my-first-plugin
mkdir my-first-plugin/.claude-plugin
mkdir -p my-first-plugin/skills/hello第二步：创建 Plugin Manifest
my-first-plugin/.claude-plugin/plugin.json：
json
{
"name": "my-first-plugin",
"description": "A greeting plugin to learn the basics",
"version": "1.0.0",
"author": {
"name": "Your Name"
}
}| 字段 | 作用 |
|---|---|
name | 唯一标识符，也是 Skill 的命名空间前缀（如 /my-first-plugin:hello） |
description | Plugin Manager 中显示的说明文字 |
version | 使用语义版本（SemVer）追踪发布 |
author | 可选，用于署名 |
可选字段：homepage（主页）、repository（仓库）、license（授权协议）。
第三步：添加 Skill
my-first-plugin/skills/hello/SKILL.md：
markdown
---
description: Greet the user with a friendly message
disable-model-invocation: true
---
Greet the user warmly and ask how you can help them today.skills/hello/ 目录名 hello + 插件名 my-first-plugin → Skill 命令为 /my-first-plugin:hello。
第四步：本地测试
bash
claude --plugin-dir ./my-first-plugin在 Claude Code 中运行：
/my-first-plugin:hello
Plugin 目录结构
my-plugin/
├── .claude-plugin/
│ └── plugin.json # 必须：Plugin Manifest
├── skills/ # Skills（每个子目录 = 一个 Skill）
│ ├── review/
│ │ └── SKILL.md
│ └── deploy/
│ ├── SKILL.md
│ └── scripts/
│ └── deploy.sh
├── agents/ # Subagents（每个子目录 = 一个 Subagent）
│ └── code-reviewer/
│ └── AGENT.md
├── hooks/ # Hooks（settings.json 格式）
│ └── settings.json
├── settings/ # 默认设置
│ └── settings.json
└── lsp/ # LSP 服务器（代码智能）
└── my-lsp-server
开发进阶功能
添加更多 Skills
markdown
<!-- skills/review/SKILL.md -->
---
description: Review code for quality, security, and best practices
disable-model-invocation: false
---
# Code Review Checklist
## Quality
- [ ] Code is readable and well-commented
- [ ] Functions have single responsibility
- [ ] No magic numbers or hardcoded strings
## Security
- [ ] Input validation present
- [ ] No SQL injection vulnerabilities
- [ ] Secrets not hardcoded
## Tests
- [ ] New code has unit tests
- [ ] Edge cases covered使用：/my-plugin:review
添加 LSP 服务器
LSP 服务器为 Claude 提供代码智能（类型错误、跳转到定义、查找引用）：
json
// .claude-plugin/plugin.json
{
"name": "my-plugin",
"lspServers": [
{
"name": "my-lsp",
"command": ["./lsp/my-lsp-server", "--stdio"],
"languages": ["python", "typescript"]
}
]
}随 Plugin 发布默认设置
settings/settings.json（在安装此 Plugin 的项目中自动应用）：
json
{
"hooks": {
"PostToolUse": [{
"matcher": "Edit|Write",
"hooks": [{
"type": "command",
"command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
}]
}]
}
}复杂 Plugin 的目录组织
对于大型 Plugin，可以在 skills/ 下创建子目录分组：
my-plugin/
└── skills/
├── code/
│ ├── review/SKILL.md
│ └── refactor/SKILL.md
└── devops/
├── deploy/SKILL.md
└── rollback/SKILL.md
本地测试
bash
# 加载单个 Plugin 目录
claude --plugin-dir ./my-plugin
# 加载多个 Plugin 目录
claude --plugin-dir ./plugin-a --plugin-dir ./plugin-b
# 在会话中验证安装
/plugin list调试 Plugin 问题：
bash
# 查看详细加载信息
claude --plugin-dir ./my-plugin --debug plugin
# 检查 Skill 是否已注册
/skills # 列出所有已加载的 Skills，包括 Plugin 提供的从独立配置迁移到 Plugin
已有 .claude/skills/、.claude/agents/ 中的配置，迁移步骤：
bash
# 1. 创建 Plugin 目录结构
mkdir my-plugin/.claude-plugin
# 2. 创建 Manifest
cat > my-plugin/.claude-plugin/plugin.json << 'EOF'
{
"name": "my-plugin",
"description": "My custom workflow tools",
"version": "1.0.0"
}
EOF
# 3. 复制已有配置
cp -r .claude/skills my-plugin/
cp -r .claude/agents my-plugin/
# 4. 测试
claude --plugin-dir ./my-plugin迁移后的变化：
- Skill 命令从
/review变为/my-plugin:review（加了命名空间前缀） - Skill 不再自动加载（需显式调用或通过描述触发）
- 可以通过 Plugin Manager 安装/卸载，而不是手动复制文件
发布和共享
共享 Plugin 的方式
bash
# 方式一：Git 仓库
git init my-plugin
git add .
git commit -m "Initial release"
git push origin main
# 用户通过 /plugin install <git-url> 安装
# 方式二：npm 包（便于版本管理）
npm init -y
# 发布到 npm
npm publish提交到官方 Marketplace
官方 Plugin Marketplace 的要求：
- 公开 Git 仓库（GitHub/GitLab）
- 完整的
plugin.json（含 description、version、homepage） - README.md（说明用途、安装方式、使用示例）
- 遵循 Anthropic 使用政策
提交地址：参考 Plugins Marketplace 文档
用户安装 Plugin 的方式
/plugin install <plugin-name> # 从 Marketplace 安装
/plugin install <git-url> # 从 Git 仓库安装
/plugin install <local-path> # 从本地路径安装
/plugin list # 查看已安装插件
/plugin enable <plugin-name> # 启用插件
/plugin disable <plugin-name> # 禁用插件
/plugin remove <plugin-name> # 卸载插件
原文：Create plugins | 来源：Anthropic 官方文档