Claude Code的Plugin是怎么运行的

步骤 1：解析插件标识
         "superpowers@claude-plugins-official"
              ↓                    ↓
           插件名              市场名（官方市场，自动可用）

步骤 2：从市场源拉取插件
         市场注册在 $CLAUDE_CONFIG_DIR/plugins/marketplaces/ 下
         官方市场源：github.com/anthropics/claude-plugins-official
                    ↓
         读取市场的 .claude-plugin/marketplace.json
         找到 superpowers 的 source 路径
                    ↓
         下载插件文件

步骤 3：缓存到本地
         存储路径：$CLAUDE_CONFIG_DIR/plugins/cache/claude-plugins-official/superpowers/4.3.1/
         （注意：不是 ~/.claude/，而是 $CLAUDE_CONFIG_DIR 指向的目录）

步骤 4：写入安装记录
         记录到 $CLAUDE_CONFIG_DIR/plugins/installed_plugins.json：
         {
           "superpowers@claude-plugins-official": {
             "scope": "project",          ← 可以是 project 或 user
             "version": "4.3.1",
             "projectPath": "/res/dev/claude-working"
           }
         }

步骤 5：写入项目配置
         写入 .claude/settings.json：
         {
           "enabledPlugins": {
             "superpowers@claude-plugins-official": true
           }
         }

superpowers/4.3.1/
├── .claude-plugin/
│   ├── plugin.json                  ← 插件清单（必需）
│   └── marketplace.json             ← 市场清单
├── skills/                          ← 15 个 Skills
│   ├── brainstorming/SKILL.md
│   ├── test-driven-development/SKILL.md
│   ├── systematic-debugging/SKILL.md
│   ├── writing-plans/SKILL.md
│   ├── executing-plans/SKILL.md
│   ├── subagent-driven-development/SKILL.md
│   ├── dispatching-parallel-agents/SKILL.md
│   ├── requesting-code-review/SKILL.md
│   ├── receiving-code-review/SKILL.md
│   ├── verification-before-completion/SKILL.md
│   ├── finishing-a-development-branch/SKILL.md
│   ├── using-git-worktrees/SKILL.md
│   ├── using-superpowers/SKILL.md
│   ├── writing-skills/SKILL.md
│   └── code-quality-reviewer-prompt/SKILL.md
├── agents/                          ← 子代理定义
│   └── code-reviewer.md             ← 代码审查代理
├── hooks/                           ← 事件钩子
│   ├── hooks.json                   ← 钩子配置
│   ├── session-start                ← SessionStart 钩子脚本（bash）
│   └── run-hook.cmd                 ← 跨平台 polyglot 包装器
├── commands/                        ← 斜杠命令（目录存在但当前为空）
├── lib/
│   └── skills-core.js               ← Skill 发现/解析工具库
├── docs/                            ← 文档
├── tests/                           ← 测试套件
├── .cursor-plugin/plugin.json       ← Cursor 编辑器兼容
├── .opencode/                       ← OpenCode 兼容
├── .codex/                          ← Codex 兼容
└── .mcp.json                        ← MCP 服务器配置（可选）

{
  "name": "superpowers",
  "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
  "version": "4.3.1",
  "author": { "name": "Jesse Vincent", "email": "jesse@fsck.com" },
  "homepage": "https://github.com/obra/superpowers",
  "repository": "https://github.com/obra/superpowers",
  "license": "MIT"
}

