规范文件

Claude Code 插件：配置、磁盘与会话三层怎样排查

分清插件包、独立 Skill 与 marketplace，再逐层检查插件是否真正进入当前会话。

AI Nav City撰写 / 更新 2026年11月4日

插件安装完成后，当前会话里找不到能力，需要分层排查。官方把插件描述为一起安装加载的组件目录，marketplace 是发现与获取目录。本文目标是给本机 Claude Code 建立加载检查表，不安装插件、不调用其中能力。

核验日期: 2026年11月4日 · 未实测
适用于: Claude Code 适用于本机 Claude Code；官方页面未给统一版本门槛，以 2026-11-04 核验与实际界面为准。[1]
涉及工具: Claude Code

文件位置

路径	适用范围	读取方式
`<plugin>/.claude-plugin/plugin.json`	插件包的 manifest 位置；组件目录按官方组件规则放置。	manifest 提供名称和可选元数据，插件还需在设置、磁盘与会话中可用。[1]

什么时候用

插件已安装，但当前会话找不到其中 Skill 或 MCP 能力。[1]

什么时候不用

只想保存一份私人 Skill，且不需要把多个组件打包分发。[1]

先分清三个对象

插件可包含 skills、agents、hooks 和 MCP servers 等组件；marketplace 是列出插件和获取位置的目录，不能把目录添加成功当插件已经可用。独立 Skill、Hook 或 MCP 可以单独配置，只有需要成组分发和更新时才考虑插件包。[1]

按三层记录实际状态

官方加载说明分三层：Settings 记录已加 marketplace 与启用插件；Disk 的 ~/.claude/plugins/ 保存获取安装内容；Session 在启动或重新加载时载入插件。原创排查表为每层记录预期名称、实际观察与缺口。先定位缺在哪一层，再阅读对应安装或加载指南，不反复安装来猜原因。[1]

本地开发的入口

manifest 通常位于 .claude-plugin/plugin.json，包含 name，可另加版本和描述。官方提供 --plugin-dir 从目录加载开发插件的入口；它不需要先创建 marketplace。此页只解释入口，实际采用时先读 Create a plugin 的目录与命令规则，并检查组件路径、脚本及外部连接。[1]

启用影响与停止条件

启用插件不只影响调用它的回合：可调用组件的名称与描述进入上下文，MCP 进程和 Hook 也可能随会话运行。官方提醒插件可按用户权限运行代码。来源、脚本或连接范围不清楚时先暂停启用。本页没有安装插件、执行 --plugin-dir、改变设置或触发外部连接；上下文用量与实际费用需另看真实记录。[1]

来源

以下均为官方页面，核验日期见各条；链接指向核验时的版本。

Anthropic · Plugins overview
2026年11月4日

发现错误？告诉我们 →