安装方式参考手册

2026/6/27大约 8 分钟

安装方式参考手册

多路径安装：怎么选、装完怎么验

全书很多仓库会写两种以上安装方式。读法固定为四步：

看「推荐（默认）」 — 只跟这一条走完即可。
「备选」 — 仅在表格里写明的场景再用（例如 CC Switch 用户、只要单体 Skill、官方 Market 找不到包）。
不要两条都跑 — 同一 Plugin 装两遍会占双份描述预算。
装完必做验证 — 见下方「Plugin 标准收尾」。

常见多路径模板（全书统一写法）

单体 Skill — CC Switch vs npx

推荐（CC Switch 用户）：install owner/repo:<目录名> → skills sync（没有 npx 的 --skill 参数）。
备选（终端 / 无 CC Switch）：npx skills add owner/repo --skill <目录名> -g -a claude-code -y。
不要两条都跑

Karpathy — Plugin vs CLAUDE.md

推荐 A（Plugin 全局）：跨项目、User scope 装一次
备选 B（单项目 CLAUDE.md）：只约束当前仓库或 git 共享规则
不要 A+B 双装

UI/UX Pro Max — uipro vs Plugin vs npx/CC Switch

推荐 A（uipro init）：上游标准，含数据脚本与 Python 引擎
备选 B（Plugin）：习惯 /plugin 统一管理
备选 C（npx / CC Switch 仅主 Skill）：不想装 CLI 或用 CC Switch 管 Skill
A / B / C 只选一条；只装主 Skill ui-ux-pro-max，不要 7 个子 Skill 全装

baoyu-skills — npx/CC Switch vs Plugin

推荐（npx / CC Switch 按需装）：只要几个 baoyu-*，控制描述预算
备选（整包 Plugin）：要 /plugin update 一键更新整包
不要双装

官方 Market vs 作者 Market（Claude Code `/plugin`）

	官方 Market	作者 Market
标识	`@claude-plugins-official`	如 `@superpowers-marketplace`、`@baoyu-skills`
谁维护	Anthropic 收录审核	仓库作者自建 catalog
典型命令	`/plugin install superpowers@claude-plugins-official`	先 `/plugin marketplace add obra/superpowers-marketplace`，再 `/plugin install superpowers@superpowers-marketplace`
何时用	Claude Code 默认首选	官方列表里没有该包；或作者文档指定（如 Copilot CLI 常走作者 Market）

Superpowers 特例：两个 Market 装的是同一套 Superpowers，不是两个不同产品。差别只在从哪个目录下载、更新走哪条 /plugin update 链。Claude Code 用户选官方 Market 即可，少一步 marketplace add。

Plugin 标准收尾（装任何 Plugin 后都做）

/reload-plugins
/skills          # 列表里应出现 plugin 内 Skill（可能带 superpowers: 前缀）
/doctor          # dropped 最好为 0

列表仍没有 → 新开一个 Claude Code 会话 再查 /skills。

单体 Skill 标准收尾（npx / CC Switch / git clone 后）

/skills
/<skill-name>    # 手动测一次
/doctor

CC Switch 用户在 install 后额外执行：cc-switch skills sync。

六种安装方式全览

截至 2026 年 6 月，Skill 的安装主要有六种方式。按推荐度排序：

方式一：Plugin Marketplace 官方安装（推荐）

在 Claude Code 对话中：

/plugin install superpowers@claude-plugins-official

适用条件：Skill 已收录到 Anthropic 官方 Plugin Marketplace。这是最安全的方式——经过 Anthropic 人工审核。

安装 Plugin 后，若 Skill 未立即出现，运行 /reload-plugins。

Scope（User / Project） 指 Plugin 启用范围（全局 vs 当前仓库），不是把 Plugin 解压成散落的 ~/.claude/skills/ 文件。Plugin 内 Skill 仍位于 <plugin>/skills/，以 plugin-name:skill-name 命名空间出现。

方式二：社区 Marketplace 安装

如果 Skill 不在官方 Marketplace 中，但作者提供了自己的 Marketplace 地址：

