最近 addyosmani/agent-skills 很火。截至 2026 年 7 月 16 日，GitHub API 显示它已经获得 7.8 万以上 Star。

我一开始以为它只是又一套 Prompt 合集。把仓库拉下来以后，这个判断不太准确：它确实有 24 个独立 Skill，覆盖需求、计划、实现、测试、调试、审查和发布；Codex Plugin Manifest 也真实存在，并且指向仓库根目录的 skills/。

我做的核对很简单，任何人都能复现：

git clone --depth 1 https://github.com/addyosmani/agent-skills.git
cd agent-skills

find skills -mindepth 2 -maxdepth 2 -name SKILL.md | wc -l
# 24

jq -r '.skills' .codex-plugin/plugin.json
# ./skills/

仓库内容没有问题，麻烦出在接入层：Codex、Claude Code 和 Cursor 的安装入口、目录和触发方式并不完全相同。“已经复制文件”和“Agent 在这次任务里真的读取了 Skill”也是两件事。

这篇不逐项翻译 24 个 Skill。我只回答安装后最常遇到的几个问题，并给出一套能验证结果的办法。

先给结论：

  • 只用 Codex 或 Claude Code，优先走各自的原生 Plugin；
  • 多种 Agent 共用一套 Skill，再考虑通用 skills CLI；
  • 老项目先装 3 到 5 个，不要一上来把 24 个全部装进全局目录；
  • 安装后必须做一次有无 Skill 的对照任务，否则很容易把“回答看起来更长”误当成“流程已经生效”。

一、Agent Skill 不是“更长的提示词”

一个 Skill 通常是一个目录，至少包含 SKILL.md：

skills/
└── code-review-and-quality/
    ├── SKILL.md
    └── references/

SKILL.md 的 YAML 头部至少包含名称和描述：

---
name: code-review-and-quality
description: Review code changes before merge and identify correctness, security and maintainability risks.
---

这里最重要的不是正文有多长，而是 description 是否准确。支持 Skill 的 Agent 会先读取名称和描述，任务匹配后才继续加载完整说明。Codex 官方文档把这个过程称为渐进式披露：每次只携带 Skill 的基本信息，真正选中时再读取完整 SKILL.md。

这也解释了为什么不应该把 24 份文档全部粘贴进全局规则。规则适合放长期、简短的约束；Skill 放的是按需触发的完整流程。

仓库里的 debugging-and-error-recovery 是个很直观的例子。我检查了当前版本的正文，它要求 Agent 按以下顺序处理故障：

停止继续加功能
→ 保存报错、日志和复现步骤
→ 稳定复现
→ 定位失败层
→ 缩小到最小案例
→ 修根因
→ 增加防回归测试
→ 做端到端验证

这和一句“请认真调试”不是一回事。前者改变执行顺序，也给出了什么时候可以结束排错的标准。

安装前多看一眼脚本和 Hook

第三方 Skill 也属于供应链依赖，不能因为主体是 Markdown 就跳过检查。

我继续看了当前仓库。它不是纯文档：skills/idea-refine/ 下有 shell 脚本，根目录的 hooks/ 里也有 session-start.sh 等文件。下面这条命令可以把需要重点检查的文件先列出来：

find skills hooks -type f \
  \( -path '*/scripts/*' -o -name '*.sh' -o -name '*.py' -o -name '*.js' \)

这不表示仓库存在恶意行为，只说明安装前应该做正常的代码审查。当前 .codex-plugin/plugin.json 中的 Hooks 配置是空对象；Claude Code 目录则包含自己的 Commands、Agents 和 Hook 文件。不同工具安装后会启用什么，应回到对应 Manifest 和客户端规则核对。

团队使用时，我会再加三条约束：

  • 先安装到测试项目，不直接放进所有项目共用的全局目录；
  • 记录审核过的 commit，升级时先看 diff；
  • API Key 只放环境变量或密钥管理工具，不写入 SKILL.md、Rule、示例日志或对话正文。

二、先选安装方式：跨工具安装，还是工具原生插件

agent-skills 提供两条路线。

路线 A：用通用 skills CLI

先查看仓库里有哪些 Skill：

npx skills add addyosmani/agent-skills --list

