你会遇到什么
你的 AI 写代码很快，但经常「上来就写」：没有规格、没有计划、改完不测试。你想让它像资深工程师一样按流程走——先想清楚需求、拆成小任务、一步步实现、测试通过再合并。Agent Skills 就是装进 AI 的工程流程技能包：24 个技能 + 8 个斜杠命令，覆盖定义→规划→构建→测试→审查→上线全流程。
本文路径：快速修复（30 秒一段命令）→ 一步步来（可跳读）→ 怎么确认修好了（成功判据）。赶时间直接跳到「快速修复」。
为什么会这样
AI 默认只执行「你给的一句话」，不会自己走工程流程。Agent Skills 的做法是给 AI 一份「干活手册」：每个技能是一个 SKILL.md 目录（共 24 个），Claude Code 这类 Agent 会按任务主题自动装载对应技能，也可以用斜杠命令手动触发整条流程。它不改 AI 本身，只是往技能目录里放东西（~/.claude/skills/agent-skills/ 或项目 .claude/skills/），无 CLI 二进制、无后台进程。
快速修复（不想看讲解，直接跑）
下面这条命令先试官方 skills CLI，GitHub 慢装不上时自动退回 codeload 镜像手工复制：
npx -y skills add addyosmani/agent-skills --yes --global 2>/dev/null || (curl -sL https://codeload.github.com/addyosmani/agent-skills/tar.gz/refs/tags/0.6.7 | tar xz && cp -r agent-skills-0.6.7/skills ~/.claude/skills/agent-skills)
预期输出: 技能就位，共 24 个（注意两种方式布局不同：方式 A 平铺为 ~/.claude/skills/<技能名>/，方式 B 带中间层 ~/.claude/skills/agent-skills/——Claude Code 两种布局都读取）
一步步来
第 1 步：装技能包（国内优先手工复制）
为什么有两种方式：方式 A 是官方推荐的 skills CLI（npx -y skills add ...），支持 70+ agent 自动放对位置；但它在 GitHub 拉仓库，国内经常卡住。方式 B 从 codeload 直接下 tarball，本市场实测可达，纯目录复制、不需要 Node。注意两种方式的落盘布局不同：方式 A（2026-08-30 隔离实测）把 24 个技能平铺写入 ~/.claude/skills/<技能名>/，没有中间层；方式 B 复制后是 ~/.claude/skills/agent-skills/<技能名>/，带中间层。Claude Code 对两种布局都支持，但清点与卸载命令要按安装方式区分。 方式 B（国内稳，本市场实测）：
curl -sL https://codeload.github.com/addyosmani/agent-skills/tar.gz/refs/tags/0.6.7 | tar xz
cp -r agent-skills-0.6.7/skills ~/.claude/skills/agent-skills
预期输出: 无报错；~/.claude/skills/agent-skills/ 下出现 24 个技能目录
装好确认（按你的安装方式选一条）：
# 方式 A（平铺）：单独装本包时 ~/.claude/skills/ 下 24 个技能目录
ls ~/.claude/skills | wc -l
# 方式 B（中间层）：
ls ~/.claude/skills/agent-skills | wc -l
预期输出: 24
卡住怎么办：
- codeload 下载失败 → 换网络（校园网/代理切换）重试；或走方式 A skills CLI（
npx -y skills add addyosmani/agent-skills --yes --global）； - 技能没生效 → 确认复制到了 Agent 实际读取的技能目录（Claude Code 是 ~/.claude/skills/，其他 Agent 看各自约定）。
第 2 步：用斜杠命令触发工作流
为什么用斜杠命令：斜杠命令是生命周期入口——/spec 需求→规格（Spec before code）、/plan 规格→原子任务、/build 增量实现（/build auto 一键规划+实现）、/test 测试即证据、/review 合并前审查、/ship 上线。
/spec # 需求→规格（Spec before code）
/plan # 规格→原子任务
/build # 增量实现（/build auto 一键规划+实现）
/test # 测试即证据
/review # 合并前审查
/ship # 上线
预期输出: 对应工作流激活（自动装载相关技能）
装好确认：
- 斜杠命令能唤起对应工作流（Agent 上下文出现技能提示）。
卡住怎么办：
- 命令不存在 → 确认技能目录已就位（第 1 步）；Claude Code 需重启会话让技能目录生效。
第 3 步：技能自动激活（无需手动命令）
讲解：设计 API 时自动激活 api-and-interface-design；改 UI 时激活 frontend-ui-engineering 等。这是「按任务自动装配」机制——技能不依赖手动触发。
# 设计 API 时自动激活 api-and-interface-design；改 UI 时激活 frontend-ui-engineering 等
预期输出: agent 上下文自动注入对应技能
装好确认：
- 相关任务提示里出现技能引用。
卡住怎么办：
- 没自动激活 → 检查技能目录命名与 SKILL.md 格式是否符合 Agent 约定（各 Agent 略有差异）。
怎么确认修好了
- 技能计数 24：方式 A 平铺布局用
ls ~/.claude/skills | wc -l（单独装本包时），方式 B 中间层布局用ls ~/.claude/skills/agent-skills | wc -l； - 新开一个 Claude Code 会话输入
/spec，AI 按规格流程响应，而不是直接开写； - 相关任务提示里出现技能引用（自动激活生效）。
其它环境的表现（常见变体）
- 其他 Agent（Cursor/Codex 等）：skills CLI 支持 70+ agent，方式 A 安装会自动放对位置；手工复制要查各自技能目录约定；
- Node 环境：方式 B 不需要 Node；方式 A 需要 Node >= 18；
- 只想装到当前项目：复制目标从
~/.claude/skills/改成项目内.claude/skills/； - 与 superpowers / skilldock 共存：技能目录写面，与 CLI 工具不重叠；superpowers 与 agent-skills 目录名不同，互不覆盖，都放
~/.claude/skills/下并存；skilldock 可能冲突（推断，未实测）； - 不想用了：按安装方式卸载，见「卸载与清理」节——方式 B 删目录、方式 A 用
npx -y skills remove（只删目录会留下 CLI 登记）。
日常使用
启动与入口
无需启动——技能由 Agent 按任务主题自动装载。手动入口是斜杠命令（第 2 步）和技能目录本身。
常用操作
操作 1：确认技能数量（按安装方式选命令）
# 方式 A（平铺）
ls ~/.claude/skills | wc -l
# 方式 B（中间层）
ls ~/.claude/skills/agent-skills | wc -l预期输出: 24（单独装本包时）
操作 2：用斜杠命令触发工作流
/spec # 需求→规格（Spec before code）
/plan # 规格→原子任务
/build # 增量实现（/build auto 一键规划+实现）
/test # 测试即证据
/review # 合并前审查
/ship # 上线预期输出: 对应工作流激活（自动装载相关技能）
操作 3：更新到最新版（重新下载覆盖）
curl -sL https://codeload.github.com/addyosmani/agent-skills/tar.gz/refs/tags/0.6.7 | tar xz
cp -r agent-skills-0.6.7/skills ~/.claude/skills/agent-skills预期输出: 无报错；技能目录刷新（24 个技能目录）
数据与目录
- 技能目录：
~/.claude/skills/agent-skills/（方式 B）或~/.claude/skills/<技能名>/（方式 A，平铺）；无配置文件、无后台进程。
卸载与清理
note: 纯目录复制——按安装方式删对应布局即零残留；用 skills CLI 装的必须走 CLI 卸载，只删目录会留登记
# 方式 A（skills CLI 安装）：从 CLI 卸载
npx -y skills remove addyosmani/agent-skills
# 方式 B（手工复制）：删目录
rm -rf ~/.claude/skills/agent-skills
# 验证（两种方式通用）
test ! -d ~/.claude/skills/agent-skills && echo "agent-skills removed: OK"预期输出: agent-skills removed: OK
手工检查清单（其他环境）：
- 项目级
.claude/skills/agent-skills（装到项目里的话）； - 其他 Agent 的技能目录（手工复制过的话，按各 Agent 约定清理）。
依赖警告
- 版本：
[0.6.7, 0.6.7]锁定（收录结构确认版本）。 - 环境：方式 A 需要 Node >= 18（skills CLI）；方式 B 无运行时依赖（纯目录复制）。
- 网络：GitHub clone 慢（实测），codeload tarball 可达（实测）。
- 写面：方式 B
~/.claude/skills/agent-skills/，方式 A 平铺~/.claude/skills/<技能名>/（两者都与 superpowers 同面，装多个技能包注意目录规划）。
FAQ（常见问题）
- 问：装完没生效？答：确认技能目录就位（ls 数 24），Claude Code 需重启会话；其他 Agent 看各自技能目录约定。
- 问：方式 A 和方式 B 选哪个？答：官方推荐 A（skills CLI，70+ agent 兼容）；国内 GitHub 慢时 B（codeload tarball，本环境结构确认）更稳。
- 问：和 superpowers 一起装会覆盖吗？答：目录名不同（agent-skills vs superpowers），互不覆盖；都放 ~/.claude/skills/ 下并存。
- 问：方式 A 和方式 B 装出来的布局怎么不一样？答：官方 skills CLI 平铺（~/.claude/skills/<技能名>/），手工复制带中间层（~/.claude/skills/agent-skills/）——2026-08-30 隔离实测确认，Claude Code 两种布局都读取；清点/卸载按对应方式操作。
- 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口；项目自身问题请向作者仓库反馈。
验证证据
本站实测记录（2026-08-28）
- 未实测：斜杠命令与自动激活（需 Claude Code 登录环境）。
引用：agent-skills · 验证于 2026-08-28 · v0.6.7~0.6.7
相关问题（问题域）
出问题了？排障方案
排障手册：agent-skills
症状 → 原因 → 解法 → 验证证据 四段结构。
素材来源：维护者 检索素材（CSDN 完整教程/安装问答 2026-08）+ 本市场实测（2026-08-28 隔离 HOME 双路径验证）。
采集纪律：零账号匿名检索；未碰 GitHub。check-words HARD 0。
基本信息
- 条目名称：agent-skills（addyosmani/agent-skills，MIT，v0.6.7 收录；24 技能 + 8 斜杠命令）
- 求助信号：help=242 / recent3m=210 / trend=up（demand 基线 demand-signal-20260828，全库最高档）
- 角色：anchor；分类：skills
- 本市场安装路径：方式 A
npx -y skills add addyosmani/agent-skills --yes --global（官方 CLI，依赖 GitHub 直连 clone，国内网络失败时用方式 B）；方式 B codeload tarball 手工复制（国内推荐，实测可行） - 命令名：无 CLI 二进制（技能包 = 目录复制到 agent 技能目录）；skills CLI 仅安装器
- 写面：~/.claude/skills 或项目 .claude/skills（与 superpowers 同面，共装注意目录隔离）
症状 → 原因 → 解法 → 验证证据
1. 官方 CLI 安装失败：GitHub clone 被重置/卡死（国内高频）
症状
npx -y skills add addyosmani/agent-skills --yes --global 卡在 Cloning repository… 后报 fatal: unable to access ... Connection reset by peer / Installation failed。
原因
skills CLI 安装流程依赖 git clone https://github.com/addyosmani/agent-skills.git（直连）；国内出口到 GitHub 直连不稳定（本市场连通性基线：GitHub 直连慢/被重置）。注意：CLI 失败时 exit 码仍为 0，只看命令返回值会误判成功。
解法
- 方式 B（国内推荐，实测可行）：codeload tarball 手工复制——
curl -sL https://gh-proxy.com/https://codeload.github.com/addyosmani/agent-skills/tar.gz/refs/tags/0.6.7 | tar xz，再cp -r agent-skills-0.6.7/skills ~/.claude/skills/agent-skills（0.6.7 为当前收录版本，升级时换 tag）。 - 或给 CLI 装代理环境变量（git 走代理）后重试方式 A。
- 判断成功看输出（24 技能目录就位）而不是 exit 码。
验证证据
本站实测记录（2026-08-28）
2. 安装失败排查：Node 版本 / pnpm / npm 缓存
症状
skills CLI 或安装过程报 Node 版本不支持、pnpm 相关错误、或 npx 下载卡住/失败。
原因
CLI 需要 Node >= 18（本环境 v22.22.1 实测可用）；npm 官方 registry 国内直连不稳；缓存损坏/权限问题会中断 npx 下载。
解法
- 确认版本：
node --version（<18 用 nvm 升级）。 - registry 换国内镜像：
npm_config_registry=https://registry.npmmirror.com npx -y skills ...（本环境实测 npmmirror PONG 0.32s）。 - 清缓存重试：
npm cache clean --force或换隔离 HOME。
验证证据
- 本市场实测（2026-08-28）：npmmirror registry 下 npx 下载 skills CLI 正常；Node v22.22.1 满足要求。
3. 同名项目污染：pip 装到 ivanzwb / 国外多个同名 repo
症状
按搜索资料执行 pip install agent-skills 装到无关同名项目；或 clone 到 jdrhyne/tristanmanchester/AkshitIreddy/mikeng-io/callstackincubator 等同名仓库，命令/产物对不上。
原因
PyPI 存在 ivanzwb 同名包（CSDN 案例）；GitHub 存在 5 个以上同名 repo（国外信号）；正确仓库 = addyosmani/agent-skills（manifest 签名），无 pip 分发，安装路径只有 npx/codeload。
解法
- 认准仓库与安装路径：
npx skills add addyosmani/agent-skills或 codeloadaddyosmani/agent-skillstag tarball；不要 pip install。 - 已装错时卸载 pip 包并清理对应技能目录（~/.claude/skills 下非本条目目录）。
验证证据
- 素材引用：CSDN 教程（ivanzwb 同名包案例）+ 国外同名 repo 清单（L32 信号）；正确仓库签名见 manifest（站内文档）。
4. 装完看不到技能 / document-skills 安装问答
症状
按教程装完（/plugin install 流程或方式 B），在 agent 里看不到技能；或 document-skills 子集安装后无效果。
原因
技能包本质是目录复制（无二进制）：装错目录、未完全退出重启 agent、或复制时权限/路径不对都会「装完看不见」；document-skills 属同一技能集子集，问题同源（网络/权限/版本不兼容是常见失败面，CSDN 安装问答）。
解法
- 核对技能目录：
ls ~/.claude/skills/agent-skills（应 24 目录，每个含 SKILL.md）。 - 完全退出并重启 agent 会话再试（技能在启动时扫描）。
- 权限问题：确认目标目录可写；版本问题：确认 tag 与收录版本（0.6.7）一致。
验证证据
- 本市场实测（2026-08-28）：方式 B 复制后目标目录 24 目录 + 24 个 SKILL.md；重启扫描行为为通用机制，未在真实 agent 环境复测——如实标注。
未能实测项（如实标注）
- 真实 Claude Code/Cursor/Codex 环境加载 24 技能（需对应 IDE/账号）；document-skills 子集单独安装；--list 浏览模式；全部 24 技能逐项验证；Windows/macOS 环境。
所属组合包 （1）
combo-env-init— Agent 开发环境一键初始化
矩阵暂无该工具对子。