agent-skills 多 Agent 安装实战：在 Claude Code / Cursor / Gemini / Codex 怎么装、踩过哪些坑

前六天我们一直在讲 agent-skills 干了什么——六阶段流水线、DEFINE 三件套、反合理化机制。理论讲够了，今天落地。我想把 24 个技能装到自己的开发环境里用起来，结果光是”装”这件事就踩了一堆坑。一篇文章讲清楚：怎么装最快、哪些工具装得最干净、为什么单 skill 安装会出诡异问题、为什么 Windows/macOS 上会撞 SSH 报错。

先看路径，再选工具

agent-skills 本身只是一堆 Markdown 文件加 YAML frontmatter，不依赖任何二进制。装在哪、放哪、怎么被发现，完全是消费方工具决定的。我把目前主流的安装路径画成一张决策树：

flowchart TD
    A["想用 agent-skills"] --> B{"你的诉求是什么？"}
    B -->|想快、跨工具|npx["npx skills add
（CLI 通用）"]
    B -->|"深度集成
原生市场"| C{"用哪个工具？"}
    C -->|Claude Code|CC["/plugin marketplace add"]
    C -->|Codex|CX["codex plugin marketplace add"]
    C -->|Antigravity|AG["agy plugin install"]
    B -->|"开发调试 / 改 skill"| GC["git clone + --plugin-dir"]
    npx --> Done["✅ 装完就能用"]
    CC --> Done
    CX --> Done
    AG --> Done
    GC --> Dev["修改后重启生效"]

一句话总结：想快用 npx，想深度集成就用工具自带的插件系统，想改 skill 就 clone 仓库本地指定。

工具支持矩阵

agent-skills 当前覆盖 10 个主流 AI 编码工具。我把每个工具的安装入口、命令、默认发现路径、踩坑点列在一张表里，这是后面所有讨论的基础。

挑几个值得展开的，后面有专门的 Hands-on。

路径一：npx skills add（跨工具通用）

vercel-labs 维护的 skills CLI 是目前最快的安装方式——一个 npx 命令把仓库下下来，自动识别所有 SKILL.md，写入对应工具的默认目录。号称支持 70+ Agent，覆盖了上面表格里几乎所有的工具。

最常用的几条命令：

1
2
3
4
5
6
7
8
9
10
11

# 装全部 24 个技能
npx skills add addyosmani/agent-skills

# 先看看有哪些技能再决定装哪些
npx skills add addyosmani/agent-skills --list

# 只装一个技能
npx skills add addyosmani/agent-skills --skill code-review-and-quality

# 装到指定 Agent（如果不传 -g 会装到所有发现的 Agent）
npx skills add addyosmani/agent-skills -g claude-code

好处：零配置、跨工具、Atomic（一次写入所有目标）。

坑：单 skill 安装只复制 skills/<name>/ 目录，不带仓库根的 references/。这一点有专门一节会讲（#361 portability gap）。

路径二：原生市场（Claude Code / Codex / Antigravity）

如果只用一两个工具，且希望走”正经”的集成路径，就用工具自带的市场命令。

Claude Code

1
2
3
4
5

# 注册市场
/plugin marketplace add addyosmani/agent-skills

# 从市场安装
/plugin install agent-skills@addy-agent-skills

装完之后 8 个 slash 命令直接可用：/spec /plan /build /test /review /code-simplify /webperf /ship。

Codex

1
2
3

# Codex CLI v0.122+
codex plugin marketplace add addyosmani/agent-skills
codex plugin add agent-skills@agent-skills

调用方式不是 slash 命令，而是 @ 触发：@spec-driven-development、@code-review-and-quality。

Antigravity

1

agy plugin install https://github.com/addyosmani/agent-skills.git

Antigravity 自身就是 Gemini CLI 的下一代，注册后会落到全局插件目录 ~/.gemini/antigravity-cli/plugins/agent-skills/。

这三种”原生市场”的好处是：工具本身知道哪些技能兼容、哪些不兼容、哪些命令冲突（Gemini 的 /plan 冲突就是 Antigravity 文档里特别标注的）。npx skills add 不知道这些，所以偶有踩坑。

路径三：本地 clone + 指定插件目录（开发模式）

当你改了某个技能的 SKILL.md，或者想验证改完立即生效，就走开发模式。

1
2
3
4
5
6
7
8
9
10

# 1. 拉代码
git clone https://github.com/addyosmani/agent-skills.git
cd agent-skills

# 2. 切个分支改你想改的 SKILL.md
git checkout -b tweak/tdd-strict
# ... 修改 skills/test-driven-development/SKILL.md ...

# 3. Claude Code 启动时用 --plugin-dir 指定
claude --plugin-dir /path/to/agent-skills

这种模式下，任何 skill 的修改重启会话即生效，不需要重新打包或发版。代价是仓库直接暴露在工作目录里，适合做二次开发或本地调优。

Hands-on：在 Claude Code 装一套

我自己在 macOS 上完整跑过一遍，记录每一步的真实输出。

1
2
3
4
5
6
7
8
9

# 1. 进入 Claude Code
$ claude

# 2. 注册市场
> /plugin marketplace add addyosmani/agent-skills
Adding marketplace addyosmani/agent-skills...
Cloning into '~/.claude/plugins/marketplaces/addy-agent-skills'...
fatal: Could not read from remote repository.
git@github.com: Permission denied (publickey).

报错：git@github.com: Permission denied (publickey)。

这是 Windows/macOS 上第一次用 /plugin marketplace 几乎必撞的坑。原因和解决见后面”SSH Permission denied”一节，先把流程走完。

把 SSH 切到 HTTPS 或者加 key 之后重新跑：

1
2
3
4
5
6
7

> /plugin marketplace add https://github.com/addyosmani/agent-skills.git
Cloning into '~/.claude/plugins/marketplaces/addy-agent-skills'...
✓ Marketplace added

> /plugin install agent-skills@addy-agent-skills
Installing plugin 'agent-skills' from marketplace 'addy-agent-skills'...
✓ Plugin installed (24 skills, 8 commands)

装完之后看下命令列表：

1
2
3
4
5
6
7
8
9

> /help
/spec          spec-driven-development
/plan          planning-and-task-breakdown
/build         incremental-implementation + test-driven-development
/test          test-driven-development
/review        code-review-and-quality
/code-simplify code-simplification
/ship          shipping-and-launch
/webperf       web-performance-auditor

随便挑一个试一下：

1
2
3
4

> /spec
Loading skill: spec-driven-development
Phase 1/4: Goals & Non-goals
What are you building? Who is it for?

正常进入技能流程，说明装成功了。

Hands-on：在 Cursor 装一套

Cursor 的安装路径和 Claude Code 完全不一样。Cursor 没有”市场”概念，技能被发现走 .cursor/skills/，规则走 .cursor/rules/*.mdc——两边不能混着用。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 1. 准备工作目录
mkdir -p .cursor/skills

# 2. 同步上游 skill（不会覆盖你已有的自定义 skill）
rsync -a --ignore-existing /path/to/agent-skills/skills/ .cursor/skills/

# 3. 写一条最小规则，告诉 Cursor "去 skills 里找"
cat > .cursor/rules/agent-skills.mdc <<'EOF'
---
description: Use agent-skills workflows from .cursor/skills
alwaysApply: true
---
Before non-trivial technical work:
1. Route via .cursor/skills/using-agent-skills/SKILL.md.
2. Read and follow the matching skill under .cursor/skills/<name>/SKILL.md.
3. Open reference.md in that folder when the skill links to it.
EOF

验证一下：

1
2
3
4
5
6
7

# 看看装进去了几个
$ ls .cursor/skills/ | wc -l
24

# 跑一个简单的，看 Cursor 会不会自动用 skill
# 在 Cursor Chat 里说："add a feature with tests first"
# （不需要说"请用 test-driven-development"——它会从 description 自动匹配）

Cursor 的坑：

• **不要把整个 SKILL.md 粘贴进 .cursor/rules/**。规则文件应该短（less than 100 行），长流程交给技能。这是 Cursor 官方文档明确反对的反模式。
• 不要维护两份分叉。上游改动后 rsync 同步，不要手改 .cursor/skills/ 里的副本。
• .cursorrules 是遗留方案。新项目用 .cursor/rules/*.mdc。

#361 portability gap：单 skill 安装的坑

这一节单独拎出来讲，因为踩了一次很迷。

如果用 npx skills add addyosmani/agent-skills --skill code-review-and-quality，CLI 只会把 skills/code-review-and-quality/ 这个目录复制到目标工具里。它不会复制仓库根的 references/。

这意味着什么？看 code-review-and-quality 的 SKILL.md：

1

When doing a security review, also load references/security-checklist.md.

references/security-checklist.md 是仓库根共享的清单，单 skill 装完之后，技能内部对它的引用全部失效。这就是 #361 跟踪的 portability gap。

我自己在 Cursor 里复现过：

1
2
3
4
5
6
7

# 装单个
$ npx skills add addyosmani/agent-skills --skill code-review-and-quality

# 跑任务，模型走到 Security 阶段
> /review
Now applying security review...
[ERROR] references/security-checklist.md not found

解决方案有三种，按推荐度排序：

1
2
3
4
5
6
7
8
9
10
11

# 方案 A：全量装（推荐）
npx skills add addyosmani/agent-skills

# 方案 B：clone 仓库，自行 rsync
git clone https://github.com/addyosmani/agent-skills.git
rsync -a /path/to/agent-skills/skills/ .your-target/skills/

# 方案 C：单 skill 安装后，手动补 references
mkdir -p .installed-skill/code-review-and-quality/references
cp /path/to/agent-skills/references/security-checklist.md \
   .installed-skill/code-review-and-quality/references/

经验法则：单 skill 安装只适合”临时尝鲜”。生产环境必须全量装或者 clone，否则技能之间的引用会在你最不希望的时候断掉。

SSH Permission denied（Windows/macOS 通用）

回到上面 Claude Code 装第一步的报错：git@github.com: Permission denied (publickey)。

这是因为 Claude Code 的 /plugin marketplace add 默认用 SSH 协议克隆仓库（git@github.com:addyosmani/agent-skills.git）。如果你本地没有配置 SSH key，或者 key 没加到 GitHub 账户，就直接报这个错。

两种解决办法：

第一，老老实实加 SSH key。

1
2
3
4
5
6

# 生成 key
ssh-keygen -t ed25519 -C "your_email@example.com"

# 复制公钥
cat ~/.ssh/id_ed25519.pub
# 粘贴到 GitHub Settings → SSH and GPG keys → New SSH key

第二，绕过去，强制 HTTPS 克隆。

1
2
3
4
5
6
7
8
9

# 1. 直接用 HTTPS URL
/plugin marketplace add https://github.com/addyosmani/agent-skills.git

# 2. 如果仍然走 SSH（有些工具子进程独立 clone），在 Git 全局配置里劫持一下
git config --global url."https://github.com/".insteadOf git@github.com:

# 这条命令的效果：
# 任何代码里写的 git@github.com:xxx/yyy.git
# 都会被 Git 替换成 https://github.com/xxx/yyy.git

第二条是我自己在 Windows WSL + macOS 上反复测试都有效的方案。它的副作用是：你本地的所有 Git 操作（包括 worktree、submodule）都会被强制走 HTTPS。如果你的 work 流程依赖 SSH 推送（比如要 push 到 private 仓库），那这一条要慎用。

另一种折中方案：把 insteadOf 限定到 Claude Code 插件目录，而不是全局：

1
2

# 只在 Claude Code 插件市场目录下生效
git config --global --add url."https://github.com/".insteadOf git@github.com:

但实际操作时，插件市场的 clone 是在临时目录里进行的，全局配置对临时子进程仍然生效，所以区分这两个场景意义不大。

Windsurf / Copilot 的”老派”装法

不是所有工具都支持 SKILL.md 自动发现。Windsurf 和 GitHub Copilot 的安装路径更”土”——直接复制 SKILL.md 内容到规则文件里。

Windsurf

1
2
3
4
5
6

# 拼出 .windsurfrules（只挑 2-3 个核心技能）
cat /path/to/agent-skills/skills/test-driven-development/SKILL.md > .windsurfrules
echo -e "\n---\n" >> .windsurfrules
cat /path/to/agent-skills/skills/incremental-implementation/SKILL.md >> .windsurfrules
echo -e "\n---\n" >> .windsurfrules
cat /path/to/agent-skills/skills/code-review-and-quality/SKILL.md >> .windsurfrules

Windsurf 没有”按需激活”机制，.windsurfrules 是常驻上下文。所以这里的取舍是：挑 2-3 个你最需要的技能塞进去，而不是全量。

GitHub Copilot

1
2
3
4
5
6
7
8

# 复制技能
mkdir -p .github/skills/test-driven-development
cp /path/to/agent-skills/skills/test-driven-development/SKILL.md \
   .github/skills/test-driven-development/SKILL.md

# 复制 persona（注意 .agent.md 扩展名）
cp /path/to/agent-skills/agents/code-reviewer.md \
   .github/agents/code-reviewer.agent.md

Copilot 的坑：

• **persona 文件必须叫 .agent.md，不能叫 .md**。这一点 VS Code 文档里专门强调过，被坑过的人不少（*.md 会被 Copilot 静默忽略）。
• Copilot skills 支持 .github/skills/、.claude/skills/、.agents/skills/ 三个目录，任何一个都可以，但只有 .github/ 是约定俗成的。
• 同样存在 #361 的单 skill 引用问题。

我的推荐组合

最后讲讲我现在自己用的组合。

主力开发：Claude Code。原因是它有原生的 marketplace 和 plugin 机制，slash 命令和 SKILL.md 联动最顺。8 个命令基本覆盖六阶段所有日常工作。

日常 code review：Cursor。因为 Cursor 对多文件 diff 的 UI 处理比 CLI 强，且 --plugin-dir 可以和 Claude Code 共用一份仓库。

长链路规划：Command Code。/spec-driven-development 走 TUI 触发，Slash 菜单可以浏览所有 24 个技能，适合”我想看看有什么可用”。

Agent 协作：Doubt-driven。涉及不可逆改动时，把 doubt-driven-development 主动拉进 prompt，让其他 persona 一起做对抗性审视。

整套安装在一个下午搞定。如果你只想试一个，建议从 npx skills add addyosmani/agent-skills --skill test-driven-development 起步——TDD 这一件如果真按它要求的那套执行，代码质量提升肉眼可见。

明天我们横向对比一下 agent-skills vs Superpowers vs Matt Pocock 的 skills，看三套流派各自的取舍。

参考资料

• agent-skills README
• Issue #361: Per-skill install portability gap
• docs/cursor-setup.md
• docs/gemini-cli-setup.md
• docs/codex-setup.md
• docs/windsurf-setup.md
• docs/copilot-setup.md
• docs/antigravity-setup.md
• docs/opencode-setup.md
• docs/commandcode-setup.md
• docs/getting-started.md
• vercel-labs/skills CLI
• GitHub: Adding a new SSH key