只安装需要的 Skill：

npx skills add addyosmani/agent-skills \
  --skill debugging-and-error-recovery \
  --skill code-review-and-quality \
  --skill test-driven-development

这条路线适合同时使用多个 Agent 的开发者。vercel-labs/skills 当前列出了 Codex、Claude Code、Cursor 等多种工具，并区分项目级和用户级安装。

建议先安装 3 到 5 个真实会用到的 Skill，不要因为“一条命令能全装”就把 24 个全部设为全局默认。

路线 B：使用工具自己的插件或目录

如果只使用一种工具，原生方式更容易理解，也更方便排错。下面分别说明。

三、Codex：优先使用原生 Plugin

agent-skills 已经提供 .codex-plugin/plugin.json，可以直接作为 Codex Plugin 安装：

codex plugin marketplace add addyosmani/agent-skills

安装后重启正在运行的 Codex。仓库根目录下的 skills/ 会通过 Plugin Manifest 暴露给 Codex，不需要再复制一份。

这里有一个容易踩到的版本差异：agent-skills 仓库示例写的是通过 @skill-name 调用；当前 Codex 官方文档说明，在 CLI/IDE 中可以运行 /skills，或输入 $ 来提及 Skill，也可以让 Codex 根据 description 自动选择。

因此，不要死记一个触发符号。安装后先运行：

/skills

确认列表里能看到目标 Skill，再按当前客户端界面提供的方式调用。若命令不存在，先检查 Codex 版本和当前使用的是 CLI、IDE 还是桌面端，不要直接判定 Skill 内容有问题。

四、Claude Code：Marketplace 能用，但先处理 Git 协议

仓库提供了 Claude Code Marketplace 安装方式：

/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

如果出现下面这类错误：

git@github.com: Permission denied (publickey)

问题发生在 Git 克隆阶段，还没有进入 Skill 加载阶段。Claude Code 官方文档说明，GitHub 简写默认可能使用 SSH，可以优先设置：

export CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1

然后重新添加 Marketplace。也可以直接使用完整 HTTPS 地址：

/plugin marketplace add https://github.com/addyosmani/agent-skills.git
/plugin install agent-skills@addy-agent-skills

注意：仓库里的 /spec、/plan、/build 等 Slash Command 是 Claude Code 集成的一部分。不要假设这些命令复制到 Codex 或 Cursor 后也会自动存在。

五、Cursor：Skill 和 Rule 必须分开

Cursor 当前同时识别以下项目级目录：

.agents/skills/
.cursor/skills/

用户级目录则包括：

~/.agents/skills/
~/.cursor/skills/

如果希望项目结构更明确，可以把仓库 Skill 同步到 .cursor/skills/：

mkdir -p .cursor/skills
rsync -a /path/to/agent-skills/skills/ .cursor/skills/

