Claude Code Skills 安装：三种方法 + 常见报错

三种装法先看结论

方法一：npx skills add（跨 agent 安装器）

这个包叫 skills，仓库是 vercel-labs/skills，2026-10-19 的 npm 最新版是 1.7.2， 它同时提供 skills 和 add-skill 两个 bin。它不只会装给 Claude Code， --agent 后能接 80 个 agent 名字（本机 skills add --agent foo 报错时把它们全列了出来， 含 claude-code、cursor、codex、windsurf、gemini-cli 等）。

1. 先预览仓库里有什么，别直接装。 npx -y skills add obra/superpowers --list 会列出 skill 名 + description 后停下，不落盘 （本机实测：退出码 0，22.8 秒，末尾提示「Use --skill <name> to install specific skills」—— 比直接装还慢，因为它仍然要先克隆仓库再逐个读描述）。superpowers 这种仓库有 15 个 skill， 全装进来会明显撑大你的 skill 描述列表（Claude Code 每一轮都要把名字和描述塞进上下文）。
2. 装之前先确认 git 的代理是不是活的（这一步是本页最值钱的，见报错第 1 条）： git config --global --get http.proxy。如果输出一个本地端口，先去浏览器或 Test-NetConnection 127.0.0.1 -Port 7890 确认它在听。
3. 正式装。你要在自己项目里跑，命令是 npx -y skills add obra/superpowers -y --agent claude-code。 本机结果：Cloning repository… → Found 15 skills → Installing all 15 skills → Installed 15 skills，9.4 秒，退出码 0。它还顺手打了一张「安全风险」表（Gen / Socket / Snyk 三家评级）， superpowers 里 using-superpowers 被判 Med Risk，其余 Safe——这张表只是提示，不拦你安装。
4. 装完别只看它说 Done，看目录。项目根目录会多出 .claude/skills/（15 个真目录，不是符号链接）和一个 skills-lock.json。 lock 里每个 skill 记了 source、skillPath 和 computedHash（SKILL.md 的 sha256）， skills experimental_install 就是靠它还原。

它不要求当前目录是个 git 仓库：本机实验目录只有 package.json，没有 .git， 照样按「项目级」装进 .claude/skills/，skills list 里 scope 也显示 project。 想装成全局（所有项目可用）加 -g；想一次喂给多个 agent 用 --agent claude-code cursor 或 --agent '*'。

方法二：手动放进目录（路径以官方文档为准）

官方路径我在 code.claude.com/docs/zh-CN/skills（2026-10-19 抓取）核对过，并且在本机看过实际落点，两者一致：

本机核对：用户级目录 ~/.claude/skills/ 里确实躺着 cloudflare、wrangler、 web-perf 等十几个目录，结构就是「一个目录一个 SKILL.md」。另外本机还有一个 ~/.agents/skills/，是 npx skills 那套自己的规范目录——两个目录不是一回事， 手动装给 Claude Code 用就放 ~/.claude/skills/。

最小可用的 SKILL.md 只有两段：--- 包起来的 YAML frontmatter，和后面的正文。 frontmatter 里 description 决定 Claude 什么时候自动触发它，name 决定 /name 这个命令名。目录名和 name 都行，但别用官方保留的 synced 和 anthropic-skills 命名空间——文档写明这两类不加载。在 Windows 上还有个额外事实： 文档说名字里带 < 这类字符的 skill 不加载，而 < 本来就是 Windows 非法文件名字符， 你根本创建不出来，所以这条限制在 Windows 上碰不到。

手动装的好处是没有任何隐藏状态：不写 lock 文件、不碰任何配置，删目录就是卸载。代价是你得自己管版本， 以后想升级只能重新覆盖。

方法三：插件市场（实测通，但落在另一个目录）

官方文档里，这条路是在会话里敲斜杠命令：/plugin marketplace add anthropics/claude-plugins-official， 再 /plugin install skill-creator@claude-plugins-official。同一条路在命令行里也有等价实现， 我用的是后者（本机能跑，也不依赖会话）：

claude plugin marketplace add anthropics/claude-plugins-official --scope project
claude plugin install skill-creator@claude-plugins-official --scope project -y

实测：加市场 13.6 秒，返回 √ Successfully added marketplace: claude-plugins-official (declared in project settings)； 装插件 1.5 秒，返回 √ Successfully installed plugin: skill-creator@claude-plugins-official (scope: project)； claude plugin list 显示 Status: √ enabled。

