Claude Code 使用必看：1 个配置文件修改，让所有 Skill 在所有项目可用

摘要： Claude Code的/plugin install命令默认将Skill安装为项目级（project scope），导致其仅在当前项目可用，而非预期的全局可用。问题根源在于该命令默认在配置文件中记录"scope": "project"并绑定项目路径，而用户误以为默认是用户级（user scope）。通过CC Switch工具安装的Skill可全局使

江湖人称小鱼哥

2951人浏览 · 2026-01-14 11:27:32

江湖人称小鱼哥 · 2026-01-14 11:27:32 发布

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

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

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

在提示词中明确要求使用某个 skill，但实际执行中并没有触发
输入 /skills 命令，发现列表中根本没有这个 skill
检查 /plugin list，也看不到任何已安装的 skill
切换回原来的项目，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 的实际行为是：

# 你以为的行为
/plugin install skill-name
# → 期望：安装为全局可用插件，所有项目都能使用

# 实际的行为
/plugin install skill-name
# → 实际：在当前 workspace 上注册插件的启用状态
# → 结果：只在当前项目可用，其他项目无法识别

这就是问题的根源：

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

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

会在配置文件中记录 "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。

证据：

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

那为什么会有 Scope 的困惑？

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

# 用户执行
/plugin install book-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：

项目	commit skill 版本	行为
开源项目	v1.0	英文提交信息 + DCO 签名
公司项目	v2.0	中文提交信息 + Jira 单号
个人项目	v1.5	随意格式 + emoji

但这不意味着所有 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 行为）
/plugin install frontend-design
# 结果：✅ 安装成功，但只在当前项目可用

# 测试 3：手动修改配置文件为 user scope
# 编辑 installed_plugins.json，将 scope 改为 user，删除 projectPath
# 结果：✅ 所有项目可用

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

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

核心问题

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

默认使用 project scope
- 用户没有明确指定 scope 时，默认为 project
- 导致 skill 只在安装时的项目中可用
绑定项目路径
- 记录了 projectPath 字段
- 在其他项目中无法识别
没有明确提示
- 安装时没有提示用户选择 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 字段
      }
    ]
  }
}

步骤:

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

验证:

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

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

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

操作步骤：

打开 CC Switch 工具（可视化界面）
添加第三方 skill 仓库
自动安装为 user scope

验证：

/skills
# ✅ 可以识别

优点：

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

缺点：

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

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

如果你确实需要 project scope:

# 在项目 A 中
cd F:\project-a
/plugin install book-cover-generator

# 在项目 B 中
cd F:\project-b
/plugin install book-cover-generator

优点:

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

缺点:

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

快速参考

两套系统对比

特性	CC Switch 工具	/plugin
安装位置	`~/.claude/skills/`	`~/.claude/plugins/`
默认 Scope	User（所有项目可用）	Project（当前项目）
识别命令	`/skills`	`/plugin list`
使用方式	可视化界面添加仓库	命令行安装
跨项目使用	✅ 天然支持	❌ 需要手动修改

使用建议

需求	推荐方案	说明
所有项目都用同一个 skill	CC Switch 工具	通过可视化界面添加仓库
不同项目用不同版本	/plugin（默认行为）	`/plugin install <skill>`
已安装但需要跨项目使用	手动改配置	编辑 `installed_plugins.json`