Plugin（插件）让你能够将自定义技能（Skills）、子 Agent、Hooks 和 MCP 服务器打包成可分享的扩展，供团队或社区使用。本文介绍如何从零开始创建 Claude Code 插件。
独立配置 vs 插件：如何选择？
| 方式 | 技能命名格式 | 适用场景 |
|---|---|---|
独立配置（.claude/ 目录） | /hello | 个人工作流、单项目定制、快速实验 |
插件（.claude-plugin/plugin.json） | /plugin-name:hello | 团队共享、社区分发、版本管理、跨项目复用 |
使用独立配置：
- 为单个项目定制 Claude Code
- 个人使用，无需共享
- 在打包前快速实验新技能
- 想要简短的技能名称
使用插件：
- 与团队或社区共享功能
- 在多个项目中使用相同的技能/Agent
- 需要版本控制和便捷更新
- 通过市场分发
建议先用独立配置快速迭代，满意后再转换为插件分发。
快速上手：创建第一个插件
前置条件
- Claude Code 已安装并认证
- Claude Code 版本 1.0.33 或更高（运行
claude --version检查）
Step 1：创建插件目录
bash
mkdir my-first-pluginStep 2：创建插件清单
插件清单（.claude-plugin/plugin.json）定义插件的身份：
bash
mkdir my-first-plugin/.claude-plugin创建 my-first-plugin/.claude-plugin/plugin.json：
json
{
"name": "my-first-plugin",
"description": "一个学习基础知识的问候插件",
"version": "1.0.0",
"author": {
"name": "你的名字"
}
}| 字段 | 用途 |
|---|---|
name | 唯一标识符和技能命名空间（技能会带此前缀，如 /my-first-plugin:hello） |
description | 在插件管理器中显示 |
version | 使用语义化版本控制 |
author | 可选，用于署名 |
Step 3：添加技能
技能存放在 skills/ 目录中，每个技能是包含 SKILL.md 的文件夹：
bash
mkdir -p my-first-plugin/skills/hello创建 my-first-plugin/skills/hello/SKILL.md：
markdown
---
name: hello
description: 用友好的消息问候用户
---
用热情的方式问候用户，并询问今天如何帮助他们。Step 4：本地测试
bash
# 使用 --plugin-dir 标志加载插件
claude --plugin-dir ./my-first-plugin在 Claude Code 中测试：
text
/my-first-plugin:hello插件目录结构
完整的插件结构示例：
text
my-plugin/
├── .claude-plugin/
│ └── plugin.json # 插件清单（必需）
├── skills/
│ ├── code-review/
│ │ ├── SKILL.md # 代码审查技能
│ │ └── checklist.md # 辅助文件
│ └── doc-gen/
│ └── SKILL.md # 文档生成技能
├── agents/
│ └── security-agent.md # 安全审查 Agent
├── hooks/
│ └── settings.json # Hook 配置
└── README.md创建完整功能的代码审查插件
插件清单
json
{
"name": "code-quality",
"description": "代码质量工具套件：审查、安全检查和文档生成",
"version": "1.0.0",
"author": {
"name": "Your Company",
"email": "dev@yourcompany.com"
},
"homepage": "https://github.com/yourcompany/claude-code-quality",
"license": "MIT"
}代码审查技能
markdown
---
name: review
description: 对代码进行全面的质量审查，包括可读性、性能和安全性
---
审查提供的代码，检查以下方面：
1. **代码可读性**
- 变量和函数命名是否清晰？
- 是否需要添加注释？
- 是否遵循项目编码规范？
2. **性能问题**
- 是否有 N+1 查询问题？
- 是否有不必要的计算或内存分配？
3. **安全风险**
- 输入验证是否充分？
- 是否有 SQL 注入、XSS 等常见漏洞？
4. **测试覆盖**
- 关键逻辑是否有测试？
- 边界条件是否覆盖？
对每个问题提供：当前代码、问题说明和改进建议。自动提交检查 Hook
json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash(git commit *)",
"hooks": [
{
"type": "command",
"command": "hooks/pre-commit-check.sh"
}
]
}
]
}
}安装插件
从本地路径安装
bash
# 使用 --plugin-dir 临时加载
claude --plugin-dir /path/to/my-plugin
# 或使用插件安装命令永久安装
/plugin install /path/to/my-plugin从 Git 仓库安装
bash
/plugin install https://github.com/yourcompany/claude-code-quality从插件市场安装
bash
# 搜索插件
/plugin search code-review
# 安装插件
/plugin install code-quality发布插件
准备发布
- 编写清晰的 README.md 说明
- 更新
plugin.json版本号（语义化版本） - 添加
CHANGELOG.md记录变更 - 编写 LICENSE 文件
发布到 npm（推荐）
bash
# 发布前确保 plugin.json 的 name 与 npm 包名匹配
npm publish
# 用户可通过 npm 安装
npx -y your-plugin-name发布到 GitHub
bash
# 创建 Release
git tag v1.0.0
git push origin v1.0.0
# 用户通过 Git URL 安装
/plugin install https://github.com/yourname/your-plugin最佳实践
- 技能描述要精确：Claude 根据 description 决定何时使用技能
- 版本控制：遵循语义化版本，破坏性变更升主版本号
- 文档完整：README 包含安装说明、配置选项和使用示例
- 测试充分：发布前在多个项目中测试
- 安全审查：插件 Hook 和 MCP 服务器的代码要经过安全审查
总结
Claude Code 插件系统提供了强大的扩展和共享机制。从简单的技能集合到包含 Hook、Agent 和 MCP 的完整工作流套件，插件让团队能够将最佳实践封装并复用。从独立配置开始，验证价值后再转换为插件分发。
来源：Claude Code 官方文档 - Create Plugins 原文作者：Anthropic Team