关键差别在落点：项目里的 .claude/settings.json 只写了两件事—— enabledPlugins 和 extraKnownMarketplaces；真正的 skill 文件在 ~/.claude/plugins/cache/claude-plugins-official/skill-creator/ea10b213686c/skills/skill-creator/SKILL.md。 所以「插件装了但项目里搜不到 skill 文件」是正常的，别以为没装上。也正因为如此，插件提供的 skill 在会话里叫 /skill-creator:... 这种带前缀的名字，不跟项目 skill 抢短名。

怎么验证真的装上了（4 步，标注来源）

1. 看安装器自己的账本（实测）。npx -y skills list 会按 skill 名列出路径、目标 agent 和来源； 加 --json 拿到机器可读版本，字段是 name / path / scope / agents / source。 本机 15 个全部列出，scope 都是 project。注意：它只证明「安装器认为装上了」。
2. 看磁盘（实测）。.claude/skills/<name>/SKILL.md 在不在， 文件是不是真目录（不是断掉的 symlink）。Windows 上如果你用 --copy 或安装器退化成复制， 目录里是实体文件；如果所在的盘/权限不支持符号链接，这一步最容易出现「列表里有、实际读不到」。
3. 让 Claude Code 自己校验（实测）。claude plugin validate .claude/skills 返回 √ Validation passed、退出码 0。这是官方文档推荐用来定位 frontmatter 坏掉的命令。 但它有两个实测盲区：frontmatter 写成 description: [unclosed 这种坏 YAML，它依然报 passed； 完全没有 frontmatter 时它只给一条 No frontmatter block found 的 warning、退出码仍是 0。 所以「validate 过了」不等于「skill 能被正确触发」。
4. 进会话看（文档，本机未复现）。会话里 /skills 能看到已加载的 skill 列表和来源分组； 是否要重启：文档说不需要——Claude Code 会监听 ~/.claude/skills/、项目 .claude/skills/ 的变化，会话中增删改直接生效。唯一的例外是 skills 顶层目录在会话启动时还不存在，这时候要手动跑一次 /reload-skills；插件里的 skill 改动要 /reload-plugins。 自动触发不到，就先 /name 手动调一次——手动能调、自动不触发，基本就是 description 写得跟你的说法对不上。

三处都失败、但 skills list 有记录时，去翻报错第 5 条：安装器有可能在「全部失败」的情况下 仍然返回 0 并打印 Done。

常见报错：9 条，8 条本机跑出来的

下面每条都标了来源。实测 是我在本机跑出来的原文（可截取关键行，不同版本措辞会变）； 据 issue 是 GitHub issue 里明确记载、我没跑到的。

1. 卡在 Cloning repository：Failed to connect to github.com port 443 via 127.0.0.1

【症状】实测 命令走到 Cloning repository… 转几圈后失败， 报错原文（exit 1，5.0 秒）：

x  Failed to clone repository
|  Failed to clone https://github.com/obra/superpowers.git: Cloning into 'C:\Users\...\Temp\skills-0cSW6M'...
|  fatal: unable to access 'https://github.com/obra/superpowers.git/':
|  Failed to connect to github.com port 443 via 127.0.0.1 after 2055 ms: Could not connect to server
—  Installation failed

【原因】git 的 http.proxy 指着一个已经关掉的本地代理端口（本机是 7890）， 端口没人监听。via 127.0.0.1 这几个字就是证据：它不是「墙」，是「代理地址失效」。 同一台机器上另一轮直连实测拿到的是另一个错法：Recv failure: Connection was reset（23.2 秒）—— 那个才是网络被重置，和本条不是一回事。

【怎么修】git config --global --unset http.proxy 清掉，或改成代理软件当前真正在听的端口 （本机是 127.0.0.1:7897）。改完先用 git ls-remote https://github.com/obra/superpowers.git 确认能通，再重跑安装。别一开始就怀疑安装器。

2. 仓库名写错 → 报的是 Authentication failed，不是 404

【症状】实测 把仓库名敲成不存在的一个，退出码 1，11.7 秒，报错是：

Authentication failed for https://github.com/obra/superpowers-does-not-exist.git.
  - For private repos, ensure you have access
  - Retry with SSH: npx skills add git@github.com:obra/superpowers-does-not-exist.git
  - Check access with: gh auth status -h github.com or ssh -T git@github.com

【原因】私有仓库和「仓库不存在」在 HTTPS 下返回同样的认证失败，安装器把两者归成一条， 于是给了一整套 SSH / gh auth 的建议。

【怎么修】先确认仓库名拼对（owner/repo 两段都要），公开仓库直接开浏览器看一眼 https://github.com/owner/repo 是否 404。不要照着提示去配 SSH——你不是没权限，是名字错了。

3. 只写名字不带 owner → 被当成 git 路径

【症状】实测 npx -y skills add superpowers -y --agent claude-code 退出码 1，2.7 秒：

o  Source: superpowers
x  Failed to clone superpowers: fatal: repository 'superpowers' does not exist

【原因】这个参数位置接受的是包标识或 URL，只写一个词时它没有去技能市场按名字解析，而是直接当 git 地址用。 交互模式下它会给你选，非交互下没有兜底。

【怎么修】写全 owner/repo，或直接贴 GitHub URL。想按关键词找 skill 用 npx skills find <关键词>。

4. 非交互环境直接拒绝安装：stdin is not a TTY

【症状】实测 在脚本、CI、或者被 `npx` 包起来的非终端里跑上面那条命令， 克隆成功、Found 15 skills 之后立刻退出（exit 1，8.6 秒）：

■  Select skills to install
│  Cancelled
—  Installation cancelled
Interactive prompt required but stdin is not a TTY. Nothing was installed.
Use --agent <name> (or --agent '*') and -y to run non-interactively.

【原因】默认流程要问你「装给哪个 agent / 装哪些 skill」，没有 tty 就无法渲染选择器，它选择什么都不装。

【怎么修】显式给全参数：-y --agent claude-code（要挑 skill 再加 --skill a b， 全都要用 --all）。这也是把安装写进 Dockerfile / CI 的唯一可靠姿势。

5. 全部安装失败，退出码却是 0，还打印 Done

【症状】实测 让 .claude 这个名字被一个同名文件占住 （比如某次脚本手滑 echo x > .claude），再装：15 条一模一样的地下，最后照样说 Done，退出码 0：

x  Failed to install 15
|    ✗ brainstorming → Claude Code: ENOTDIR: not a directory, mkdir '...\err-path2\.claude'
|    ✗ diagnosing-superpowers → Claude Code: ENOTDIR: not a directory, mkdir '...\.claude'
    ...（共 15 条）
—  Done!  Review skills before use; they run with full agent permissions.

【原因】逐条失败被吞进了汇总，安装器只用最后那句 Done 收尾，退出码没跟着失败走。 目录里除那个占位文件之外什么都没写，skills-lock.json 也没生成。

【怎么修】别信退出码，信产物：装完必须 skills list + 看目录。CI 里判断成败要 skills list --json 解析条数，或者直接检查 .claude/skills/<name>/SKILL.md 是否存在。 撞上 ENOTDIR 就先确认 .claude 是目录不是文件（Get-Item .claude / ls -ld .claude）。

6. skills update 全绿，进程却崩在退出的那一刻

【症状】实测 npx -y skills update（项目级）已经把活干完了， 紧跟一条 libuv 断言，退出码是 -1073740791（0xC0000409），10.3 秒：

Checking for skill updates…
Updating for: Claude Code
Checking 15 skill(s)…
✓ All project skills are up to date
Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), file src\win\async.c, line 76

