agent-skills 详解：给 AI Agent 的可复用技能库
让 AI 助手稳定输出高质量的代码评审、PR 描述、发布说明，靠反复口头叮嘱是不行的——上下文一长就忘。Google Chrome 团队工程师 Addy Osmani 开源的 addyosmani/agent-skills（agent-skills）提供了另一种做法：把某项任务的"专家做法"写成结构化技能文件，Agent 按需装载，如同给 AI 装上一块块"专业插件"。本文从技能机制、库内容、使用方法到自建技能，完整拆解。
1、项目概述
agent-skills 定位为"AI Agent 技能的精选集合与参考实现"，作者 Addy Osmani 是 Chrome 团队知名工程师、《Learning Patterns》作者。项目与 Anthropic 推动的 Agent Skills 生态同向：技能是带元数据的文件夹（说明 + 资源 + 脚本），Agent 判断任务相关时自动读取，无关时不占上下文。
基本形态与生态：
- 形态：多个独立技能目录，每个含 SKILL.md 及可选脚本/模板资源
- 装载：兼容 Claude Skills 目录约定，可被 Claude Code 等助手加载
- 内容：代码评审、PR 生成、发布说明、前端性能、写作等工程技能
- 协议为 MIT，可自由取用与二开
2、技能机制：SKILL.md 与渐进披露
技能机制的核心是"渐进披露"（progressive disclosure）：Agent 先只读技能的简短元数据，判断当前任务是否需要；需要时才加载全文与资源，避免上下文被撑爆。
// 技能的标准结构
my-skill/
├── SKILL.md # 入口：name、description、何时使用
├── reference.md # 深度参考：详细规则、清单（按需加载）
└── scripts/
└── check.sh # 可执行脚本：Agent 可直接调用
// SKILL.md 头部元数据（frontmatter）
---
name: code-review
description: 评审变更代码的安全、性能与可维护性问题
---机制要点：
1. description 是触发开关：写得越准，自动装载越可靠
2. 正文与 reference 分层：常用规则放正文，长清单放深层文件
3. 脚本可执行：技能不只是提示词，还能带可运行的工具
4. 整个技能进 Git：评审、版本化与团队共享一条龙
3、库内技能一览
仓库按工程场景收录多个即用技能，覆盖开发工作流的高频环节。
代表性技能：
- code-review：按安全/性能/可维护性分层评审变更，输出结构化意见
- pr-description：根据 diff 自动生成规范化的 PR 描述
- release-notes：从提交历史提炼面向用户的发布说明
- frontend-performance：前端性能审查清单与优化建议
- technical-writing：技术写作规范，收紧措辞与结构
内容要点：
1. 技能均遵循同一结构约定，复制即可改造
2. 评审类技能输出格式固定，便于接入流水线
3. 写作类技能聚焦删减与具体化，与 Addy 的写作理念一致
4、安装与使用
技能为纯文本目录，放入助手的技能路径即生效，无编译无依赖。
git clone https://github.com/addyosmani/agent-skills.git
# 个人级安装（Claude Code 约定路径）
cp -r agent-skills/code-review ~/.claude/skills/
# 项目级安装（随仓库共享给全组）
cp -r agent-skills/pr-description .claude/skills/
# 验证：直接对话触发
> 帮我评审这个 PR 的变更 # 自动装载 code-review 技能使用要点：
1. 个人级放 ~/.claude/skills，团队级放项目内 .claude/skills
2. description 触发不灵时，在对话里点名技能名强制加载
3. 非 Claude 助手可将 SKILL.md 内容整体并入系统提示词
4. 技能更新走 git pull，团队同步零成本
5、自建技能：从复制到创造
库的价值一半在即用，一半在范式——照结构写自己的技能，才是正确姿势。
// 1. 新建目录与入口文件
mkdir -p my-team-skills/api-design && cd my-team-skills/api-design
// 2. SKILL.md 写清触发与规则
---
name: api-design
description: 设计 REST 接口时检查命名、分页、错误码规范
---
# API 设计规范
- 资源名用复数名词，动作走子资源或方法语义
- 列表接口必须分页，默认 page_size=20
- 错误码统一 envelope：{code, message, request_id}
// 3. 放入技能目录即完成
cp -r ../api-design ~/.claude/skills/自建要点：
1. 一个技能一个职责，命名与 description 对齐触发场景
2. 规则写成可判定的条目，正反例比抽象描述有效
3. 内部规范（接口、文案、发布）是最值得优先技能化的资产
6、典型应用场景
凡是"每次都要重复交代"的工作约定，都适合技能化。
常见场景：
- 代码评审自动化：PR 流水线调用评审技能，先出第一轮意见
- 文档一致性：发布说明、变更日志按统一模板生成
- 新人上手：把团队规范技能化，新人 Agent 与老成员同标准
- 个人工作流：个人写作、复盘模板随身携带跨项目复用
使用提醒：
1. 技能是"能力插件"不是"知识库"，长文档走 RAG 更合适
2. 装载数量克制，几十个技能会稀释触发准确率
3. 定期清理低频技能，保持库的信号密度
7、定位对比：经验沉淀方案三选一
把 agent-skills、CLAUDE.md 项目说明与示例微调放在一张桌上，各自的位置清晰起来。
三者对比：
- agent-skills：按需装载、可带脚本、生态标准结构，团队共享首选
- CLAUDE.md：项目级常驻说明，简单直接，但全程占上下文
- 示例微调：风格内化最深，但成本高、迭代慢
选型建议：
1. 项目固定约定（构建命令、目录规范）→ CLAUDE.md
2. 跨项目可复用的工作方法 → 技能包
3. 大量历史优质产出、追求模型原生风格 → 微调
4. 组合玩法：CLAUDE.md 管常驻，技能包管专项，微调管风格
8、总结
agent-skills 是 Addy Osmani 维护的 Agent 技能精选库：以 SKILL.md 元数据 + 渐进披露为机制，把代码评审、PR 描述、发布说明、前端性能、技术写作等专家流程变成可装载的能力插件；纯文本 + 可选脚本，MIT 协议，个人级与项目级两种安装路径，clone 即用。它示范了"提示词工程 → 技能工程"的演进路径：约定成结构、经验成资产。
使用边界：技能是"能力插件"不是"知识库"，长文档走 RAG 更合适；装载数量需克制，几十个技能会稀释触发准确率；description 措辞决定自动触发的可靠性，需要反复打磨。团队内部规范可按同款结构写成私有技能，随仓库版本化共享。