Claude Code 启动（或 resume/clear/compact）
    │
    │ ══════════ 阶段 A：静态组装 ══════════
    │
    ├─① 读取 .claude/settings.json
    │      └─ enabledPlugins → 确定激活哪些插件
    │
    ├─② 从插件缓存加载已启用插件
    │      └─ $CLAUDE_CONFIG_DIR/plugins/cache/<市场>/<插件>/<版本>/
    │             │
    │             ├─ 读取 .claude-plugin/plugin.json → 插件元信息
    │             ├─ 扫描 skills/*/SKILL.md → 提取 YAML frontmatter (name + description)
    │             ├─ 扫描 agents/*.md → 注册可用子代理
    │             └─ 读取 hooks/hooks.json → 注册事件钩子
    │
    ├─③ 扫描项目 .claude/skills/*/SKILL.md → 提取独立 skill 的 frontmatter
    │
    ├─④ 读取 CLAUDE.md → 项目规则
    │
    ├─⑤ 组装系统提示（System Prompt）
    │      │
    │      ├─ [常驻] 基础 System Prompt（Claude Code 内置指令）
    │      ├─ [常驻] CLAUDE.md 内容（项目规则）
    │      └─ [常驻] 所有 skill 的 name + description 列表 ← Level 1 元数据
    │
    │ ══════════ 阶段 B：Hook 注入 ══════════
    │
    ├─⑥ 执行 SessionStart Hook
    │      │
    │      │  superpowers 的 hooks.json 定义：
    │      │  {
    │      │    "hooks": {
    │      │      "SessionStart": [{
    │      │        "matcher": "startup|resume|clear|compact",
    │      │        "hooks": [{
    │      │          "type": "command",
    │      │          "command": "'${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd' session-start"
    │      │        }]
    │      │      }]
    │      │    }
    │      │  }
    │      │
    │      └─ session-start 脚本执行：
    │             ├─ 读取 skills/using-superpowers/SKILL.md 完整内容
    │             ├─ 包裹在 <EXTREMELY_IMPORTANT> 标签中
    │             └─ 输出 JSON: { "additional_context": "..." }
    │                    │
    │                    └─ Claude Code 将其注入为 <system-reminder>  ← Level 0 行为规则
    │
    │ ══════════ 阶段 C：对话中按需加载 ══════════
    │
    ├─⑦ 用户发消息 / Claude 判断需要某个 skill
    │      └─ 调用 Skill 工具 → 加载 SKILL.md 正文              ← Level 2 完整指导
    │
    └─⑧ Skill 执行过程中按需引用
           ├─ Read references/*.md → 参考文档                   ← Level 3 捆绑资源
           ├─ Bash scripts/*.py → 执行脚本                     ← Level 3 捆绑资源
           └─ 引用 assets/* → 输出资源                          ← Level 3 捆绑资源

superpowers/                          ← 缓存中的插件目录
├── .claude-plugin/
│   └── plugin.json                   ← 插件清单（必需）
├── skills/                           ← Skills（就是你看到的那些）
│   ├── brainstorming/
│   │   └── SKILL.md
│   ├── test-driven-development/
│   │   └── SKILL.md
│   ├── systematic-debugging/
│   │   └── SKILL.md
│   └── ... (其他 skill)
├── commands/                         ← 斜杠命令（可选）
├── agents/                           ← 子代理定义（可选）
├── hooks/
│   └── hooks.json                    ← 事件钩子（可选）
└── .mcp.json                         ← MCP 服务器（可选）

The following skills are available for use with the Skill tool:
- superpowers:brainstorming: You MUST use this before any creative work...
- superpowers:test-driven-development: Use when implementing any feature...
- pdf: Use this skill whenever the user wants to do anything with PDF files...
（共 24 条，包括 15 个 superpowers skill + 9 个独立 skill）

---
name: code-reviewer
description: Use this agent when a major project step has been completed...
model: inherit
---

（代理的详细行为指导）

{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup|resume|clear|compact",   // ← 匹配哪些触发场景
      "hooks": [{
        "type": "command",                          // ← 类型：执行一条 shell 命令
        "command": "'${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd' session-start",
        "async": false                              // ← 同步执行，必须等它跑完才继续
      }]
    }]
  }
}

# 1. 读取 using-superpowers skill 的完整 SKILL.md 文件内容
using_superpowers_content=$(cat "${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md")

# 2. 用 <EXTREMELY_IMPORTANT> 标签包裹，加强语气
session_context="<EXTREMELY_IMPORTANT>
You have superpowers.
**Below is the full content of your 'superpowers:using-superpowers' skill...**
（SKILL.md 完整内容）
</EXTREMELY_IMPORTANT>"

# 3. JSON 转义后输出到 stdout
{
  "additional_context": "（上面那段内容）",
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "（同样的内容，兼容不同平台）"
  }
}

<system-reminder>
SessionStart:resume hook success: Success
</system-reminder>
<system-reminder>
SessionStart hook additional context: <EXTREMELY_IMPORTANT>
You have superpowers.

**Below is the full content of your 'superpowers:using-superpowers' skill...**

（一大段行为规则：强制检查 skill、12 条思维陷阱表、优先级规则等）

</EXTREMELY_IMPORTANT>
</system-reminder>

Claude Code 启动/恢复/清除/压缩
       │
       ▼
  触发 SessionStart 事件
       │
       ▼
  查找匹配的 hooks.json         ← "matcher": "startup|resume|clear|compact"
       │
       ▼
  执行 shell 命令               ← run-hook.cmd session-start
       │
       ▼
  session-start 脚本
       │
       ├─ cat SKILL.md                            ← 读取 skill 文件
       │
       ├─ 包裹 <EXTREMELY_IMPORTANT> 标签          ← 加强语气标记
       │
       └─ 输出 JSON 到 stdout                      ← { "additional_context": "..." }
              │
              ▼
  Claude Code 解析 stdout JSON
       │
       ├─ 提取 additional_context 字段
       │
       └─ 包裹为 <system-reminder> 注入对话上下文
              │
              ▼
  LLM 收到的上下文中多了一段 system-reminder
  内容 = using-superpowers 的完整行为规则

┌─────────────────────────────────────────────────────────┐
│                    Claude Code 基础设施                    │
│                                                         │
│  ┌─────────────┐  ┌─────────────┐  ┌────────────────┐  │
│  │ Skill 系统   │  │ Hooks 系统   │  │  Agent 系统    │  │
│  │ (发现+加载)  │  │ (事件驱动)   │  │  (子代理注册)  │  │
│  └──────┬──────┘  └──────┬──────┘  └───────┬────────┘  │
│         │                │                  │           │
│  ┌──────┴────────────────┴──────────────────┴────────┐  │
│  │              Plugin 管理器                          │  │
│  │  (marketplace → download → cache → register)      │  │
│  └──────┬────────────────────────────────────────────┘  │
│         │                                               │
│  ┌──────┴──────┐  ┌──────────┐  ┌──────────────────┐   │
│  │ settings.json│  │ CLAUDE.md│  │ settings.local    │   │
│  │ (启用控制)   │  │ (规则)    │  │ (权限白名单)     │   │
│  └─────────────┘  └──────────┘  └──────────────────┘   │
│                                                         │
│  ┌─────────┐ ┌──────┐ ┌──────┐ ┌────────────────────┐  │
│  │ Bash    │ │ Read │ │ Task │ │ TaskCreate/Update   │  │
│  │ (脚本)  │ │(引用) │ │(代理)│ │ (任务跟踪)         │  │
│  └─────────┘ └──────┘ └──────┘ └────────────────────┘  │
└─────────────────────────────────────────────────────────┘
          ↑          ↑          ↑          ↑
          │          │          │          │
    ┌─────┴──────────┴──────────┴──────────┴─────┐
    │           superpowers 插件                   │
    │  skills/ + agents/ + hooks/ + lib/          │
    └─────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                     软件开发生命周期                           │
│                                                             │
│  ┌─────────┐   ┌──────────┐   ┌───────────────────────┐    │
│  │ 构思     │   │ 设计      │   │ 开发                   │    │
│  │         │   │          │   │                       │    │
│  │ brain-  │──▶│ writing- │──▶│ test-driven-dev       │    │
│  │ storming│   │ plans    │   │ subagent-driven-dev   │    │
│  │         │   │          │   │ dispatching-parallel   │    │
│  │         │   │          │   │ using-git-worktrees    │    │
│  │         │   │          │   │ executing-plans        │    │
│  └─────────┘   └──────────┘   └───────────┬───────────┘    │
│                                            │                │
│  ┌─────────┐   ┌──────────┐   ┌───────────▼───────────┐    │
│  │ 收尾     │   │ 审查      │   │ 验证/调试              │    │
│  │         │   │          │   │                       │    │
│  │ finish- │◀──│ request- │◀──│ verification-before-  │    │
│  │ ing-a-  │   │ ing-code-│   │ completion            │    │
│  │ dev-    │   │ review   │   │ systematic-debugging  │    │
│  │ branch  │   │ receiv-  │   │                       │    │
│  │         │   │ ing-code-│   │                       │    │
│  │         │   │ review   │   │                       │    │
│  └─────────┘   └──────────┘   └───────────────────────┘    │
│                                                             │
│  ┌─────────────────────────────────────────┐                │
│  │ 元技能                                   │                │
│  │ using-superpowers / writing-skills       │                │
│  │ code-quality-reviewer-prompt             │                │
│  └─────────────────────────────────────────┘                │
└─────────────────────────────────────────────────────────────┘

{
  "name": "my-plugin",              // 必填，kebab-case
  "version": "1.0.0",               // 必填，语义化版本
  "description": "插件做什么",        // 必填
  "author": { "name": "你的名字" },  // 建议填写
  "license": "MIT"                   // 建议填写
}

my-plugin/
├── .claude-plugin/
│   └── plugin.json          ← 必需
└── skills/
    └── my-skill/
        └── SKILL.md         ← 至少一个 skill

---
name: my-plugin:my-skill              # 建议用 "插件名:技能名" 格式
description: >
  精确描述触发条件。这段文字决定 Claude 是否会使用这个 skill。
  要写清楚：(1) 做什么 (2) 什么时候触发 (3) 关键词列表
---

# Skill 标题

## 前置条件（可选）
触发此 skill 前需要确认什么

## 工作流程（核心）
1. 步骤一
2. 步骤二
3. 步骤三

## 检查清单（可选）
- [ ] 验证项 1
- [ ] 验证项 2

## 注意事项（可选）
禁止做什么、边界条件等

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear|compact",
        "hooks": [
          {
            "type": "command",
            "command": "'${CLAUDE_PLUGIN_ROOT}/hooks/my-hook-script'",
            "async": false
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "'${CLAUDE_PLUGIN_ROOT}/hooks/after-write'"
          }
        ]
      }
    ]
  }
}

---
name: my-agent
description: 描述什么时候应该使用这个代理
model: inherit
---

# 代理行为指导

（详细描述代理的职责、工作流程、输出格式）

# 方式 1：作为独立 skill（最简单）
mkdir -p .claude/skills/my-skill
# 编写 SKILL.md → 重启会话即可

# 方式 2：作为完整 plugin（需要 hook/agent 等能力时）
# 创建完整的 plugin 目录结构
# 通过 /plugin install 从本地路径安装

/plugin marketplace add <github-user>/<repo>

{
  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  "name": "marketplace-name",
  "version": "1.0.0",
  "description": "Description",
  "owner": { "name": "...", "email": "..." },
  "plugins": [
    {
      "name": "plugin-name",
      "description": "...",
      "source": "./plugins/plugin-name",
      "category": "development"
    }
  ]
}