Claude Code Plugins 开发指南：封装 Skills、Agents、Hooks 和 MCP Servers

Claude Code Plugins 是把 Claude Code 自定义能力打包、共享和版本化的方式。一个 plugin 可以包含 skills、agents、hooks、MCP servers，并通过 manifest 描述身份和版本。

Plugins vs standalone .claude 配置#

Claude Code 有两种扩展方式：

Standalone 配置#

放在项目的 .claude/ 目录。

适合：

• 单项目定制
• 个人工作流
• 快速实验
• 想用短命令，例如 /deploy

Plugins#

独立目录，带 skills、agents、hooks 或 .claude-plugin/plugin.json。

适合：

• 团队共享
• 多项目复用
• 社区分发
• 版本化发布
• 避免命名冲突

插件中的 skill 会带命名空间，例如：

/my-first-plugin:hello

创建第一个 Plugin#

创建目录：

mkdir my-first-plugin
mkdir my-first-plugin/.claude-plugin

创建 manifest：

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

关键字段：

• name：唯一标识，也是 skill namespace
• description：插件管理器中显示
• version：控制更新；若省略，git commit SHA 可作为版本
• author：作者信息

添加 Skill#

插件 skill 放在：

my-first-plugin/skills/hello/SKILL.md

示例：

---
description: Greet the user with a friendly message
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.

加载后命令是：

/my-first-plugin:hello

命名空间避免了多个插件都提供 /hello 时的冲突。

支持参数：ARGUMENTS 占位符#

Skill 可以读取用户输入：

---
description: Greet the user with a personalized message
---

# Hello Skill

Greet the user named "ARGUMENTS_PLACEHOLDER" warmly and ask how you can help them today.

调用：

/my-first-plugin:hello Alex

本地测试#

开发期间可以用：

claude --plugin-dir ./my-first-plugin

进入 Claude Code 后测试：

/my-first-plugin:hello

修改后可用：

/reload-plugins

从本地 Skill 迁移为 Plugin#

官方建议：先用 .claude/ 做快速迭代，稳定后再转成 plugin。

这样你可以：

• 先验证工作流是否真的有用
• 再添加 manifest、namespace、版本管理
• 最后分享给团队或 marketplace

最佳实践#

• Plugin 名称保持短且唯一
• description 写清楚用途，不要泛泛而谈
• 对写文件/执行命令的 hooks 做权限设计
• MCP servers 不要默认带过宽权限
• 先用 --plugin-dir 本地测试
• 发布前写 README 和版本策略

来源：Claude Code 官方文档 - Plugins | 整理：ClaudeEagle