Claude Code插件系统全解析

GISer_Jing2026-06-02 16:17

Claude Code Plugin System 深度解析：从顶层设计到落地实践

作者视角：AI 前端架构师

版本参考：Claude Code v2.0.12+

一、为什么需要 Plugin System？

Claude Code 从一个单体 CLI 工具演进为多智能体编排平台，核心驱动力之一就是可扩展性。不同团队、不同项目对 AI 编码助手的需求千差万别：有人需要严格的安全审查，有人需要特定的前端设计风格，有人需要自动化 PR 流程。

Plugin System 的设计目标是：在不修改核心代码的前提下，允许任何人以声明式方式扩展 Claude Code 的能力。

二、顶层架构：Plugin System 在整体系统中的位置

在深入细节之前，先看 Plugin System 如何嵌入 Claude Code 的整体架构：
#mermaid-svg-umpvtpnU4meyndfL{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-umpvtpnU4meyndfL .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-umpvtpnU4meyndfL .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-umpvtpnU4meyndfL .error-icon{fill:#552222;}#mermaid-svg-umpvtpnU4meyndfL .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-umpvtpnU4meyndfL .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-umpvtpnU4meyndfL .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-umpvtpnU4meyndfL .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-umpvtpnU4meyndfL .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-umpvtpnU4meyndfL .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-umpvtpnU4meyndfL .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-umpvtpnU4meyndfL .marker{fill:#333333;stroke:#333333;}#mermaid-svg-umpvtpnU4meyndfL .marker.cross{stroke:#333333;}#mermaid-svg-umpvtpnU4meyndfL svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-umpvtpnU4meyndfL p{margin:0;}#mermaid-svg-umpvtpnU4meyndfL .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-umpvtpnU4meyndfL .cluster-label text{fill:#333;}#mermaid-svg-umpvtpnU4meyndfL .cluster-label span{color:#333;}#mermaid-svg-umpvtpnU4meyndfL .cluster-label span p{background-color:transparent;}#mermaid-svg-umpvtpnU4meyndfL .label text,#mermaid-svg-umpvtpnU4meyndfL span{fill:#333;color:#333;}#mermaid-svg-umpvtpnU4meyndfL .node rect,#mermaid-svg-umpvtpnU4meyndfL .node circle,#mermaid-svg-umpvtpnU4meyndfL .node ellipse,#mermaid-svg-umpvtpnU4meyndfL .node polygon,#mermaid-svg-umpvtpnU4meyndfL .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-umpvtpnU4meyndfL .rough-node .label text,#mermaid-svg-umpvtpnU4meyndfL .node .label text,#mermaid-svg-umpvtpnU4meyndfL .image-shape .label,#mermaid-svg-umpvtpnU4meyndfL .icon-shape .label{text-anchor:middle;}#mermaid-svg-umpvtpnU4meyndfL .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-umpvtpnU4meyndfL .rough-node .label,#mermaid-svg-umpvtpnU4meyndfL .node .label,#mermaid-svg-umpvtpnU4meyndfL .image-shape .label,#mermaid-svg-umpvtpnU4meyndfL .icon-shape .label{text-align:center;}#mermaid-svg-umpvtpnU4meyndfL .node.clickable{cursor:pointer;}#mermaid-svg-umpvtpnU4meyndfL .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-umpvtpnU4meyndfL .arrowheadPath{fill:#333333;}#mermaid-svg-umpvtpnU4meyndfL .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-umpvtpnU4meyndfL .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-umpvtpnU4meyndfL .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-umpvtpnU4meyndfL .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-umpvtpnU4meyndfL .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-umpvtpnU4meyndfL .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-umpvtpnU4meyndfL .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-umpvtpnU4meyndfL .cluster text{fill:#333;}#mermaid-svg-umpvtpnU4meyndfL .cluster span{color:#333;}#mermaid-svg-umpvtpnU4meyndfL div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-umpvtpnU4meyndfL .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-umpvtpnU4meyndfL rect.text{fill:none;stroke-width:0;}#mermaid-svg-umpvtpnU4meyndfL .icon-shape,#mermaid-svg-umpvtpnU4meyndfL .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-umpvtpnU4meyndfL .icon-shape p,#mermaid-svg-umpvtpnU4meyndfL .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-umpvtpnU4meyndfL .icon-shape .label rect,#mermaid-svg-umpvtpnU4meyndfL .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-umpvtpnU4meyndfL .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-umpvtpnU4meyndfL .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-umpvtpnU4meyndfL :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} Plugin 组件（五类）
Claude Code 核心引擎
Plugin System（本文重点）
用户层
用户 / 终端 REPL
Slash Commands

/plugin install

/plugin enable
Plugin Discovery

四级作用域扫描
Manifest 解析

plugin.json / marketplace.json
Trust Dialog

安全信任校验
Component Loader

组件注册分发
Slash Command Registry

命令注册表
Agent Orchestrator

智能体编排器
Lifecycle Hook Manager

生命周期钩子管理器
Skill Context Provider

技能上下文注入器
MCP Client Manager

MCP 服务集成
commands/

自定义 Slash 命令
agents/

专用子智能体
hooks/hooks.json

生命周期钩子
skills/SKILL.md

领域知识技能
.mcp.json

MCP 服务配置

Plugin System 是一个中间层，它负责发现、验证、加载插件，并将插件的五类组件分发注册到对应的核心引擎中。

三、Plugin Discovery：四级作用域模型

Plugin System 的第一个核心设计是分层作用域发现机制，优先级从高到低：

作用域 路径 优先级 适用场景
Managed .claude-plugin/marketplace.json 最高 Anthropic 官方随 Claude Code 分发的插件
Project .claude/plugins/ 中 项目级插件，提交到版本控制，团队共享
User ~/.claude/plugins/ 低 个人跨项目插件
Auto-load .claude/skills/ 最低 本地技能，无需 marketplace 注册，自动加载