而 .cursor/rules/*.mdc 应只保留短规则，例如代码风格、目录约束和“遇到复杂任务先选择合适 Skill”。不要把完整的 SKILL.md 再复制到 Rule 中，否则同一套要求会重复进入上下文，还可能出现两个版本逐渐不一致。

一个够用的目录结构如下：

your-project/
├── .cursor/
│   ├── rules/
│   │   └── project-policy.mdc
│   └── skills/
│       ├── debugging-and-error-recovery/
│       │   └── SKILL.md
│       └── code-review-and-quality/
│           └── SKILL.md
└── src/

六、十分钟确认 Skill 是否真的生效

“目录存在”只能证明安装动作执行过，不能证明 Agent 在当前任务里读了它。我现在更愿意用一个小故障做验收，而不是继续研究安装界面。

第一步：确认发现路径

在工具提供的 Skill 列表中确认目标名称。若列表里没有，先检查目录层级和 SKILL.md 的 YAML 头部。

第二步：设计一个明确匹配的任务

例如验证调试 Skill，可以给一个带具体约束的任务：

这个测试在 CI 中失败但本地通过。请先复现并缩小范围，再修复，并补充防回归测试。开始前说明你准备使用的 Skill。

别选真实生产事故作为第一次测试。找一个可回滚的小项目，准备一条稳定失败的测试，记录未使用 Skill 时的结果，再显式指定 Skill 重跑。

第三步：检查输出证据

一个真正生效的工程 Skill，不应该只把回答写得更规整。以调试为例，至少应看到：

  • 复现命令；
  • 失败范围缩小过程；
  • 根因证据；
  • 最小修复；
  • 防回归测试；
  • 未验证边界。

第四步：做一次有无 Skill 的对照

用同一个小任务分别运行一次，比较有没有稳定的检查步骤、测试证据和停止条件。

例如，面对“CI 失败、本地通过”，没有调试流程时，Agent 很可能直接改超时或重跑次数；加载当前 debugging-and-error-recovery 后，合理的行为应该是先保存 CI 日志，再比较 Node 版本、环境变量、测试顺序和共享状态，最后补一条能复现原问题的测试。

这才是可观察的差异。至于回答里有没有说“我正在使用某某 Skill”，只能作为辅助信号。

七、Skill 没生效，还是 API 没通？

很多排错会把两层问题混在一起。

Skill 层问题

  • Skill 没出现在列表里；
  • SKILL.md 头部格式错误；
  • description 与任务不匹配；
  • Rule 和 Skill 重复或冲突；
  • 把 Claude Code 的 Slash Command 当成所有工具通用能力。

API 层问题

  • 401：Key 无效、请求头错误或读取了错误环境变量；
  • 403：账号、模型或地区权限不满足；
  • 404：Base URL、端点或模型 ID 错误；
  • 429：触发限流、额度不足或并发过高；
  • 5xx：上游、网关或路由暂时异常；
  • /v1/v1：客户端和配置重复追加版本路径。

如果 Agent 已经能看到 Skill，但真正发送请求时报错，就应该转到 API 层排查，而不是反复重装 Skill。

为了避免每篇文章重复贴一遍客户端配置，我把 API 层的检查步骤整理成了几个页面：

这些页面由 AI快站维护，但方法同样适用于其他 OpenAI Compatible 接口。模型 ID、价格和可用状态应以各平台当前控制台和实时接口为准。

八、我建议先装哪几个

如果是已有项目，不建议一开始引入完整流程。先从以下四个开始：

  1. using-agent-skills：让 Agent 先判断该使用哪个流程；
  2. debugging-and-error-recovery：用于复现、定位和防回归；
  3. code-review-and-quality：用于合并前审查；
  4. security-and-hardening：涉及认证、用户输入和外部 API 时使用。

新项目再增加 spec-driven-development、planning-and-task-breakdown 和 test-driven-development。这样更容易判断每个 Skill 带来的变化，也方便出现问题时回滚。

结语

我对 Agent Skills 的看法是：它最有用的地方不是新文件格式，而是把团队原本写在 Wiki、评审清单和老员工经验里的流程，变成 Agent 可以按任务读取的执行单元。

但它也没有神奇到“装完代码质量自动提升”。工具要能发现 Skill，任务描述要能触发它，输出里还得留下测试和验证证据。缺一项，都只能算安装过，不能算真正用起来了。

参考资料

核对日期：2026 年 7 月 16 日。仓库命令和客户端入口可能随版本调整，安装时应以当前官方文档为准。

Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

Cursor Free VIP破解工具：终极免费Pro功能一键解锁指南

还在为Cursor的"试用请求已达上限"而烦恼吗？你是否经常遇到"本机使用过多免费试用账户"的提示？别担心，今天我要介绍的这个开源工具能帮你轻松解决这些问题！Cursor Free VIP是一款功能强大的破解工具，通过智能重置机器ID和修改授权状态，让你免费享受Cursor Pro的全部高级功能。这个工具支持Windows、macOS和Linux三大操作系统，提供多语言界面，操作简单快捷，让AI编

avatar DeepSeek技术社区
cover

AI第一性原理：从一个神经元到ChatGPT的硬核拆解

avatar DeepSeek技术社区

CC-Switch 2026最新完整版 下载+安装+全功能配置教程

供应商名称：自定义备注（如XX中转）Base URL：平台提供地址（结尾带/v1）API Key：中转平台密钥模型名称：填写平台支持代码模型名勾选「适配Claude协议路由」，保存启用。

avatar DeepSeek技术社区