前言：一次令人困惑的安装经历

最近在使用 Claude Code 时遇到了一个让我"小脑萎缩"的问题：

通过/plugin install安装了几个常用的 skill，在当前项目中使用正常。但当我切换到另一个项目时，却发现：

1. 在提示词中明确要求使用某个 skill，但实际执行中并没有触发
2. 输入/skills命令，发现列表中根本没有这个 skill
3. 检查/plugin list，也看不到任何已安装的 skill
4. 切换回原来的项目，skill 又神奇地出现了

这是为什么？明明安装时提供了三个选项：user scope、project scope 和 enterprise scope，我以为默认应该是 user scope（所有项目可用），但实际情况却完全不是这样。

更诡异的是，通过CC Switch 工具安装的 skill 却可以在所有项目中正常使用，而通过/plugin install安装的 skill 就不行。

本文将深入剖析这个问题，帮你彻底理解 Claude Code 中 Skill 的 scope 机制，以及如何正确安装和管理 skills。

核心问题：/plugin install 的默认行为陷阱

问题根源

当你执行/plugin install skill-name时，Claude Code 的实际行为是：

# 你以为的行为/plugininstallskill-name# → 期望：安装为全局可用插件，所有项目都能使用# 实际的行为/plugininstallskill-name# → 实际：在当前 workspace 上注册插件的启用状态# → 结果：只在当前项目可用，其他项目无法识别

这就是问题的根源：

/plugin install默认在当前 workspace 上注册插件的启用状态，而不是注册为全局可用插件。

虽然 Claude Code 没有公开显式的--scopeCLI 参数，但在内部实现上：

• 会在配置文件中记录"scope": "project"
• 会隐式绑定当前项目的路径（projectPath字段）
• 导致插件只在安装时的 workspace 中生效

配置文件的秘密

查看C:\Users\admin\.claude\plugins\installed_plugins.json：