#mermaid-svg-rO1geZRbzgAb8yzT{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-rO1geZRbzgAb8yzT .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-rO1geZRbzgAb8yzT .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-rO1geZRbzgAb8yzT .error-icon{fill:#552222;}#mermaid-svg-rO1geZRbzgAb8yzT .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-rO1geZRbzgAb8yzT .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-rO1geZRbzgAb8yzT .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-rO1geZRbzgAb8yzT .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-rO1geZRbzgAb8yzT .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-rO1geZRbzgAb8yzT .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-rO1geZRbzgAb8yzT .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-rO1geZRbzgAb8yzT .marker{fill:#333333;stroke:#333333;}#mermaid-svg-rO1geZRbzgAb8yzT .marker.cross{stroke:#333333;}#mermaid-svg-rO1geZRbzgAb8yzT svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-rO1geZRbzgAb8yzT p{margin:0;}#mermaid-svg-rO1geZRbzgAb8yzT .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-rO1geZRbzgAb8yzT .cluster-label text{fill:#333;}#mermaid-svg-rO1geZRbzgAb8yzT .cluster-label span{color:#333;}#mermaid-svg-rO1geZRbzgAb8yzT .cluster-label span p{background-color:transparent;}#mermaid-svg-rO1geZRbzgAb8yzT .label text,#mermaid-svg-rO1geZRbzgAb8yzT span{fill:#333;color:#333;}#mermaid-svg-rO1geZRbzgAb8yzT .node rect,#mermaid-svg-rO1geZRbzgAb8yzT .node circle,#mermaid-svg-rO1geZRbzgAb8yzT .node ellipse,#mermaid-svg-rO1geZRbzgAb8yzT .node polygon,#mermaid-svg-rO1geZRbzgAb8yzT .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-rO1geZRbzgAb8yzT .rough-node .label text,#mermaid-svg-rO1geZRbzgAb8yzT .node .label text,#mermaid-svg-rO1geZRbzgAb8yzT .image-shape .label,#mermaid-svg-rO1geZRbzgAb8yzT .icon-shape .label{text-anchor:middle;}#mermaid-svg-rO1geZRbzgAb8yzT .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-rO1geZRbzgAb8yzT .rough-node .label,#mermaid-svg-rO1geZRbzgAb8yzT .node .label,#mermaid-svg-rO1geZRbzgAb8yzT .image-shape .label,#mermaid-svg-rO1geZRbzgAb8yzT .icon-shape .label{text-align:center;}#mermaid-svg-rO1geZRbzgAb8yzT .node.clickable{cursor:pointer;}#mermaid-svg-rO1geZRbzgAb8yzT .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-rO1geZRbzgAb8yzT .arrowheadPath{fill:#333333;}#mermaid-svg-rO1geZRbzgAb8yzT .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-rO1geZRbzgAb8yzT .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-rO1geZRbzgAb8yzT .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-rO1geZRbzgAb8yzT .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-rO1geZRbzgAb8yzT .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-rO1geZRbzgAb8yzT .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-rO1geZRbzgAb8yzT .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-rO1geZRbzgAb8yzT .cluster text{fill:#333;}#mermaid-svg-rO1geZRbzgAb8yzT .cluster span{color:#333;}#mermaid-svg-rO1geZRbzgAb8yzT div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-rO1geZRbzgAb8yzT .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-rO1geZRbzgAb8yzT rect.text{fill:none;stroke-width:0;}#mermaid-svg-rO1geZRbzgAb8yzT .icon-shape,#mermaid-svg-rO1geZRbzgAb8yzT .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-rO1geZRbzgAb8yzT .icon-shape p,#mermaid-svg-rO1geZRbzgAb8yzT .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-rO1geZRbzgAb8yzT .icon-shape .label rect,#mermaid-svg-rO1geZRbzgAb8yzT .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-rO1geZRbzgAb8yzT .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-rO1geZRbzgAb8yzT .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-rO1geZRbzgAb8yzT :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 含可执行组件/Hooks
纯声明式
用户批准
用户拒绝
Session 启动
扫描 .claude-plugin/marketplace.json

Managed 作用域
扫描 .claude/plugins/

Project 作用域
扫描 ~/.claude/plugins/

User 作用域
扫描 .claude/skills/

Auto-load 作用域
需要 Workspace

Trust 校验？
显示 Trust Dialog

等待用户确认
加载 Plugin 组件

注册到核心引擎
跳过该插件

设计亮点 ：Auto-load 作用域（.claude/skills/）允许开发者在本地快速迭代插件，无需发布到 marketplace，极大降低了开发门槛。

四、Plugin Manifest：两层声明式配置

4.1 Marketplace 级别：marketplace.json

这是插件集合的注册表，定义了哪些插件可被发现：

json 复制代码 
{
  "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
  "name": "claude-code-plugins",
  "version": "1.0.0",
  "owner": { "name": "Anthropic", "email": "support@anthropic.com" },
  "plugins": [
    {
      "name": "code-review",
      "description": "Automated code review for pull requests...",
      "version": "1.0.0",
      "author": { "name": "Boris Cherny", "email": "boris@anthropic.com" },
      "source": "./plugins/code-review",
      "category": "productivity"
    }
  ]
}

