11 插件与市场——扩展的打包与分发

原文：Create plugins + Plugin Marketplaces + Discover plugins

什么是 Plugin

Plugin 是 Claude Code 扩展的打包和分发单元。它把 Skill、Hook、Agent、MCP Server 打成一个可安装的包，就像 npm package 或 VS Code Extension。

Plugin 本身不提供新的机制——它是已有机制的容器。

Plugin vs 单机配置

Plugin 目录结构

my-plugin/
├── .claude-plugin/
│   └── plugin.json      ← 清单文件（唯一必须在这个子目录的）
├── skills/              ← Skill（SKILL.md）
├── agents/              ← 自定义 Agent
├── commands/            ← 命令（Markdown）
├── hooks/
│   └── hooks.json       ← Hook 定义
├── .mcp.json            ← MCP Server 配置
├── .lsp.json            ← LSP Server 配置
└── settings.json        ← 默认设置

常见错误：不要把 skills/、agents/ 等放在 .claude-plugin/ 里面。只有 plugin.json 放在那里。

plugin.json 清单

{
  "name": "my-plugin",
  "description": "A description of what this plugin does",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

name 字段决定了命名空间——所有 Skill 会加上 /my-plugin: 前缀。

开发和测试

# 本地测试
claude --plugin-dir ./my-plugin

# 修改后热重载
/reload-plugins

# 加载多个插件
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

从单机配置迁移

mkdir -p my-plugin/.claude-plugin
# 写 plugin.json
cp -r .claude/skills my-plugin/
cp -r .claude/agents my-plugin/
# Hook 从 settings.json 移到 hooks/hooks.json

Marketplace

Marketplace 是插件的分发渠道，本质是一个包含 marketplace.json 索引文件的 Git 仓库。

官方 Marketplace

Anthropic 维护的官方市场，通过 claude.ai/settings/plugins/submit 提交。

自定义 Marketplace

团队可以搭建自己的 marketplace：

// marketplace.json
{
  "name": "My Team Plugins",
  "plugins": [
    {
      "name": "my-plugin",
      "version": "1.0.0",
      "description": "...",
      "git": "https://github.com/team/my-plugin.git"
    }
  ]
}

安装插件

# 从默认 marketplace
/plugin install my-plugin

# 从自定义 marketplace
/plugin install my-plugin --marketplace https://github.com/team/marketplace

知识检测

概念理解题

1. 为什么 Plugin 使用命名空间（/plugin-name:skill）？如果不用命名空间会有什么问题？

2. Plugin 的 settings.json 目前只支持 agent 键。这个设计意味着什么？一个 Plugin 可以完全改变 Claude Code 的默认行为吗？

应用题

3. 你的团队有一套代码规范检查的 Hook + 一个部署 Skill + 一个 Jira MCP Server。把它们打包成一个 Plugin，写出目录结构和 plugin.json。

4. 你在官方 Marketplace 上发现了一个插件的 Hook 会在每次编辑后执行一段 shell 脚本。你会有什么安全顾虑？

参见

• 03-扩展体系总览 — Plugin 在架构中的位置
• 04-Skill-技能系统、05-Hook-生命周期钩子 — Plugin 打包的核心内容

参考答案

1. 命名空间的必要性

如果两个 Plugin 都有一个叫 review 的 Skill，没有命名空间就会冲突——Claude 不知道该用哪个。命名空间（plugin-a:review vs plugin-b:review）让它们共存。这和编程中的 module/namespace/package 是同一个思路——避免全局命名冲突。

2. settings.json 只支持 agent 键

这意味着 Plugin 不能修改 Claude Code 的核心行为（权限模式、沙箱设置等）——它只能声明自己提供的 Agent 配置。这是安全设计：防止恶意 Plugin 通过 settings 关闭安全检查或修改权限。Plugin 提供能力扩展，不提供行为覆盖。

3. 团队 Plugin 结构

team-workflow/
├── .claude-plugin/
│   └── plugin.json        # {"name":"team-workflow","version":"1.0.0"}
├── skills/
│   └── deploy/
│       └── SKILL.md       # 部署工作流
├── hooks/
│   └── hooks.json         # PostToolUse → eslint/prettier
├── .mcp.json              # Jira MCP Server 配置
└── settings.json          # {} (暂无 agent 覆盖)

安装后：/team-workflow:deploy 触发部署，Hook 自动格式化，Jira 工具可用。

4. 第三方 Plugin Hook 的安全顾虑

(1) Hook 以你的用户权限执行——恶意脚本可以读取 ssh key、环境变量、源代码 (2) PostToolUse Hook 在每次编辑后执行——高频率意味着攻击面大 (3) 脚本可能联网发送数据。缓解：(a) 安装前审查 Hook 脚本内容 (b) 优先选择开源且有社区审计的 Plugin (c) 在沙箱环境中先测试 (d) 检查 Plugin 是否有不必要的网络调用。