{"version":2,"plugins":{"book-cover-generator@happy-claude-skills-gxj":[{"scope":"project","installPath":"C:\\Users\\admin\\.claude\\plugins\\cache\\...","projectPath":"D:\\MyDocument\\documents"// ← 绑定了项目路径！}]}}

关键字段：

• "scope": "project"：表示这是项目级 skill
• "projectPath": "D:\\MyDocument\\documents"：绑定到安装时的项目路径

后果：

• ✅ 在D:\MyDocument\documents项目中可用
• ❌ 在F:\mds项目中不可用
• ❌ 在其他任何项目中都不可用

Skill 可以是 User Scope 吗？

答案：可以！

重要澄清：Skill完全支持user scope，并且在很多场景下应该使用 user scope。

证据：

1. ✅ 通过CC Switch 工具安装的 skills 就是 user scope，在所有项目中都能正常使用
2. ✅ 手动修改installed_plugins.json为 user scope 后可以正常工作
3. ✅ 配置文件中的"scope": "user"字段是有效的

那为什么会有 Scope 的困惑？

问题根源：/plugin install的默认行为有问题

# 用户执行/plugininstallbook-cover-generator# 用户期望# → 安装为全局可用，所有项目都能使用# 实际行为# → 在当前 workspace 注册启用状态# → 配置文件记录：{"scope": "project", "projectPath": "当前路径"}# → 只在当前项目可用

核心问题：虽然内部支持 user scope，但/plugin install命令默认采用 project scope 的行为模式。

User Scope vs Project Scope 的适用场景

User Scope（推荐用于通用 skills）

适用场景：

• 通用工具类 skill（如 markdown-helper、book-cover-generator）
• 个人开发者的常用 skills
• 不依赖项目特定配置的 skills

优点：

• ✅ 所有项目都能使用
• ✅ 安装一次，到处可用
• ✅ 更新方便

示例：

# 这些 skills 适合 user scope- markdown-helper（Markdown 文档辅助） - book-cover-generator（生成书籍封面） - docx-format-replicator（Word 文档格式复制） - algorithmic-art（算法艺术生成）

Project Scope（推荐用于项目特定 skills）

适用场景：

• 需要读取项目 CLAUDE.md 的 skills
• 不同项目需要不同配置的 skills
• 团队协作项目的共享 skills

优点：

• ✅ 可以根据项目定制行为
• ✅ 不同项目可以使用不同版本
• ✅ 避免跨项目冲突

示例：

# 这些 skills 可能需要 project scope- commit（提交规范可能因项目而异） - review-pr（审查标准可能不同） - frontend-design（技术栈可能不同）

为什么有些 Skill 需要 Project Scope？

原因 1：上下文绑定

某些 skill 需要读取项目特定的配置：

# 项目 A 的 CLAUDE.md - 使用 TypeScript + React - 提交信息要求英文 + conventional commits 格式 - 代码风格：Prettier + ESLint # 项目 B 的 CLAUDE.md - 使用 Python + Django - 提交信息要求中文 + Jira 单号 - 代码风格：Black + Flake8

对于这类 skill，project scope 更合适。

原因 2：版本隔离

不同项目可能需要不同版本的 skill：

但这不意味着所有 skill 都必须是 project scope！

三个 Scope 选项的真相

设计意图 vs 实际行为

安装 skill 时，界面提供了三个选项：

1. User Scope（用户级）

位置：~/.claude/skills/ 或 ~/.claude/plugins/cache/ 设计意图：个人常用的通用 skill，所有项目都能访问 实际行为：✅ 完全可用，但 /plugin install 默认不使用此 scope

2. Project Scope（项目级）

位置：<project>/.claude/skills/ 设计意图：项目特定的 skill，只在当前项目可用 实际行为：✅ 完全可用，/plugin install 的默认选项

3. Enterprise Scope（企业级）

位置：企业账号关联的远程配置 设计意图：团队共享的 skill，组织内所有成员可用 实际行为：❓ 可能需要企业账号，未广泛测试

实际测试结果

# 测试 1：使用 CC Switch 工具（自动 user scope）# 通过 CC Switch 界面添加第三方 skill 仓库# 结果：✅ 安装成功，/skills 列表中可以看到，所有项目可用# 测试 2：/plugin install（默认 project scope 行为）/plugininstallfrontend-design# 结果：✅ 安装成功，但只在当前项目可用# 测试 3：手动修改配置文件为 user scope# 编辑 installed_plugins.json，将 scope 改为 user，删除 projectPath# 结果：✅ 所有项目可用

注意：Claude Code 目前没有公开的 CLI 参数来指定 scope，只能通过：

1. 使用CC Switch 工具（自动 user scope）
2. 手动修改配置文件（修改为 user scope）

核心问题

不是 user scope 不可用，而是/plugin install的默认行为有问题：

1. 默认使用 project scope

   • 用户没有明确指定 scope 时，默认为 project
   • 导致 skill 只在安装时的项目中可用

2. 绑定项目路径

   • 记录了projectPath字段
   • 在其他项目中无法识别

3. 没有明确提示

   • 安装时没有提示用户选择 scope
   • 用户以为安装成功就能全局使用

三种解决方案

核心发现

通过排查发现，Claude Code 存在两套独立的 Skill 管理系统：

系统 1: CC Switch 工具

• 位置：~/.claude/skills/
• 默认：user scope（所有项目可用）
• 识别命令：/skills
• 使用方式：通过 CC Switch 可视化界面添加仓库

系统 2: /plugin

• 位置：~/.claude/plugins/
• 默认：project scope（只在当前项目可用）
• 识别命令：/plugin list
• 配置文件：installed_plugins.json中记录"scope": "project"和"projectPath"

问题根源：/plugin install默认在当前 workspace 注册，并绑定项目路径，导致只在安装时的项目中可用。

解决方案

方案 1: 手动修改配置文件

编辑C:\Users\admin\.claude\plugins\installed_plugins.json:

{"version":2,"plugins":{"book-cover-generator@happy-claude-skills-gxj":[{"scope":"user",// ← 改为 user"installPath":"C:\\Users\\admin\\.claude\\plugins\\cache\\...",// 删除 projectPath 字段}]}}

步骤:

1. 关闭 Claude Code
2. 打开installed_plugins.json
3. 将所有"scope": "project"改为"scope": "user"
4. 删除所有"projectPath"字段
5. 保存文件
6. 重启 Claude Code

验证:

# 在任意项目中/plugin list# ✅ 应该能看到所有 skills

方案 2: 使用 CC Switch 工具（推荐）

如果你希望 skills 在所有项目中都可用：

操作步骤：

1. 打开 CC Switch 工具（可视化界面）
   
   

2. 添加第三方 skill 仓库
   
   

3. 自动安装为 user scope
   

验证：

/skills# ✅ 可以识别

优点：

• 自动使用 user scope
• 无需手动修改配置文件
• 更新方便

缺点：

• /plugin命令无法识别（两套系统不互通）

方案 3: 在每个项目中重新安装

如果你确实需要 project scope:

# 在项目 A 中cdF:\project-a /plugininstallbook-cover-generator# 在项目 B 中cdF:\project-b /plugininstallbook-cover-generator

优点:

• 每个项目可以使用不同版本的 skill
• 符合 Claude Code 的设计意图

缺点:

• 需要在每个项目中重复安装
• 占用更多磁盘空间

快速参考

两套系统对比

使用建议

总结

Claude Code 的 Skill 管理存在两套独立系统：CC Switch 工具（默认 user scope）和/plugin（默认 project scope）。

核心问题：/plugin install默认在当前 workspace 注册，导致只在安装时的项目可用。

解决方案：

• 通用 skill → 使用CC Switch 工具或手动修改配置文件
• 项目特定 skill → 使用/plugin install

希望这篇文章能帮你避免踩坑。如果遇到类似困惑，欢迎在评论区分享经验！

相关资源：

Claude Code 官方文档：
https://docs.anthropic.com/claude-code

Claude Code GitHub 仓库：
https://github.com/anthropics/claude-code

Claude Code Issues（报告问题）：
https://github.com/anthropics/claude-code/issues

CC Switch 工具：
https://github.com/anthropics/claude-code#cc-switch

如果这篇文章对你有帮助，欢迎点赞、收藏、转发！
欢迎关注公粽号FishTech Notes，一块交流使用心得！