Claude Code Plugins 目录结构与加载机制

Claude Code Plugins 目录结构与加载机制目录结构~/.claude/plugins/ ├── marketplaces/ # Marketplace 插件源码只读 │ ├── claude-plugins-official/ │ ├── anthropic-agent-skills/ │ ├── everything-claude-code/ │ └── superpowers-marketplace/ ├── cache/ # 实际运行的插件实例 │ ├── claude-plugins-official/ │ ├── anthropic-agent-skills/ │ ├── everything-claude-code/ │ └── superpowers-marketplace/ ├── installed_plugins.json # 已安装插件清单 ├── known_marketplaces.json # 已知的 Marketplace 列表 ├── blocklist.json # 插件阻止列表 └── data/ # 插件数据目录两个目录的区别目录作用内容marketplaces/存放从 marketplace 下载的原始插件代码插件源码可更新时拉取新版本cache/实际运行的插件实例根据 installed_plugins.json 确定的版本为什么分离marketplaces/是原始仓库副本cache/是根据installed_plugins.json中指定版本运行的实例方便版本管理和回滚加载机制1. 读取已安装插件清单Claude Code 启动时首先读取installed_plugins.json{version:2,plugins:{everything-claude-codeeverything-claude-code:[{scope:user,installPath:/Users/username/.claude/plugins/cache/everything-claude-code/everything-claude-code/1.8.0,version:1.8.0}]}}2. 根据 installPath 加载插件读取installed_plugins.json获取所有已安装插件根据每个插件的installPath找到实际运行的插件目录加载插件的plugin.json清单文件扫描并加载插件的 hookshooks/hooks.json3. Hook 发现流程Claude Code 启动 ↓ 读取 installed_plugins.json ↓ 遍历每个插件的 installPath ↓ 读取插件目录的 plugin.json ↓ 检查 hooks/hooks.json 是否存在 ↓ 加载并注册 hooks 到当前会话插件清单文件详解plugin.json 位置路径说明插件根目录/plugin.json旧版/简单插件插件根目录/.claude-plugin/plugin.json新版插件分离 npm 包结构everything-claude-code采用新版结构everything-claude-code/ ├── package.json # npm 包管理 ├── .claude-plugin/ │ └── plugin.json # Claude Code 插件配置 ├── hooks/ ├── agents/ └── skills/installed_plugins.json记录所有已安装插件及其运行版本{plugins:{插件名称来源:[{scope:user,// user 或 project 级别installPath:...,// 实际运行路径version:1.8.0,// 版本号installedAt:时间戳,// 安装时间lastUpdated:时间戳,// 最后更新时间gitCommitSha:...// Git 提交 SHA}]}}plugin.json插件内部每个插件根目录必须有plugin.json{name:everything-claude-code,version:1.8.0,description:...,hooks:{PreToolUse:[...]}}插件目录结构示例everything-claude-code/ ├── plugin.json # 插件清单 ├── hooks/ │ └── hooks.json # Hook 配置 ├── agents/ # 子代理 ├── skills/ # 技能 ├── commands/ # 命令 └── README.md加载条件条件说明插件在installed_plugins.json中已安装且启用plugin.json存在且有效插件清单完整hooks/hooks.json存在有 hook 配置查看当前加载的插件# 方式1查看 installed_plugins.jsoncat~/.claude/plugins/installed_plugins.json# 方式2在 Claude Code 中使用 /plugins 命令如果支持# 方式3使用 --debug 模式启动claude--debug插件来源标识插件名格式插件名来源来源格式说明claude-plugins-officialAnthropic 官方插件anthropic-agent-skillsAnthropic Agent Skillseverything-claude-codeMarketplace 插件同名superpowers-marketplace第三方 Marketplace缓存更新机制当插件更新时从 marketplace 拉取新版本到marketplaces/更新installed_plugins.json中的installPath和版本下次启动时加载新版本