【原因】据 vercel-labs/skills#2461（2026-10-11 提出，仍 open）：CLI 在退出前发一个 telemetry 请求， process.exit() 抢在 undici 收尾之前执行，Windows 上就撞 libuv 断言。issue 里 Node 24.19.0 报的是 async.c: line 94，本机 Node 24.15.0 报 line 76，行号漂移但机制一致。issue 还说明： 命令本身是成功的，坏的只是退出状态，但这足以让 CI 任务判红。

【怎么修】看输出判断结果，别只看退出码；确实需要干净退出码的流水线，暂时别把 skills update 放进门禁， 或钉一个未受影响的旧版本。本机 skills add 和 skills list 多轮都没触发这个崩溃，只有 update 复现了。

7. --agent 名字写错：它认识 80 个 agent，不认识你编的那个

【症状】实测 --agent foo-agent，已经装到一半才报错，退出码 1，8.6 秒：

x  Invalid agents: foo-agent
•  Valid agents: aider-desk, amp, antigravity, ..., claude-code, openclaw, cline, ...,
   codex, ..., cursor, ..., gemini-cli, github-copilot, ..., trae, ..., windsurf, zed, ...

【原因】agent 名字是白名单，必须小写连字符，且是它支持的名字（不是 Claude Code 的显示名 "Claude Code"）。

