Create custom plugins to extend Claude Code with skills, agents, hooks, and MCP servers.
创建自定义插件以扩展 Claude Code 的功能，包括技能、agent、钩子和 MCP 服务器。
Plugins let you extend Claude Code with custom functionality that can be shared across projects and teams.
插件允许你通过可跨项目和团队共享的自定义功能扩展 Claude Code。
Looking to install existing plugins? See Discover and install plugins.
想安装现有插件？请参阅"发现和安装插件"。
https://code.claude.com/docs/en/discover-plugins
一，When to use plugins vs standalone configuration
何时使用插件与独立配置
Claude Code supports two ways to add custom skills, agents, and hooks:
Claude Code 支持两种添加自定义skills、agent和钩子的方式：
1，Standalone (.claude/ directory)
独立使用（ .claude/ 目录）
技能名称：/hello
最适合：Personal workflows, project-specific customizations, quick experiments
个人工作流程、项目特定定制、快速实验
2，Plugins (directories with .claude-plugin/plugin.json)
插件（带有 .claude-plugin/plugin.json 的目录）
技能名称：/plugin-name:hello
最适合：Sharing with teammates, distributing to community, versioned releases, reusable across projects
与队友分享，分发给社区，版本化发布，跨项目复用
1.1 Use standalone configuration when:
在以下情况使用独立配置：
You're customizing Claude Code for a single project
你正在为单个项目定制 Claude Code
The configuration is personal and doesn't need to be shared
配置是私人的，不需要共享
You're experimenting with skills or hooks before packaging them
你正在测试技能或钩子，然后再将它们打包
You want short skill names like /hello or /review
你想使用短技能名称，如 /hello 或 /review
1.2 Use plugins when: 使用插件的情况：
You want to share functionality with your team or community
你想与你的团队或社区共享功能
You need the same skills/agents across multiple projects
你需要在多个项目中使用相同的 skills/agents
You want version control and easy updates for your extensions
你希望为你的扩展提供版本控制和轻松更新
You're distributing through a marketplace
你通过市场进行分发
You're okay with namespaced skills like /my-plugin:hello (namespacing prevents conflicts between plugins)
你可以接受命名空间技能，如 /my-plugin:hello （命名空间可以防止插件之间的冲突）
Start with standalone configuration in .claude/ for quick iteration, then convert to a plugin when you're ready to share.
从 .claude/ 中的独立配置开始，以便快速迭代，当你准备好分享时再将其转换为插件。
二，Quickstart 快速入门
This quickstart walks you through creating a plugin with a custom skill. You'll create a manifest (the configuration file that defines your plugin), add a skill, and test it locally using the --plugin-dir flag.
本快速入门将指导你使用自定义技能创建一个插件。你将创建一个清单（定义插件的配置文件），添加一个技能，并使用 --plugin-dir 标志在本地测试它。
2.1 Prerequisites 前提条件
Claude Code installed and authenticated
已安装并认证 Claude Code
Claude Code version 1.0.33 or later (run claude --version to check)
Claude Code 版本 1.0.33 或更高版本（运行 claude --version 检查）
If you don't see the /plugin command, update Claude Code to the latest version.
如果你看不到 /plugin 命令，请将 Claude Code 更新到最新版本。
2.2 Create your first plugin 创建你的第一个插件
分下面5步
1，Create the plugin directory
创建插件目录
Every plugin lives in its own directory containing a manifest and your skills, agents, or hooks. Create one now:
每个插件都存在于自己的目录中，该目录包含一个清单文件以及你的技能skills、agents代理或钩子。现在创建一个：
mkdir my-first-plugin
2，Create the plugin manifest
创建插件清单
The manifest file at .claude-plugin/plugin.json defines your plugin's identity: its name, description, and version. Claude Code uses this metadata to display your plugin in the plugin manager.
位于 .claude-plugin/plugin.json 的清单文件定义了你的插件的标识：它的名称、描述和版本。Claude Code 使用这些元数据在插件管理器中显示你的插件。
Create the .claude-plugin directory inside your plugin folder:
在你的插件文件夹内创建 .claude-plugin 目录：
mkdir my-first-plugin/.claude-plugin
Then create my-first-plugin/.claude-plugin/plugin.json with this content:
然后创建 my-first-plugin/.claude-plugin/plugin.json 并包含以下内容：
```bash
{
"name": "my-first-plugin",
"description": "A greeting plugin to learn the basics",
"version": "1.0.0",
"author": {
"name": "Your Name"
}
}
```
其中
name：Unique identifier and skill namespace. Skills are prefixed with this (e.g., /my-first-plugin:hello).
唯一标识符和技能命名空间。技能会以这个前缀开头（例如， /my-first-plugin:hello ）。
description：Shown in the plugin manager when browsing or installing plugins.
在浏览或安装插件时，会在插件管理器中显示。
version：Track releases using semantic versioning.
使用语义版本控制来跟踪发布。
author：Optional. Helpful for attribution.
可选。有助于归属
此外还有 homepage 、 repository 和 license 等其他字段。
- Add a skill 添加技能
Skills live in the skills/ directory. Each skill is a folder containing a SKILL.md file. The folder name becomes the skill name, prefixed with the plugin's namespace (hello/ in a plugin named my-first-plugin creates /my-first-plugin:hello).
技能位于 skills/ 目录中。每个技能是一个包含 SKILL.md 文件的文件夹。文件夹名称成为技能名称，并带有插件的命名空间前缀（在名为 my-first-plugin 的插件中， hello/ 创建 /my-first-plugin:hello ）。
Create a skill directory in your plugin folder:
在你的插件文件夹中创建一个技能目录：
mkdir -p my-first-plugin/skills/hello
Then create my-first-plugin/skills/hello/SKILL.md with this content:
然后创建 my-first-plugin/skills/hello/SKILL.md 并包含以下内容：
```bash
description: Greet the user with a friendly message #用友好的消息问候用户
disable-model-invocation: true #禁用模型调用
Greet the user warmly and ask how you can help them today. #今天我能为你做些什么？
```
4,Test your plugin 测试你的插件
Run Claude Code with the --plugin-dir flag to load your plugin:
使用 --plugin-dir 标志运行 Claude Code 以加载你的插件：
claude --plugin-dir ./my-first-plugin
Once Claude Code starts, try your new command:
Claude Code 启动后，尝试你的新命令：
/my-first-plugin:hello
You'll see Claude respond with a greeting. Run /help to see your command listed under the plugin namespace.
你会看到 Claude 回应问候。运行 /help 可以在插件命名空间下看到你的命令。
Why namespacing? Plugin skills are always namespaced (like /greet:hello) to prevent conflicts when multiple plugins have skills with the same name.
为什么需要命名空间？插件技能总是命名空间（如 /greet:hello ）的，以防止多个插件拥有相同名称的技能时发生冲突。
To change the namespace prefix, update the name field in plugin.json.
要更改命名空间前缀，请更新 plugin.json 中的 name 字段。
5,Add skill arguments 添加技能参数
Make your skill dynamic by accepting user input. The $ARGUMENTS placeholder captures any text the user provides after the skill name.
通过接受用户输入使你的技能动态化。 $ARGUMENTS 占位符会捕获用户在技能名称后提供的任何文本。
Update your hello.md file: 更新你的 hello.md 文件：（my-first-plugin/commands/hello.md）
```bash
description: Greet the user with a personalized message
Hello Command
Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.
```
热情地向名为"$ARGUMENTS"的用户打招呼，并询问今天你能如何帮助他。使问候更加个性化和鼓舞人心。
Restart Claude Code to pick up the changes, then try the command with your name:
重启 Claude Code 以应用更改，然后使用你的名字尝试该命令：
/my-first-plugin:hello Alex
Claude will greet you by name.
Claude 将用你的名字向你打招呼。
You've successfully created and tested a plugin with these key components:
好的，你已成功创建并测试了一个包含这些关键组件的插件：
Plugin manifest (.claude-plugin/plugin.json): describes your plugin's metadata
插件清单（ .claude-plugin/plugin.json ）：描述你的插件元数据
Commands directory (commands/): contains your custom skills
命令目录（ commands/ ）：包含你的自定义技能 ？？？ 这里是不是有问题？
Skill arguments ($ARGUMENTS): captures user input for dynamic behavior
技能参数（ $ARGUMENTS ）：捕获用户输入以实现动态行为
The --plugin-dir flag is useful for development and testing.
--plugin-dir 标志对于开发和测试很有用。
三，Plugin structure overview
插件结构概述
You've created a plugin with a skill, but plugins can include much more: custom agents, hooks, MCP servers, and LSP servers.
你已经创建了一个带有技能的插件，但插件可以包含更多内容：自定义代理、钩子、MCP 服务器和 LSP 服务器。
Common mistake: Don't put commands/, agents/, skills/, or hooks/ inside the .claude-plugin/ directory. Only plugin.json goes inside .claude-plugin/. All other directories must be at the plugin root level.
常见错误：不要将 commands/ 、 agents/ 、 skills/ 或 hooks/ 放在 .claude-plugin/ 目录内。只有 plugin.json 放在 .claude-plugin/ 内。所有其他目录都必须在插件根级别。
以下目录都在Plugin root 插件根目录
.claude-plugin/ ：Contains only plugin.json manifest (required)
仅包含 plugin.json 清单（必需）
commands/：Skills as Markdown files 技能作为 Markdown 文件
skills/：Agent Skills with SKILL.md files
带有 SKILL.md 文件的代理技能
agents/：Custom agent definitions 自定义代理定义
hooks/：Event handlers in hooks.json # hooks.json 中的事件处理器
.mcp.json：MCP server configurations
MCP 服务器配置
.lsp.json：LSP server configurations for code intelligence
代码智能的 LSP 服务器配置
四，Develop more complex plugins
开发更复杂的插件
Once you're comfortable with basic plugins, you can create more sophisticated extensions.
当你熟悉基本插件后，可以创建更复杂的扩展。
4.1 Add Skills to your plugin
为你的插件添加技能
Plugins can include Agent Skills to extend Claude's capabilities. Skills are model-invoked: Claude automatically uses them based on the task context.
插件可以包含Agent Skills代理技能来扩展 Claude 的功能。技能Skills是模型调用的：Claude 会根据任务上下文自动使用它们。
Add a skills/ directory at your plugin root with Skill folders containing SKILL.md files:
在你的插件根目录下添加一个 skills/ 目录，其中包含技能文件夹和 SKILL.md 文件：
```bash
my-plugin/
├── .claude-plugin/
│ └── plugin.json
└── skills/
└── code-review/
└── SKILL.md
```
Each SKILL.md needs frontmatter with name and description fields, followed by instructions:
每个 SKILL.md 需要带有 name 和 description 字段的 frontmatter，随后是说明：
```bash
name: code-review
description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality. #审查代码以最佳实践和潜在问题。在审查代码、检查PR或分析代码质量时使用。
When reviewing code, check for: #在审查代码时，检查：
-
Code organization and structure #代码组织和结构
-
Error handling #错误处理
-
Security concerns #安全问题
-
Test coverage #测试覆盖率
```
After installing the plugin, restart Claude Code to load the Skills.
安装插件后，重启 Claude Code 以加载技能。
4.2 Add LSP servers to your plugin
为你的插件添加 LSP 服务器
For common languages like TypeScript, Python, and Rust, install the pre-built LSP plugins from the official marketplace. Create custom LSP plugins only when you need support for languages not already covered.
对于 TypeScript、Python 和 Rust 等常见语言，从官方市场安装预构建的 LSP 插件。只有当你需要支持尚未覆盖的语言时，才创建自定义 LSP 插件。
LSP (Language Server Protocol) plugins give Claude real-time code intelligence. If you need to support a language that doesn't have an official LSP plugin, you can create your own by adding an .lsp.json file to your plugin:
LSP（语言服务器协议）插件为 Claude 提供实时代码智能。如果你需要支持没有官方 LSP 插件的语言，可以通过向你的插件添加一个 .lsp.json 文件来创建自己的插件：
```bash
{
"go": {
"command": "gopls",
"args": ["serve"],
"extensionToLanguage": {
".go": "go"
}
}
}
```
Users installing your plugin must have the language server binary installed on their machine.
安装你插件的用户必须在他们的机器上安装语言服务器二进制文件。
4.3 Organize complex plugins 组织复杂插件
For plugins with many components, organize your directory structure by functionality.
对于包含多个组件的插件，请按功能组织你的目录结构。
4.4 Test your plugins locally
在本地测试你的插件
Use the --plugin-dir flag to test plugins during development. This loads your plugin directly without requiring installation.
使用 --plugin-dir 标志在开发过程中测试插件。这可以直接加载你的插件，无需安装。
claude --plugin-dir ./my-plugin
As you make changes to your plugin, restart Claude Code to pick up the updates. Test your plugin components:
当你对插件进行修改时，重启 Claude Code 以获取更新。再测试你的插件组件：
Try your commands with /command-name
使用 /command-name 尝试你的命令
Check that agents appear in /agents
检查代理是否出现在 /agents
Verify hooks work as expected
验证钩子是否按预期工作
You can load multiple plugins at once by specifying the flag multiple times:
你可以通过多次指定标志来同时加载多个插件：
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two
4.5 Debug plugin issues 调试插件问题
If your plugin isn't working as expected:
如果你的插件未按预期工作：
Check the structure: Ensure your directories are at the plugin root, not inside .claude-plugin/
检查结构：确保你的目录位于插件根目录，而不是在 .claude-plugin/ 内部
Test components individually: Check each command, agent, and hook separately
单独测试组件：分别检查每个命令、代理和钩子
4.6 Share your plugins 分享你的插件
When your plugin is ready to share:
当你的插件准备分享时：
- Add documentation: Include a README.md with installation and usage instructions
添加文档：包含 README.md 的安装和使用说明
- Version your plugin: Use semantic versioning in your plugin.json
为插件版本化：在 plugin.json 中使用语义版本控制
- Create or use a marketplace: Distribute through plugin marketplaces for installation
创建或使用市场：通过插件市场分发以供安装
Test with others: Have team members test the plugin before wider distribution
与他人测试：在广泛分发之前，让团队成员测试插件
五，Convert existing configurations to plugins
将现有配置转换为插件
If you already have skills or hooks in your .claude/ directory, you can convert them into a plugin for easier sharing and distribution.
如果你在 .claude/ 目录中已经拥有技能或钩子，你可以将它们转换为插件，以便更轻松地共享和分发。
5.1 Migration steps 迁移步骤
有如下4步，
1，Create the plugin structure
创建插件结构
Create a new plugin directory:
创建一个新的插件目录：
mkdir -p my-plugin/.claude-plugin
Create the manifest file at my-plugin/.claude-plugin/plugin.json:
在 my-plugin/.claude-plugin/plugin.json 创建清单文件：
```bash
{
"name": "my-plugin",
"description": "Migrated from standalone configuration",
"version": "1.0.0"
}
```
2, Copy your existing files 复制你的现有文件
Copy your existing configurations to the plugin directory:
将你的现有配置复制到插件目录：
```bash
Copy commands
cp -r .claude/commands my-plugin/
Copy agents (if any)
cp -r .claude/agents my-plugin/
Copy skills (if any)
cp -r .claude/skills my-plugin/
```
3, Migrate hooks 迁移钩子
If you have hooks in your settings, create a hooks directory:
如果你在设置中有钩子，创建一个 hooks 目录：
mkdir my-plugin/hooks
Create my-plugin/hooks/hooks.json with your hooks configuration. Copy the hooks object from your .claude/settings.json or settings.local.json---the format is the same:
创建 my-plugin/hooks/hooks.json ，并包含你的钩子配置。从你的 .claude/settings.json 或 settings.local.json 复制 hooks 对象------格式相同：
```bash
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [{ "type": "command", "command": "npm run lint:fix $FILE" }]
}
]
}
}
```
4, Test your migrated plugin
测试你的迁移插件
Load your plugin to verify everything works:
加载你的插件以验证一切正常：
claude --plugin-dir ./my-plugin
Test each component: run your commands, check agents appear in /agents, and verify hooks trigger correctly.
测试每个组件：运行你的命令，检查代理是否出现在 /agents 中，并验证钩子是否正确触发。
5.2 What changes when migrating
迁移时会发生什么变化
原来 Only available in one project
仅在一个项目中可用
现在Can be shared via marketplaces
可通过市场共享
原来.claude/commands/ 中的文件
现在移到了 plugin-name/commands/ 中
原来settings.json 中的钩子 ，现在移到了hooks/hooks.json 中
原来Must manually copy to share
必须手动复制才能分享
现在可通过 /plugin install 安装
After migrating, you can remove the original files from .claude/ to avoid duplicates. The plugin version will take precedence when loaded.
迁移后，你可以从 .claude/ 删除原始文件以避免重复。加载时插件版本将优先。
小结：
可以将skills快速转换成插件。