/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

或：

/plugin marketplace add JimLiu/baoyu-skills

添加后可以在 Claude Code 的 /plugin 浏览界面中搜索和安装。

安装时会提示选择 Scope（User / Project）：指 Plugin 启用范围（全局 vs 当前仓库），不是把 Plugin 解压成 ~/.claude/skills/ 下的散落文件。Plugin 内 Skill 仍位于 <plugin>/skills/，以 plugin-name:skill-name 命名。

baoyu-skills 同时支持方式三 npx skills add JimLiu/baoyu-skills（上游 README 推荐的 Quick Install），不必走 Plugin。

方式三：`npx skills add` CLI 安装（跨平台通用）

Vercel Labs 发布的 skills CLI 对接 skills.sh 注册表，支持 20+ Agent：

# 搜索 Skill（交互式或关键词）
npx skills find
npx skills find "code review"

# 安装某个仓库中的特定 Skill
npx skills add mattpocock/skills --skill grill-me

# 安装到全局（所有项目可用）
npx skills add mattpocock/skills --skill grill-me -g

# 安装到特定 Agent
npx skills add vercel-labs/agent-skills --skill react-best-practices -a claude-code -a cursor

# 列出仓库中所有可安装的 Skill
npx skills add mattpocock/skills --list

# 安装仓库中的所有 Skill
npx skills add mattpocock/skills --all

# 更新已安装的 Skill
npx skills update

关键选项：

选项	说明
`--skill <name>`	安装特定 Skill；用 `*` 安装所有
`-g`	安装到全局
`-a <agent>`	指定目标 Agent（`claude-code`、`cursor`、`codex` 等）
`--copy`	复制文件而非 symlink
`-y`	跳过确认提示

技术原理：CLI 先将 Skill 写入 .agents/skills/ 中心目录，再 symlink/copy 到各 Agent 对应路径（Claude Code → ~/.claude/skills/ 等）。

方式四：Git 克隆 + setup 脚本

适用于 gstack 等带安装脚本的仓库：

# gstack 官方推荐
git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
cd ~/.claude/skills/gstack && ./setup

# 通用 git clone（无 setup 脚本的项目）
git clone --single-branch --depth 1 https://github.com/owner/repo.git ~/.claude/skills/my-skill

方式五：CC Switch Deep Link / GUI 安装

CC Switch 桌面版（farion1231/cc-switch）提供 Skills 的 GUI 管理：

点击 Skills 面板 → 浏览 GitHub 仓库 → 一键安装
支持 Deep Link：ccswitch:// 导入 Skill
Skill 存储在 ~/.cc-switch/skills/，默认 symlink 到各 Agent 目录
支持 Dropbox / WebDAV 等云同步

这是图形界面管理方式，适合不熟悉命令行的用户。

方式六：手动创建 SKILL.md

mkdir -p ~/.claude/skills/my-skill
# 编辑 ~/.claude/skills/my-skill/SKILL.md

SKILL.md 文本支持热重载；新创建的 skills 根目录需重启会话才能被 watch。

CC Switch 与 cc-switch-cli 的 Skills 管理

重要区分：CC Switch 常见两种安装物：

项目	说明
farion1231/cc-switch	桌面 GUI + 内置 CLI/TUI（如 v5.8.x，命令同样是 `cc-switch`）
SaladDay/cc-switch-cli	纯 CLI fork；Skills/MCP 子命令与桌面版同名同形

以下 CLI 命令在任一安装方式下均可用（以 cc-switch --version 为准）：

发现与搜索

cc-switch skills discover "code review"    # 别名: search
cc-switch --app claude skills discover "TDD"

安装与列表

SPEC 格式（与 npx 不同）：cc-switch skills install 只接受一个 <SPEC> 参数——Skill 目录名，或完整键 owner/repo:目录名。没有 --skill 选项（那是 npx skills add 的参数）。

首次使用某仓库 — 须先把源仓库加入 SSOT（GUI Skills 面板或 CLI）：

cc-switch skills repos add anthropics/skills     # owner/name 或 GitHub URL
cc-switch skills repos list
cc-switch skills discover frontend-design        # 查目录名（Directory 列）