source 字段支持四种安装源，覆盖了从本地开发到企业分发的全场景：
#mermaid-svg-0WM5cmWlx9I4OCa1{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-0WM5cmWlx9I4OCa1 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-0WM5cmWlx9I4OCa1 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-0WM5cmWlx9I4OCa1 .error-icon{fill:#552222;}#mermaid-svg-0WM5cmWlx9I4OCa1 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-0WM5cmWlx9I4OCa1 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-0WM5cmWlx9I4OCa1 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-0WM5cmWlx9I4OCa1 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-0WM5cmWlx9I4OCa1 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-0WM5cmWlx9I4OCa1 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-0WM5cmWlx9I4OCa1 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-0WM5cmWlx9I4OCa1 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-0WM5cmWlx9I4OCa1 .marker.cross{stroke:#333333;}#mermaid-svg-0WM5cmWlx9I4OCa1 svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-0WM5cmWlx9I4OCa1 p{margin:0;}#mermaid-svg-0WM5cmWlx9I4OCa1 .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-0WM5cmWlx9I4OCa1 .cluster-label text{fill:#333;}#mermaid-svg-0WM5cmWlx9I4OCa1 .cluster-label span{color:#333;}#mermaid-svg-0WM5cmWlx9I4OCa1 .cluster-label span p{background-color:transparent;}#mermaid-svg-0WM5cmWlx9I4OCa1 .label text,#mermaid-svg-0WM5cmWlx9I4OCa1 span{fill:#333;color:#333;}#mermaid-svg-0WM5cmWlx9I4OCa1 .node rect,#mermaid-svg-0WM5cmWlx9I4OCa1 .node circle,#mermaid-svg-0WM5cmWlx9I4OCa1 .node ellipse,#mermaid-svg-0WM5cmWlx9I4OCa1 .node polygon,#mermaid-svg-0WM5cmWlx9I4OCa1 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-0WM5cmWlx9I4OCa1 .rough-node .label text,#mermaid-svg-0WM5cmWlx9I4OCa1 .node .label text,#mermaid-svg-0WM5cmWlx9I4OCa1 .image-shape .label,#mermaid-svg-0WM5cmWlx9I4OCa1 .icon-shape .label{text-anchor:middle;}#mermaid-svg-0WM5cmWlx9I4OCa1 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-0WM5cmWlx9I4OCa1 .rough-node .label,#mermaid-svg-0WM5cmWlx9I4OCa1 .node .label,#mermaid-svg-0WM5cmWlx9I4OCa1 .image-shape .label,#mermaid-svg-0WM5cmWlx9I4OCa1 .icon-shape .label{text-align:center;}#mermaid-svg-0WM5cmWlx9I4OCa1 .node.clickable{cursor:pointer;}#mermaid-svg-0WM5cmWlx9I4OCa1 .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-0WM5cmWlx9I4OCa1 .arrowheadPath{fill:#333333;}#mermaid-svg-0WM5cmWlx9I4OCa1 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-0WM5cmWlx9I4OCa1 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-0WM5cmWlx9I4OCa1 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-0WM5cmWlx9I4OCa1 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-0WM5cmWlx9I4OCa1 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-0WM5cmWlx9I4OCa1 .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-0WM5cmWlx9I4OCa1 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-0WM5cmWlx9I4OCa1 .cluster text{fill:#333;}#mermaid-svg-0WM5cmWlx9I4OCa1 .cluster span{color:#333;}#mermaid-svg-0WM5cmWlx9I4OCa1 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-0WM5cmWlx9I4OCa1 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-0WM5cmWlx9I4OCa1 rect.text{fill:none;stroke-width:0;}#mermaid-svg-0WM5cmWlx9I4OCa1 .icon-shape,#mermaid-svg-0WM5cmWlx9I4OCa1 .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-0WM5cmWlx9I4OCa1 .icon-shape p,#mermaid-svg-0WM5cmWlx9I4OCa1 .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-0WM5cmWlx9I4OCa1 .icon-shape .label rect,#mermaid-svg-0WM5cmWlx9I4OCa1 .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-0WM5cmWlx9I4OCa1 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-0WM5cmWlx9I4OCa1 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-0WM5cmWlx9I4OCa1 :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} source 字段
./plugins/name

本地相对路径
npm:package-name

npm 包
git:https://github.com/...

Git 仓库
git-subdir:https://...#subdir

Git 子目录（Monorepo）

4.2 Plugin 级别：plugin.json

每个插件目录下的 .claude-plugin/plugin.json 定义插件自身的元数据：

json 复制代码 
{
  "name": "security-guidance",
  "version": "2.0.0",
  "description": "Security review for Claude-generated code...",
  "author": { "name": "David Dworken", "email": "dworken@anthropic.com" },
  "homepage": "https://github.com/anthropics/claude-code/tree/main/plugins/security-guidance"
}

五、Plugin 目录结构：五类组件

每个插件遵循统一的目录约定：

复制代码 
plugin-name/
├── .claude-plugin/
│   └── plugin.json          # 插件元数据（必须）
├── commands/                # Slash 命令定义（.md 文件）
├── agents/                  # 专用子智能体定义（.md 文件）
├── skills/                  # 领域知识技能（SKILL.md）
├── hooks/                   # 生命周期钩子（hooks.json + 脚本）
├── .mcp.json                # MCP 服务配置
└── README.md                # 用户文档

组件与核心引擎的映射关系

