Appearance
创建插件
插件让你可以用自定义功能扩展 Claude Code，并与项目和团队共享。本指南介绍如何创建包含技能（Skills）、代理（Agents）、钩子（Hooks）和 MCP 服务器的插件。
想要安装已有插件？请查看发现并安装插件。完整技术规范请参阅插件技术参考。
插件 vs 独立配置
| 方式 | 技能名称格式 | 适合场景 |
|---|---|---|
独立（.claude/ 目录） | /hello | 个人工作流、项目定制、快速实验 |
插件（含 .claude-plugin/plugin.json 的目录） | /plugin-name:hello | 团队共享、社区分发、版本化发布、跨项目复用 |
使用独立配置的场景：
- 为单个项目定制 Claude Code
- 配置是个人的，无需共享
- 在打包前实验技能或钩子
- 需要简短的技能名称如
/hello或/deploy
使用插件的场景：
- 想与团队或社区共享功能
- 需要在多个项目中使用相同的技能/代理
- 需要版本控制和便捷更新
- 通过市场分发
- 可以接受命名空间化的技能名称如
/my-plugin:hello
建议先在
.claude/中用独立配置快速迭代，准备共享时再转换为插件。
快速入门
前提条件
- Claude Code 已安装并认证
- Claude Code 版本 1.0.33 或更高（运行
claude --version查看）
创建第一个插件
步骤 1：创建插件目录
bash
mkdir my-first-plugin步骤 2：创建插件清单
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 | 唯一标识符和技能命名空间（技能以此为前缀） |
description | 在插件管理器中显示 |
version | 使用语义化版本追踪发布 |
author | 可选，用于归属 |
步骤 3：添加技能
bash
mkdir -p my-first-plugin/skills/hello创建 my-first-plugin/skills/hello/SKILL.md：
markdown
---
description: 用友好的消息问候用户
disable-model-invocation: true
---
热情地问候用户，询问今天能为他们做什么。步骤 4：测试插件
bash
claude --plugin-dir ./my-first-plugin在 Claude Code 中尝试：
/my-first-plugin:hello步骤 5：添加技能参数
更新 SKILL.md：
markdown
---
description: 用个性化消息问候用户
---
热情地问候名为 "$ARGUMENTS" 的用户，询问今天能为他们做什么。让问候个性化且鼓励人心。运行 /reload-plugins 后测试：
/my-first-plugin:hello Alex插件结构概览
| 目录 | 位置 | 用途 |
|---|---|---|
.claude-plugin/ | 插件根目录 | 包含 plugin.json 清单 |
commands/ | 插件根目录 | Markdown 格式的技能文件 |
agents/ | 插件根目录 | 自定义代理定义 |
skills/ | 插件根目录 | 包含 SKILL.md 的代理技能 |
hooks/ | 插件根目录 | hooks.json 中的事件处理器 |
.mcp.json | 插件根目录 | MCP 服务器配置 |
.lsp.json | 插件根目录 | 代码智能 LSP 服务器配置 |
settings.json | 插件根目录 | 插件启用时应用的默认设置 |
常见错误：不要把
commands/、agents/、skills/或hooks/放在.claude-plugin/目录内。只有plugin.json放在.claude-plugin/内，其他所有目录必须在插件根目录级别。
开发更复杂的插件
添加 LSP 服务器
json
{
"go": {
"command": "gopls",
"args": ["serve"],
"extensionToLanguage": {
".go": "go"
}
}
}包含默认设置
json
{
"agent": "security-reviewer"
}本地测试
bash
# 加载单个插件
claude --plugin-dir ./my-plugin
# 同时加载多个插件
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two当 --plugin-dir 插件与已安装的市场插件同名时，本地版本优先，便于在不卸载的情况下测试变更。
修改后运行 /reload-plugins 即时生效，无需重启。
调试问题
- 检查结构：确保目录在插件根目录，而非在
.claude-plugin/内 - 逐个测试组件：单独检查每个命令、代理和钩子
- 使用调试工具：运行
claude --debug查看加载详情
从现有配置转换为插件
步骤 1：创建插件结构
bash
mkdir -p my-plugin/.claude-plugin创建 my-plugin/.claude-plugin/plugin.json：
json
{
"name": "my-plugin",
"description": "从独立配置迁移",
"version": "1.0.0"
}步骤 2：复制现有文件
bash
cp -r .claude/commands my-plugin/
cp -r .claude/agents my-plugin/ # 如有
cp -r .claude/skills my-plugin/ # 如有步骤 3：迁移钩子
创建 my-plugin/hooks/hooks.json，将 hooks 对象从 .claude/settings.json 复制过来：
json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }]
}
]
}
}迁移前后对比：
独立（.claude/） | 插件 |
|---|---|
| 仅在一个项目中可用 | 可通过市场共享 |
文件在 .claude/commands/ | 文件在 plugin-name/commands/ |
钩子在 settings.json | 钩子在 hooks/hooks.json |
| 必须手动复制才能共享 | 通过 /plugin install 安装 |
提交插件到官方市场
使用应用内提交表单：
- Claude.ai：claude.ai/settings/plugins/submit
- Console：platform.claude.com/plugins/submit