安装单体 Skill：

cc-switch skills list
cc-switch skills install anthropics/skills:frontend-design -a claude
# 目录名在已启用仓库中唯一时，可简写：cc-switch skills install frontend-design -a claude
cc-switch skills install mattpocock/skills:grill-me -a claude
cc-switch skills uninstall frontend-design
cc-switch skills info frontend-design

收尾 — install 后同步到 Claude Code 目录：

cc-switch skills sync

启用与禁用

cc-switch skills enable <name> --app claude
cc-switch skills disable <name> --app claude

同步到 live 配置

cc-switch skills sync
cc-switch skills sync-method symlink    # symlink | copy | auto
cc-switch skills import-from-apps <path/to/skill-dir>   # 须至少一个目录；可先 scan-unmanaged
cc-switch skills scan-unmanaged         # 扫描 ~/.claude/skills 等 live 目录里未进 SSOT 的 Skill
cc-switch skills repos list             # 管理 Skill 源仓库

CC Switch 桌面版用户：以上操作均可在 GUI 的 Skills 面板完成，无需 CLI。

日常使用流程

安装后验证

/skills          # 列出并开关 Skill（2026 推荐的管理入口）
/doctor          # 查看描述预算、截断/丢弃的 Skill

Bundled skills（/code-review、/debug 等）无需安装即可使用。

刚安装的 Skill 若不在列表中：重启 Claude Code 会话，或 Plugin 安装后运行 /reload-plugins。

触发 Skill

自动触发不需要你做任何操作。比如说"帮我给这个函数写测试"，Claude 自动匹配 test-driven-development 的 description 并加载 TDD 指令。

手动触发：输入 / 选择，或直接 /code-review src/api/routes/users.ts。

安装 Skills 不是越多越好。用 /skills 禁用低频 Skill 是调优描述预算的首选方式（比提高 skillListingBudgetFraction 更省 token）。在 /skills 中 Space 循环 Skill 状态（on / name-only / user-invocable-only / off），Enter 保存到 skillOverrides（通常写入 settings.local.json）。Plugin 内 Skill 不受 skillOverrides 影响。

日常检查：/doctor 或 claude --verbose 看 truncation / dropped 计数。可调 maxSkillDescriptionChars（默认 1536）。

10-15 个核心 Skill 是实战中证明的最佳数量（含 bundled skills 时需更严格控制）。

更新 Skill

# Plugin Marketplace
/plugin update <plugin-name>

# git clone 安装
cd ~/.claude/skills/<skill-name> && git pull

# npx skills
npx skills update
# 或重新安装
npx skills add <repo> --skill <name> -g -y

CC Switch 多 Provider

切换 Provider 后：

Skills 配置不受影响——存在本地文件系统，切换 Provider 只改 API 端点
CC Switch 用户：skills sync 重新同步是好习惯
cc-switch config common set 中的公共配置片段可跨 Provider 共享

常见问题排错

Skill 安装了但 /skills 看不到？

重启会话。Plugin 安装后运行 /reload-plugins。git clone 的新目录需新会话。

Skill 从不自动触发？

检查 description 是否匹配你的话术（触发词放前面）
检查 disable-model-invocation: true
运行 /doctor 看描述是否被 budget 丢弃
YAML frontmatter 格式错误会导致 description 为空（用 claude --debug 看解析错误）

Skill 触发了但输出质量差？

指令要具体。模糊指令不如 checklist 式约束。

CC Switch CLI 中 Skills 列表为空？

cc-switch skills scan-unmanaged -a claude → import-from-apps ~/.claude/skills/<name> -a claude → skills sync（须带目录；项目内 ./.claude/skills/ 不在 scan 范围内）。

Plugin hooks 改了不生效？

SKILL.md 文本热重载，但 Plugin 的 hooks/MCP/agents 需 /reload-plugins。

本章资料来源：Claude Code 官方文档 - Skills、Vercel Labs skills CLI、CC Switch 桌面版 README、cc-switch-cli