#mermaid-svg-8Lg62l8oKQtiYj0h{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-8Lg62l8oKQtiYj0h .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-8Lg62l8oKQtiYj0h .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-8Lg62l8oKQtiYj0h .error-icon{fill:#552222;}#mermaid-svg-8Lg62l8oKQtiYj0h .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-8Lg62l8oKQtiYj0h .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-8Lg62l8oKQtiYj0h .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-8Lg62l8oKQtiYj0h .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-8Lg62l8oKQtiYj0h .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-8Lg62l8oKQtiYj0h .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-8Lg62l8oKQtiYj0h .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-8Lg62l8oKQtiYj0h .marker{fill:#333333;stroke:#333333;}#mermaid-svg-8Lg62l8oKQtiYj0h .marker.cross{stroke:#333333;}#mermaid-svg-8Lg62l8oKQtiYj0h svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-8Lg62l8oKQtiYj0h p{margin:0;}#mermaid-svg-8Lg62l8oKQtiYj0h .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-8Lg62l8oKQtiYj0h .cluster-label text{fill:#333;}#mermaid-svg-8Lg62l8oKQtiYj0h .cluster-label span{color:#333;}#mermaid-svg-8Lg62l8oKQtiYj0h .cluster-label span p{background-color:transparent;}#mermaid-svg-8Lg62l8oKQtiYj0h .label text,#mermaid-svg-8Lg62l8oKQtiYj0h span{fill:#333;color:#333;}#mermaid-svg-8Lg62l8oKQtiYj0h .node rect,#mermaid-svg-8Lg62l8oKQtiYj0h .node circle,#mermaid-svg-8Lg62l8oKQtiYj0h .node ellipse,#mermaid-svg-8Lg62l8oKQtiYj0h .node polygon,#mermaid-svg-8Lg62l8oKQtiYj0h .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-8Lg62l8oKQtiYj0h .rough-node .label text,#mermaid-svg-8Lg62l8oKQtiYj0h .node .label text,#mermaid-svg-8Lg62l8oKQtiYj0h .image-shape .label,#mermaid-svg-8Lg62l8oKQtiYj0h .icon-shape .label{text-anchor:middle;}#mermaid-svg-8Lg62l8oKQtiYj0h .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-8Lg62l8oKQtiYj0h .rough-node .label,#mermaid-svg-8Lg62l8oKQtiYj0h .node .label,#mermaid-svg-8Lg62l8oKQtiYj0h .image-shape .label,#mermaid-svg-8Lg62l8oKQtiYj0h .icon-shape .label{text-align:center;}#mermaid-svg-8Lg62l8oKQtiYj0h .node.clickable{cursor:pointer;}#mermaid-svg-8Lg62l8oKQtiYj0h .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-8Lg62l8oKQtiYj0h .arrowheadPath{fill:#333333;}#mermaid-svg-8Lg62l8oKQtiYj0h .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-8Lg62l8oKQtiYj0h .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-8Lg62l8oKQtiYj0h .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-8Lg62l8oKQtiYj0h .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-8Lg62l8oKQtiYj0h .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-8Lg62l8oKQtiYj0h .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-8Lg62l8oKQtiYj0h .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-8Lg62l8oKQtiYj0h .cluster text{fill:#333;}#mermaid-svg-8Lg62l8oKQtiYj0h .cluster span{color:#333;}#mermaid-svg-8Lg62l8oKQtiYj0h div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-8Lg62l8oKQtiYj0h .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-8Lg62l8oKQtiYj0h rect.text{fill:none;stroke-width:0;}#mermaid-svg-8Lg62l8oKQtiYj0h .icon-shape,#mermaid-svg-8Lg62l8oKQtiYj0h .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-8Lg62l8oKQtiYj0h .icon-shape p,#mermaid-svg-8Lg62l8oKQtiYj0h .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-8Lg62l8oKQtiYj0h .icon-shape .label rect,#mermaid-svg-8Lg62l8oKQtiYj0h .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-8Lg62l8oKQtiYj0h .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-8Lg62l8oKQtiYj0h .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-8Lg62l8oKQtiYj0h :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 核心引擎
Plugin 目录
commands/*.md
agents/*.md
skills/*/SKILL.md
hooks/hooks.json
.mcp.json
Slash Command Registry

/code-review, /feature-dev
Agent Orchestrator

code-explorer, code-architect
Skill Context Provider

按意图匹配注入上下文
Hook Manager

SessionStart, PreToolUse...
MCP Client Manager

外部工具集成

六、五类组件深度解析

6.1 Commands（Slash 命令）

最直观的扩展方式，以 Markdown 文件定义命令行为。code-review 插件提供的 /code-review 命令是典型案例：

  • 启动 4 个并行 Agent 分别审查 CLAUDE.md 合规性、Bug 检测、历史上下文
  • 每个 Issue 独立打分（0-100），过滤低于 80 分的误报
  • 支持 --comment 参数直接发布 PR 评论

6.2 Agents（专用子智能体）