【怎么修】用 claude-code；不确定就 --agent '*' 让它装给所有检测到的 agent， 或先用 -y --agent claude-code 装一个再 skills ls -a claude-code 复查。

8. 插件市场 / 插件名写错：报错在叫你去 update 一个不存在的市场

【症状】实测 claude plugin install skill-creator@no-such-marketplace --scope project -y， 退出码 1：

x  Failed to install plugin "skill-creator@no-such-marketplace":
   Plugin "skill-creator" not found in marketplace "no-such-marketplace".
   Your local copy may be out of date — try `claude plugin marketplace update no-such-marketplace`.

插件名写错（no-such-plugin@claude-plugins-official）时，只报 Plugin "no-such-plugin" not found in marketplace "claude-plugins-official"，不带提示。

【原因】它把「市场不存在」和「市场里没这个插件」压成同一句话，而修法只对后者成立。

【怎么修】先 claude plugin marketplace list（本机一开始是 No marketplaces configured）， 没有就先 claude plugin marketplace add anthropics/claude-plugins-official；市场在了再 claude plugin list / 文档里的 claude plugin validate 确认插件名。只有「市场存在且目录过期」时， update 才是对的修法。

9. 装上了却触发不了：validate 通过 ≠ 能用

【症状】实测 我故意把 frontmatter 写成坏 YAML（description: [unclosed）， claude plugin validate .claude/skills 依然返回 √ Validation passed、退出码 0； 再删掉整段 frontmatter，它也只给一条 No frontmatter block found 的 warning，退出码还是 0。

【原因】据官方文档：frontmatter 的 YAML 解析失败时，skill 主体照样加载，但元数据为空—— 于是 /name 手动调用还能用，Claude 却拿不到 description，永远自动触发不到。 validate 只校验结构，不替你做语义检查。

【怎么修】用 claude --debug 启动会话看解析报错；把 description 改写成「用户会怎么说」的说法 （文档建议把关键词放前面，每条描述组合文本上限 1536 字符）；触发太频繁就把描述写窄，或加 disable-model-invocation: true 改成只能手动调。

还有两条只来自 issue，我没跑出来

据 issue Windows 上没装 git：npx skills add 会甩出 Failed to clone ...: Error: spawn git ENOENT，且只有 vercel、 vercel-labs、heygen-com 三个 owner 走免 git 的快路径，其他 owner 一律要 git。 来源 vercel-labs/skills#1010。 修法：装 Git for Windows，或换到上述 owner 的仓库。

据 issue skills list -g 在 Windows 上很慢： 据 vercel-labs/skills#1389 是 20–25 秒（全局 skill 目录多、大量 junction 时）；本机实测 77.8 秒（退出码 0），比我预期更糟。 所以别在脚本里频繁跑它，验证优先用项目级的 skills list --json。

什么情况下别用安装器

下面几条是我这次实测后确定的「别硬上」：

• 公司网络里 npm 能通、git 不能通。安装器最终是 git clone，git 走不通就是第 1、2 条那种报错。 这时候手动下 zip、把 SKILL.md 放进 .claude/skills/ 更快，也不会有 lock 文件残留。
• 你只需要一个 skill。装一个 15 skill 的大仓库会把 Claude 的 skill 描述列表撑满， 按文档的说法超预算时会开始截断描述，被截断的正是你「用得最少」的那些——但一开始它并不知道你用得少。
• 把安装写进 CI 门禁。本页第 5、6 条说明退出码不可靠：全失败返回 0，全成功可能返回 -1073740791。要门禁就断言产物，别断言退出码。
• 你在 Windows 且路径含空格。本机 Node 装在 E:\Program Files\nodejs（带空格）， skills update 在这个环境下曾长期有 ✗ Failed to update 的静默失败记录 （见 #1457、 #941）。 我用 1.7.2 跑 update 没遇到这一条（遇到的是上面第 6 条的崩溃），但同类环境值得先试一次再写进流程。

一句话结论

证据目录留在 _bench/install-test/：.claude/skills/ 下那 15 个目录是真实装出来的， 里面还有我故意造的 broken-yaml、no-frontmatter、synced 三个测试目录，用来验证第 9 条。 想接着往下看「装哪个」，去 按场景选 skill 的清单； 还分不清 skill 和插件，看 Skills 还是 Plugins。