Plugins 是 Claude Code 的扩展打包机制——把 Skills、子代理、Hooks 和 MCP 服务器打包成可分享的单元，供团队复用或发布到社区市场。
插件 vs 独立配置：何时选择哪种？
使用独立配置（.claude/ 目录），当：
- 只为当前项目定制
- 个人使用，不需要共享
- 快速实验 Skills 或 Hooks
- 想要简短的命令名（
/hello而不是/my-plugin:hello）
使用插件，当：
- 想与团队或社区共享
- 需要在多个项目间复用
- 想要版本控制和便捷更新
- 准备发布到市场
- 接受命名空间前缀（
/my-plugin:hello，防止冲突）
建议路径：先在 .claude/ 中快速迭代，成熟后再转为插件。
快速开始：创建第一个插件
第一步：创建插件目录
bash
mkdir my-first-plugin第二步：创建插件清单
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：插件唯一标识符，也是 Skill 的命名空间前缀（如/my-first-plugin:hello）description：在插件管理器中显示的描述version：使用语义版本控制（如1.0.0）author（可选）：作者信息，便于归属
其他可选字段：homepage、repository、license。
第三步：添加 Skill
创建 my-first-plugin/skills/hello.md：
markdown
---
name: hello
description: 用友好的方式问候用户
---
用温暖、个性化的方式问候用户。如果知道用户名字，使用他们的名字。
加入一句鼓励的话，让他们开心地开始工作。在插件中，技能通过 /my-first-plugin:hello 调用。
第四步：本地测试
bash
claude --plugin-dir ./my-first-plugin
/my-first-plugin:hello--plugin-dir 无需安装即可测试插件，快速迭代。
插件目录结构
my-plugin/
├── .claude-plugin/
│ └── plugin.json # 插件清单（必须）
├── skills/ # Skill 文件
│ ├── review.md
│ └── deploy.md
├── agents/ # 子代理定义
│ └── security-reviewer.md
├── hooks/ # Hook 配置
│ └── hooks.json
├── mcp/ # MCP 服务器
│ └── my-server/
├── settings/ # 插件默认设置
│ └── defaults.json
└── README.md
进阶：添加 LSP 服务器
插件可以携带语言服务器（LSP），为 Claude Code 提供代码智能支持：
json
{
"name": "my-plugin",
"lspServers": [
{
"name": "my-lsp",
"command": "my-lsp-server",
"args": ["--stdio"]
}
]
}内置默认设置
插件可以附带默认配置，安装后自动生效：
settings/defaults.json：
json
{
"tools": {
"allow": ["group:fs", "Bash"]
}
}调试技巧
bash
# 检查插件是否正确加载
claude --plugin-dir ./my-plugin /debug
# 查看可用的插件 Skills
/help常见问题：
- Skill 不显示：检查
plugin.json的name字段是否正确，确认文件在skills/目录 - 命名冲突：确认 plugin
name是唯一的，避免与其他插件冲突 - 版本太低：需要 Claude Code 1.0.33+，运行
claude --version检查
发布到官方市场
- 准备好
README.md、设置合适的version - 发布到 npm（确保包名以
@claude-code-plugin/开头，或按市场要求） - 在 Claude Code 文档提交 PR，申请加入官方插件目录
用户安装方式：
bash
/plugin install my-plugin-name从现有配置迁移到插件
如果已有 .claude/skills/ 和 .claude/agents/ 配置，迁移步骤：
- 创建插件目录和
plugin.json - 将
skills/、agents/、hooks/移入插件目录 - 注意：独立配置中的
/hello在插件中变为/my-plugin:hello - 用
--plugin-dir测试后发布
原文：Create plugins - Claude Code Docs | 来源：Anthropic 官方文档