插件可以定义具有特定专长的子智能体，由主 Agent 按需调度。feature-dev 插件的 7 阶段工作流中使用了三类专用 Agent：
"code-reviewer\n代码审查智能体" "code-architect\n架构设计智能体" "code-explorer\n代码探索智能体" "主 Agent" User "code-reviewer\n代码审查智能体" "code-architect\n架构设计智能体" "code-explorer\n代码探索智能体" "主 Agent" User #mermaid-svg-uEKwTwSSiex1N7QL{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-uEKwTwSSiex1N7QL .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-uEKwTwSSiex1N7QL .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-uEKwTwSSiex1N7QL .error-icon{fill:#552222;}#mermaid-svg-uEKwTwSSiex1N7QL .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-uEKwTwSSiex1N7QL .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-uEKwTwSSiex1N7QL .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-uEKwTwSSiex1N7QL .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-uEKwTwSSiex1N7QL .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-uEKwTwSSiex1N7QL .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-uEKwTwSSiex1N7QL .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-uEKwTwSSiex1N7QL .marker{fill:#333333;stroke:#333333;}#mermaid-svg-uEKwTwSSiex1N7QL .marker.cross{stroke:#333333;}#mermaid-svg-uEKwTwSSiex1N7QL svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-uEKwTwSSiex1N7QL p{margin:0;}#mermaid-svg-uEKwTwSSiex1N7QL .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-uEKwTwSSiex1N7QL text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-uEKwTwSSiex1N7QL .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-uEKwTwSSiex1N7QL .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-uEKwTwSSiex1N7QL .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-uEKwTwSSiex1N7QL .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-uEKwTwSSiex1N7QL #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-uEKwTwSSiex1N7QL .sequenceNumber{fill:white;}#mermaid-svg-uEKwTwSSiex1N7QL #sequencenumber{fill:#333;}#mermaid-svg-uEKwTwSSiex1N7QL #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-uEKwTwSSiex1N7QL .messageText{fill:#333;stroke:none;}#mermaid-svg-uEKwTwSSiex1N7QL .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-uEKwTwSSiex1N7QL .labelText,#mermaid-svg-uEKwTwSSiex1N7QL .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-uEKwTwSSiex1N7QL .loopText,#mermaid-svg-uEKwTwSSiex1N7QL .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-uEKwTwSSiex1N7QL .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-uEKwTwSSiex1N7QL .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-uEKwTwSSiex1N7QL .noteText,#mermaid-svg-uEKwTwSSiex1N7QL .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-uEKwTwSSiex1N7QL .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-uEKwTwSSiex1N7QL .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-uEKwTwSSiex1N7QL .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-uEKwTwSSiex1N7QL .actorPopupMenu{position:absolute;}#mermaid-svg-uEKwTwSSiex1N7QL .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-uEKwTwSSiex1N7QL .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-uEKwTwSSiex1N7QL .actor-man circle,#mermaid-svg-uEKwTwSSiex1N7QL line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-uEKwTwSSiex1N7QL :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} /feature-dev Add OAuth Phase 2: 并行探索代码库（2-3个实例） 返回关键文件和架构洞察 Phase 4: 并行设计3种架构方案 返回方案对比和推荐 展示方案，等待确认 选择方案3 Phase 5: 实现功能 Phase 6: 并行代码审查（3个实例） 返回高置信度问题 展示审查结果

6.3 Hooks（生命周期钩子）

Hook System 是 Plugin System 中最强大也最复杂的组件，允许在 Agent 执行生命周期的关键节点注入自定义逻辑。

支持的 Hook 事件类型：

Hook 类型 触发时机 典型用途
SessionStart 会话开始前 注入系统提示词、初始化环境
UserPromptSubmit 用户提交 Prompt 时 安全校验、上下文增强
PreToolUse 工具调用前 命令拦截、权限校验
PostToolUse 工具调用后 结果处理、日志记录
Stop Agent 准备停止时 任务完成验证、最终审查
WorktreeCreate 创建 Worktree 时 环境初始化
TeammateIdle 团队成员空闲时 任务编排和交接

Hook 执行协议（以 security-guidance 为例）：
#mermaid-svg-3PkM79T9PkjC0A9T{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-3PkM79T9PkjC0A9T .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-3PkM79T9PkjC0A9T .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-3PkM79T9PkjC0A9T .error-icon{fill:#552222;}#mermaid-svg-3PkM79T9PkjC0A9T .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-3PkM79T9PkjC0A9T .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-3PkM79T9PkjC0A9T .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-3PkM79T9PkjC0A9T .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-3PkM79T9PkjC0A9T .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-3PkM79T9PkjC0A9T .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-3PkM79T9PkjC0A9T .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-3PkM79T9PkjC0A9T .marker{fill:#333333;stroke:#333333;}#mermaid-svg-3PkM79T9PkjC0A9T .marker.cross{stroke:#333333;}#mermaid-svg-3PkM79T9PkjC0A9T svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-3PkM79T9PkjC0A9T p{margin:0;}#mermaid-svg-3PkM79T9PkjC0A9T .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-3PkM79T9PkjC0A9T .cluster-label text{fill:#333;}#mermaid-svg-3PkM79T9PkjC0A9T .cluster-label span{color:#333;}#mermaid-svg-3PkM79T9PkjC0A9T .cluster-label span p{background-color:transparent;}#mermaid-svg-3PkM79T9PkjC0A9T .label text,#mermaid-svg-3PkM79T9PkjC0A9T span{fill:#333;color:#333;}#mermaid-svg-3PkM79T9PkjC0A9T .node rect,#mermaid-svg-3PkM79T9PkjC0A9T .node circle,#mermaid-svg-3PkM79T9PkjC0A9T .node ellipse,#mermaid-svg-3PkM79T9PkjC0A9T .node polygon,#mermaid-svg-3PkM79T9PkjC0A9T .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-3PkM79T9PkjC0A9T .rough-node .label text,#mermaid-svg-3PkM79T9PkjC0A9T .node .label text,#mermaid-svg-3PkM79T9PkjC0A9T .image-shape .label,#mermaid-svg-3PkM79T9PkjC0A9T .icon-shape .label{text-anchor:middle;}#mermaid-svg-3PkM79T9PkjC0A9T .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-3PkM79T9PkjC0A9T .rough-node .label,#mermaid-svg-3PkM79T9PkjC0A9T .node .label,#mermaid-svg-3PkM79T9PkjC0A9T .image-shape .label,#mermaid-svg-3PkM79T9PkjC0A9T .icon-shape .label{text-align:center;}#mermaid-svg-3PkM79T9PkjC0A9T .node.clickable{cursor:pointer;}#mermaid-svg-3PkM79T9PkjC0A9T .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-3PkM79T9PkjC0A9T .arrowheadPath{fill:#333333;}#mermaid-svg-3PkM79T9PkjC0A9T .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-3PkM79T9PkjC0A9T .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-3PkM79T9PkjC0A9T .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-3PkM79T9PkjC0A9T .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-3PkM79T9PkjC0A9T .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-3PkM79T9PkjC0A9T .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-3PkM79T9PkjC0A9T .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-3PkM79T9PkjC0A9T .cluster text{fill:#333;}#mermaid-svg-3PkM79T9PkjC0A9T .cluster span{color:#333;}#mermaid-svg-3PkM79T9PkjC0A9T div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-3PkM79T9PkjC0A9T .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-3PkM79T9PkjC0A9T rect.text{fill:none;stroke-width:0;}#mermaid-svg-3PkM79T9PkjC0A9T .icon-shape,#mermaid-svg-3PkM79T9PkjC0A9T .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-3PkM79T9PkjC0A9T .icon-shape p,#mermaid-svg-3PkM79T9PkjC0A9T .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-3PkM79T9PkjC0A9T .icon-shape .label rect,#mermaid-svg-3PkM79T9PkjC0A9T .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-3PkM79T9PkjC0A9T .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-3PkM79T9PkjC0A9T .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-3PkM79T9PkjC0A9T :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 双层安全检查
无风险
发现风险
Stop Hook 触发
PostToolUse 触发

（Edit/Write 操作后）
执行 security_reminder_hook.py
Layer 1: 正则模式匹配

命令注入/XSS/SQL注入等
Layer 2: LLM 差异分析

git diff 对比基线 SHA
exit(0)

继续执行
exit(2)

阻断 + 反馈给 Claude

hooks.json 的配置格式支持 matcher（工具过滤）、if（条件执行）、asyncRewake（异步唤醒）等高级特性：

json 复制代码 
{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [{
          "type": "command",
          "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/sg-python.sh\" ...",
          "if": "Bash(git commit:*)",
          "asyncRewake": true,
          "rewakeMessage": "Background security review of commit..."
        }],
        "matcher": "Bash"
      }
    ]
  }
}

6.4 Skills（领域知识技能）

Skills 是 Plugin System 中最具创新性的设计------用 Markdown 文件作为 AI 的"专业知识包"。

三级渐进式加载策略（解决上下文窗口压力的关键设计）：
#mermaid-svg-eUY7jBsNDvKTuiCZ{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-eUY7jBsNDvKTuiCZ .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-eUY7jBsNDvKTuiCZ .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-eUY7jBsNDvKTuiCZ .error-icon{fill:#552222;}#mermaid-svg-eUY7jBsNDvKTuiCZ .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-eUY7jBsNDvKTuiCZ .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-eUY7jBsNDvKTuiCZ .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-eUY7jBsNDvKTuiCZ .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-eUY7jBsNDvKTuiCZ .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-eUY7jBsNDvKTuiCZ .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-eUY7jBsNDvKTuiCZ .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-eUY7jBsNDvKTuiCZ .marker{fill:#333333;stroke:#333333;}#mermaid-svg-eUY7jBsNDvKTuiCZ .marker.cross{stroke:#333333;}#mermaid-svg-eUY7jBsNDvKTuiCZ svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-eUY7jBsNDvKTuiCZ p{margin:0;}#mermaid-svg-eUY7jBsNDvKTuiCZ .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-eUY7jBsNDvKTuiCZ .cluster-label text{fill:#333;}#mermaid-svg-eUY7jBsNDvKTuiCZ .cluster-label span{color:#333;}#mermaid-svg-eUY7jBsNDvKTuiCZ .cluster-label span p{background-color:transparent;}#mermaid-svg-eUY7jBsNDvKTuiCZ .label text,#mermaid-svg-eUY7jBsNDvKTuiCZ span{fill:#333;color:#333;}#mermaid-svg-eUY7jBsNDvKTuiCZ .node rect,#mermaid-svg-eUY7jBsNDvKTuiCZ .node circle,#mermaid-svg-eUY7jBsNDvKTuiCZ .node ellipse,#mermaid-svg-eUY7jBsNDvKTuiCZ .node polygon,#mermaid-svg-eUY7jBsNDvKTuiCZ .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-eUY7jBsNDvKTuiCZ .rough-node .label text,#mermaid-svg-eUY7jBsNDvKTuiCZ .node .label text,#mermaid-svg-eUY7jBsNDvKTuiCZ .image-shape .label,#mermaid-svg-eUY7jBsNDvKTuiCZ .icon-shape .label{text-anchor:middle;}#mermaid-svg-eUY7jBsNDvKTuiCZ .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-eUY7jBsNDvKTuiCZ .rough-node .label,#mermaid-svg-eUY7jBsNDvKTuiCZ .node .label,#mermaid-svg-eUY7jBsNDvKTuiCZ .image-shape .label,#mermaid-svg-eUY7jBsNDvKTuiCZ .icon-shape .label{text-align:center;}#mermaid-svg-eUY7jBsNDvKTuiCZ .node.clickable{cursor:pointer;}#mermaid-svg-eUY7jBsNDvKTuiCZ .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-eUY7jBsNDvKTuiCZ .arrowheadPath{fill:#333333;}#mermaid-svg-eUY7jBsNDvKTuiCZ .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-eUY7jBsNDvKTuiCZ .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-eUY7jBsNDvKTuiCZ .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-eUY7jBsNDvKTuiCZ .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-eUY7jBsNDvKTuiCZ .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-eUY7jBsNDvKTuiCZ .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-eUY7jBsNDvKTuiCZ .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-eUY7jBsNDvKTuiCZ .cluster text{fill:#333;}#mermaid-svg-eUY7jBsNDvKTuiCZ .cluster span{color:#333;}#mermaid-svg-eUY7jBsNDvKTuiCZ div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-eUY7jBsNDvKTuiCZ .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-eUY7jBsNDvKTuiCZ rect.text{fill:none;stroke-width:0;}#mermaid-svg-eUY7jBsNDvKTuiCZ .icon-shape,#mermaid-svg-eUY7jBsNDvKTuiCZ .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-eUY7jBsNDvKTuiCZ .icon-shape p,#mermaid-svg-eUY7jBsNDvKTuiCZ .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-eUY7jBsNDvKTuiCZ .icon-shape .label rect,#mermaid-svg-eUY7jBsNDvKTuiCZ .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-eUY7jBsNDvKTuiCZ .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-eUY7jBsNDvKTuiCZ .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-eUY7jBsNDvKTuiCZ :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 意图匹配
需要执行/查询
Level 1: 元数据

name + description

~100 词

始终在系统提示中
Level 2: 指令

SKILL.md 正文

< 5000 词

意图匹配时加载
Level 3: 资源

scripts/ references/

无限制

Claude 主动调用时加载

以 frontend-design 技能为例，其 SKILL.md 的 frontmatter 决定了触发时机：

yaml 复制代码 
---
name: frontend-design
description: Create distinctive, production-grade frontend interfaces...
             Use this skill when the user asks to build web components,
             pages, or applications.
---

当用户说"帮我做一个音乐 App 的 Dashboard"，Agent 扫描所有已注册技能的 description，匹配到 frontend-design，然后将完整的设计指导原则（避免 AI 审美、选择大胆字体、使用 CSS 动画等）注入上下文。 11

6.5 MCP Servers（外部工具集成）

插件可以通过 .mcp.json 捆绑 MCP 服务器配置，Claude Code 会自动连接这些外部工具。MCP 子进程会自动接收 CLAUDE_CODE_SESSION_ID 和 CLAUDECODE=1 环境变量，实现会话上下文传递。 2

七、Plugin Marketplace：官方插件生态

当前官方 marketplace 包含 13 个插件，覆盖四大类别：
#mermaid-svg-o4vuLkNhOb2v5Gap{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-o4vuLkNhOb2v5Gap .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-o4vuLkNhOb2v5Gap .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-o4vuLkNhOb2v5Gap .error-icon{fill:#552222;}#mermaid-svg-o4vuLkNhOb2v5Gap .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-o4vuLkNhOb2v5Gap .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-o4vuLkNhOb2v5Gap .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-o4vuLkNhOb2v5Gap .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-o4vuLkNhOb2v5Gap .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-o4vuLkNhOb2v5Gap .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-o4vuLkNhOb2v5Gap .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-o4vuLkNhOb2v5Gap .marker{fill:#333333;stroke:#333333;}#mermaid-svg-o4vuLkNhOb2v5Gap .marker.cross{stroke:#333333;}#mermaid-svg-o4vuLkNhOb2v5Gap svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-o4vuLkNhOb2v5Gap p{margin:0;}#mermaid-svg-o4vuLkNhOb2v5Gap .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-o4vuLkNhOb2v5Gap .cluster-label text{fill:#333;}#mermaid-svg-o4vuLkNhOb2v5Gap .cluster-label span{color:#333;}#mermaid-svg-o4vuLkNhOb2v5Gap .cluster-label span p{background-color:transparent;}#mermaid-svg-o4vuLkNhOb2v5Gap .label text,#mermaid-svg-o4vuLkNhOb2v5Gap span{fill:#333;color:#333;}#mermaid-svg-o4vuLkNhOb2v5Gap .node rect,#mermaid-svg-o4vuLkNhOb2v5Gap .node circle,#mermaid-svg-o4vuLkNhOb2v5Gap .node ellipse,#mermaid-svg-o4vuLkNhOb2v5Gap .node polygon,#mermaid-svg-o4vuLkNhOb2v5Gap .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-o4vuLkNhOb2v5Gap .rough-node .label text,#mermaid-svg-o4vuLkNhOb2v5Gap .node .label text,#mermaid-svg-o4vuLkNhOb2v5Gap .image-shape .label,#mermaid-svg-o4vuLkNhOb2v5Gap .icon-shape .label{text-anchor:middle;}#mermaid-svg-o4vuLkNhOb2v5Gap .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-o4vuLkNhOb2v5Gap .rough-node .label,#mermaid-svg-o4vuLkNhOb2v5Gap .node .label,#mermaid-svg-o4vuLkNhOb2v5Gap .image-shape .label,#mermaid-svg-o4vuLkNhOb2v5Gap .icon-shape .label{text-align:center;}#mermaid-svg-o4vuLkNhOb2v5Gap .node.clickable{cursor:pointer;}#mermaid-svg-o4vuLkNhOb2v5Gap .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-o4vuLkNhOb2v5Gap .arrowheadPath{fill:#333333;}#mermaid-svg-o4vuLkNhOb2v5Gap .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-o4vuLkNhOb2v5Gap .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-o4vuLkNhOb2v5Gap .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-o4vuLkNhOb2v5Gap .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-o4vuLkNhOb2v5Gap .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-o4vuLkNhOb2v5Gap .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-o4vuLkNhOb2v5Gap .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-o4vuLkNhOb2v5Gap .cluster text{fill:#333;}#mermaid-svg-o4vuLkNhOb2v5Gap .cluster span{color:#333;}#mermaid-svg-o4vuLkNhOb2v5Gap div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-o4vuLkNhOb2v5Gap .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-o4vuLkNhOb2v5Gap rect.text{fill:none;stroke-width:0;}#mermaid-svg-o4vuLkNhOb2v5Gap .icon-shape,#mermaid-svg-o4vuLkNhOb2v5Gap .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-o4vuLkNhOb2v5Gap .icon-shape p,#mermaid-svg-o4vuLkNhOb2v5Gap .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-o4vuLkNhOb2v5Gap .icon-shape .label rect,#mermaid-svg-o4vuLkNhOb2v5Gap .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-o4vuLkNhOb2v5Gap .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-o4vuLkNhOb2v5Gap .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-o4vuLkNhOb2v5Gap :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} marketplace.json

13 个官方插件
Development（6个）
Productivity（4个）
Learning（2个）
Security（1个）
agent-sdk-dev

Agent SDK 开发套件
feature-dev

7阶段功能开发工作流
frontend-design

高质量前端设计技能
plugin-dev

插件开发工具包
ralph-wiggum

自引用迭代开发循环
claude-opus-4-5-migration

模型迁移助手
code-review

多 Agent 置信度 PR 审查
commit-commands

Git 工作流自动化
hookify

自定义 Hook 规则生成
pr-review-toolkit

专项 PR 审查套件
explanatory-output-style

教育性代码解释
learning-output-style

交互式学习模式
security-guidance

安全漏洞实时检测

八、Plugin 管理命令

bash 复制代码 
# 从 marketplace 安装插件
/plugin install code-review

# 启用/禁用插件
/plugin enable security-guidance
/plugin disable learning-output-style

# 浏览 marketplace（支持按当前目录相关性排序）
/plugin marketplace

# 验证插件结构
/plugin validate

# 脚手架新插件（在 .claude/skills/ 下创建）
claude plugin init my-plugin

# 诊断插件问题
/doctor
```[2](#0-1) 

---

## 九、安全模型：Trust Dialog 机制

Plugin System 的安全设计遵循**最小信任原则**：

```mermaid
sequenceDiagram
    participant User
    participant PluginSystem as "Plugin System"
    participant TrustDialog as "Trust Dialog"
    participant Engine as "核心引擎"

    User->>PluginSystem: /plugin enable security-guidance
    PluginSystem->>PluginSystem: 解析 plugin.json\n检测可执行组件（Hooks/Scripts）
    PluginSystem->>TrustDialog: 展示插件信息\n（名称、来源、作者、权限）
    TrustDialog->>User: "此插件包含可执行 Hooks，是否信任？"
    User->>TrustDialog: 确认
    TrustDialog->>Engine: 注册插件组件
    Engine->>User: 插件已激活

关键安全特性：

  • 含可执行组件的插件必须经过 Trust Dialog 确认
  • 插件可声明 defaultEnabled: false，需用户手动启用
  • 依赖插件自动启用，但仍需经过信任校验
  • allowed-tools 系统防止插件绕过权限提示 13

十、开发者视角：如何构建一个插件

以构建一个"代码风格检查"插件为例，完整流程如下：

Step 1：脚手架

bash 复制代码 
claude plugin init style-checker

Step 2：目录结构

复制代码 
style-checker/
├── .claude-plugin/
│   └── plugin.json
├── hooks/
│   ├── hooks.json          # 定义 PreToolUse Hook
│   └── style_check.py      # 检查逻辑
└── README.md

Step 3：定义 Hook（hooks/hooks.json）

json 复制代码 
{
  "hooks": {
    "PostToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/style_check.py\""
      }],
      "matcher": "Edit|Write"
    }]
  }
}

Step 4：实现检查逻辑（hooks/style_check.py）

python 复制代码 
import json, sys, re

data = json.load(sys.stdin)
tool_input = data.get("tool_input", {})
content = tool_input.get("new_content", "")

# 检查 console.log 遗留
if re.search(r'console\.log\(', content):
    print("Warning: console.log found, consider removing before commit", file=sys.stderr)
    sys.exit(2)  # 阻断并反馈给 Claude

sys.exit(0)

Step 5：发布到 marketplace

json 复制代码 
// .claude-plugin/marketplace.json 中添加
{
  "name": "style-checker",
  "source": "git:https://github.com/yourname/style-checker",
  "category": "productivity"
}

十一、架构总结

Claude Code Plugin System 的设计哲学可以归纳为三点：

  1. 声明优于命令：插件通过 JSON/Markdown 声明能力，而非直接操作核心代码
  2. 渐进式加载：Skills 的三级加载策略在能力扩展和上下文效率之间取得平衡
  3. 安全优先 ：Trust Dialog + 作用域隔离确保插件生态的可信度 14 15
复制代码
相关推荐
Mh15 小时前
别再只会 `find` 了：Map 在前端业务里的真实用法
前端·javascript
奔跑中的小象15 小时前
统信UOS + 天数AI卡部署SGLang服务手册
人工智能·uos·sglang·天数智芯
DevSecOps选型指南15 小时前
中国版Mythos，为何是悬镜安全灵脉CodeAI？
人工智能·安全
Shockang15 小时前
LangGraph 状态机实战
人工智能
陈随易15 小时前
FFmpeg 9.0 发布，代号 Lei，音视频处理再升级
前端·后端·程序员
刹那芳华199215 小时前
循环神经网络的从零开始实现(RNN)
人工智能·rnn·深度学习
阿童木写作16 小时前
跨境图片翻译工具多合一，批量图片视频字幕翻译加智能抠图
人工智能·python·音视频·语音识别
科技之门16 小时前
AI3D从建模到贴图、绑骨和动画的完整流程怎么做？V2Fun完整工作流指南
人工智能·3d·贴图
宇宙第一小趴菜16 小时前
二、机器学习的应用领域和发展史
人工智能·机器学习
前端开发江鸟16 小时前
我写过 MCP Server，却一直以为 MCP 只有 Tool
人工智能
热门推荐
01如何新建文件夹？ 电脑新建文件夹的4种方法02GitHub 镜像站点03国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）04Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费05微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新06AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路072026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？082026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片0900 Debian字符界面如何支持中文10历年考研数学一、数学二、数学三真题试卷及答案PDF