本文面向 AI Agent 初学者，系统讲解 Agent Skills 的概念、原理与实战写法，并以一个完整的 Code Review Skill 为例，带你走完「写 Skill → 安装 → 使用 → 发布」的全流程。
读完你会发现：你不是在“写 prompt”，你是在给 Agent 安装一个可复用的“职业技能证书”。🎓
TL;DR（给赶时间的你）⚡
- Agent Skills 是什么：一种开放标准，用一个
SKILL.md把“领域知识 + 工作流 + 可执行脚本”打包成可复用能力。 - 为什么有用：把你反复对 AI 说的那套“正确姿势”固定下来，下次直接用，不再做“重复劳动的搬运工”。
- 怎么运行：靠“渐进式加载”，启动只读 frontmatter（很省 token），命中时再按需加载全文与资源/脚本。
目录🧭
一、概念篇：Agent Skills 是什么
1.1 从一个痛点说起
你有没有遇到过这种情况：每次让 AI 帮你做代码审查，它给的格式都不一样，有时候是流水账，有时候是大段废话，永远不是你想要的那种「按严重程度分级、附上修改建议」的规范报告？
或者每次部署项目，你都要手动告诉 AI「先检查环境变量、再跑单测、再构建镜像」，重复输入同一套上下文，烦不烦？
Agent Skills 就是为了解决这个问题而生的。 ✅
它让你把这些「重复的专业经验」打包成一个可复用的「技能包」，Agent 下次遇到相关任务，直接调用，不用你再重新解释。（是的，你终于可以把“复读机”这个岗位外包给文件系统了。）
1.2 一句话定义
Agent Skills 是一种开放标准，通过
SKILL.md文件将领域知识、工作流程和可执行脚本打包成模块化能力，供 AI Agent 动态加载和使用。
1.3 和几个容易混淆的概念的区别
这是初学者最容易搞混的地方，直接上对比表（把“它到底是什么”一次讲清楚）：📌
| 概念 | 是什么 | 解决什么问题 | 作用范围 |
|---|---|---|---|
| Agent Skills | SKILL.md 文件包 | 封装可复用的工作流和领域知识 | 跨对话、跨会话持久生效 |
| MCP | 连接外部工具的协议 | 让 Agent 能调用外部服务（数据库、API） | 工具层，定义连接方式 |
| Prompt / System Prompt | 一次性指令文本 | 单次任务的临时指导 | 单次对话，不可复用 |
| Custom Instructions | 用户偏好设置 | 定义 Agent 的行为风格和语气 | 全局生效，偏向个性化 |
| LangGraph Skill（框架概念） | Graph 中的一个 Node | 定义 Agent 的处理逻辑单元 | 代码层，开发者使用 |
💡 一个形象的类比：
MCP 是 Agent 的「USB 接口」，让它能插上各种外部工具；
Agent Skills 是 Agent 的「操作手册」，告诉它怎么用这些工具完成特定任务。
两者是互补关系，而不是竞争关系。
1.4 从 Claude 专属到开放标准
timeline
title Agent Skills 发展时间线
2025年10月 : Anthropic 在 Claude Code 内部引入 Skills 概念
2025年12月18日 : Anthropic 将 Agent Skills 发布为开放标准
: agentskills.io 上线
2026年1月 : OpenAI Codex CLI 支持 Skills
: GitHub Copilot 宣布支持
2026年2月 : Cursor、Gemini CLI、Windsurf 等相继跟进
: 支持平台超过 26 个
2026年3月 : OpenClaw（龙虾）等 AI Agent 工具全面兼容
: 社区 Skill 数量突破 5000+
关键结论：这不是 Claude 的私有功能，而是整个 AI Agent 生态的通用标准。 🌍
你写的 Skill，在 Claude Code、OpenClaw、Cursor、GitHub Copilot 里都能用。（一稿多投，但完全不水。）
1.5 当前支持平台全景
graph LR
%% ===== 开放标准（最左）=====
subgraph 开放标准
direction TB
SPEC["🌐 Agent Skills 规范<br/>agentskills.io"]
end
%% ===== 编辑器 / 编程工具 =====
subgraph 编辑器 / 编程工具
direction TB
CC["🤖 Claude Code<br/>参考实现 ✅"]
CUR["⚡ Cursor ✅"]
COP["🐙 GitHub Copilot ✅"]
VSC["💻 VS Code ✅"]
WIN["🌊 Windsurf ⚠️ 部分"]
end
%% ===== AI Agent 平台 =====
subgraph AI Agent 平台
direction TB
OC["🦞 OpenClaw ✅"]
COD["🧠 OpenAI Codex ✅"]
GEM["✨ Gemini CLI ✅"]
AMP["🎯 Amp ✅"]
end
%% ===== 国内生态 =====
subgraph 国内生态
direction TB
YD["🐟 网易有道龙虾 ✅"]
AC["🦀 AutoClaw ✅"]
end
%% ===== 连接关系 =====
SPEC --> CC
SPEC --> CUR
SPEC --> COP
SPEC --> VSC
SPEC --> WIN
SPEC --> OC
SPEC --> COD
SPEC --> GEM
SPEC --> AMP
SPEC --> YD
SPEC --> AC
二、原理篇：它是怎么运行的
2.1 一个 Skill 长什么样
最小化的 Skill 结构非常简单（简单到你甚至可以用它来练习“少即是多”）：🧩
my-skill/
├── SKILL.md # 必须，主入口
├── scripts/ # 可选，可执行脚本
│ └── helper.py
└── resources/ # 可选，参考资料
└── checklist.md
SKILL.md 分为两个部分：
---
name: code-review # 触发命令：/code-review
description: >
对代码进行规范审查，输出结构化报告。
Use when: 用户要求 code review、审查代码、检查代码质量时触发。
---
# Code Review 指令
你是一位资深工程师，请按照以下规范对代码进行审查...
（这里是详细的指令内容）
---之间的部分是 YAML frontmatter，控制触发方式- 下面的 Markdown 正文是 实际指令，Agent 激活后才读取
2.2 核心机制：渐进式加载（Progressive Disclosure）
这是 Agent Skills 最精妙的设计，解决了「Skills 太多会撑爆 context window」的问题。🧠➡️📦
sequenceDiagram
participant U as 用户
participant A as Agent
participant FS as 文件系统
Note over A,FS: 启动阶段（每个 Skill 只消耗 ~100 tokens）
A->>FS: 扫描 skills 目录
FS-->>A: 返回所有 SKILL.md 的 frontmatter（name + description）
Note over A: Agent 建立 Skill 索引，知道「有哪些技能」
Note over U,A: 用户发起请求
U->>A: "帮我 review 这段代码"
A->>A: 匹配 description，命中 code-review Skill
Note over A,FS: 按需加载阶段
A->>FS: bash 读取 code-review/SKILL.md 完整内容
FS-->>A: 返回详细指令（< 5k tokens）
A->>FS: 按需读取 resources/checklist.md
FS-->>A: 返回审查清单
A->>FS: 执行 scripts/format_report.py
FS-->>A: 返回脚本输出结果（代码本身不进 context！）
A->>U: 输出规范化的 Code Review 报告
三级加载模型总结：
| 阶段 | 加载内容 | Token 消耗 | 时机 |
|---|---|---|---|
| 第一级 | frontmatter（name + description） | ~100 tokens/个 | Agent 启动时 |
| 第二级 | SKILL.md 完整指令 | < 5k tokens | Skill 被触发时 |
| 第三级 | resources 文件 / scripts 输出 | 按需 | 指令中引用时 |
💡 这意味着你可以同时安装几十个 Skills，而不用担心 context 爆炸。（你的 token 终于不用为“全量加载”缴税了。）💸
2.3 两种触发方式
flowchart LR
subgraph 手动触发
U1["用户输入 /code-review"] --> S1["直接加载对应 Skill"]
end
subgraph 自动触发
U2["用户输入：帮我审查这段代码"] --> M["Agent 扫描所有 Skill 的 description"]
M --> |"匹配成功"| S2["自动加载 code-review Skill"]
M --> |"无匹配"| D["正常回复，不加载 Skill"]
end
description 字段是自动触发的关键，它相当于 Skill 的「触发词词典」，写得越精准，Agent 越能准确识别何时该用它。
2.4 Skill vs Prompt 的本质区别
graph LR
subgraph "没有 Skill（每次都不一样）"
P1["你：帮我 review 代码"] --> R1["AI：随机格式\n随机深度\n随机风格"]
end
subgraph "有 Skill（稳定可预期）"
P2["你：帮我 review 代码"] --> SK["触发 code-review Skill"]
SK --> R2["AI：按固定模板\n分级输出\n统一标准"]
end
三、实战篇：写一个真实的 Skill
3.1 选题：Code Review Skill
为什么选这个场景？
- 每个开发者都有这个需求
- 没有 Skill 时，AI 的审查结果质量不稳定
- 逻辑清晰，适合展示 Skill 的核心价值
- 可以结合
resources/和scripts/展示完整结构
我们想要实现的效果：
每次让 Agent 做代码审查，自动按以下结构输出：
## Code Review Report
### 🔴 严重问题（必须修复）
### 🟡 一般建议（建议修复）
### 🟢 优化建议（可选）
### ✅ 亮点（做得好的地方）
### 📊 总评分：X/10
3.2 目录结构设计
code-review/
├── SKILL.md # 主指令
├── resources/
│ ├── checklist.md # 审查清单（不同语言/场景的检查项）
│ └── examples/
│ ├── good.py # 好的代码示例（供 AI 参考）
│ └── bad.py # 有问题的代码示例
└── scripts/
└── format_report.py # 格式化最终报告输出
3.3 编写 SKILL.md
---
name: code-review
description: >
对代码进行专业的规范审查，输出结构化分级报告。
Use when: 用户提到 code review、代码审查、审查代码、检查代码、
review this、帮我看下这段代码、代码有没有问题 时自动触发。
invocation:
user-invokable: true # 支持 /code-review 手动触发
model-invokable: true # 支持自动触发
---
# Code Review Skill
你是一位拥有 10 年以上经验的资深软件工程师，专注于代码质量、安全性和可维护性。
## 你的工作流程
1. 首先读取 `resources/checklist.md`，了解本次审查的检查维度
2. 逐条分析用户提交的代码
3. 执行 `scripts/format_report.py` 格式化最终报告
## 审查维度
请从以下维度对代码进行评估：
- **正确性**：逻辑是否正确，边界条件是否处理
- **安全性**：是否存在注入、越权、敏感信息泄露等风险
- **性能**：是否存在明显的性能瓶颈或不必要的资源消耗
- **可读性**：命名是否清晰，注释是否合理
- **可维护性**：耦合度是否合理，是否遵循 SOLID 原则
- **测试覆盖**：是否有测试，测试是否充分
## 输出格式
严格按照以下 Markdown 格式输出，不要偏离：
```markdown
## 📋 Code Review Report
**文件**：{filename}
**语言**：{language}
**审查时间**：{datetime}
---
### 🔴 严重问题（必须修复）
> 影响功能正确性、存在安全漏洞、可能导致生产事故
| # | 位置 | 问题描述 | 修复建议 |
|---|------|---------|---------|
| 1 | Line XX | ... | ... |
### 🟡 一般建议（建议修复）
> 影响代码质量、可维护性，但不影响当前功能
| # | 位置 | 问题描述 | 修复建议 |
|---|------|---------|---------|
### 🟢 优化建议（可选）
> 性能优化、代码简化，锦上添花
| # | 位置 | 建议描述 |
|---|------|---------|
### ✅ 亮点
- 列举代码中做得好的地方，积极反馈
### 📊 综合评分
| 维度 | 评分 | 说明 |
|------|------|------|
| 正确性 | X/10 | |
| 安全性 | X/10 | |
| 性能 | X/10 | |
| 可读性 | X/10 | |
| **综合** | **X/10** | |
```
## 注意事项
- 每条问题必须给出**具体的行号或代码片段**，不允许模糊描述
- 修复建议要给出**可执行的代码示例**，而不仅仅是文字描述
- 语气专业但友善，像资深同事在做 PR review，而不是批评
- 如果代码太长，优先关注核心逻辑，标注「仅审查了核心部分」
3.4 编写 resources/checklist.md
# Code Review 检查清单
## 通用检查项（所有语言）
### 安全性
- [ ] 是否存在 SQL 注入风险
- [ ] 是否存在 XSS 风险（前端代码）
- [ ] 敏感信息（密钥、密码）是否硬编码
- [ ] 是否有适当的输入验证
- [ ] 权限校验是否完整
### 错误处理
- [ ] 异常是否被正确捕获和处理
- [ ] 错误信息是否暴露了敏感细节
- [ ] 是否有兜底处理
### 性能
- [ ] 是否存在 N+1 查询问题
- [ ] 循环内是否有不必要的数据库/API 调用
- [ ] 大数据量处理是否有分页或流式处理
## Python 专项检查
- [ ] 是否使用了类型注解（Type Hints）
- [ ] 是否遵循 PEP 8 规范
- [ ] 是否有不必要的全局变量
- [ ] 上下文管理器（with）是否正确使用
- [ ] f-string 是否优先于 % 格式化
## Java 专项检查
- [ ] 是否存在空指针风险（NPE）
- [ ] 资源是否在 finally 或 try-with-resources 中关闭
- [ ] 集合操作是否线程安全
- [ ] 是否滥用了静态方法
## 并发 / 高并发专项（适用于后端服务）
- [ ] 共享变量是否有适当的同步机制
- [ ] 是否存在死锁风险
- [ ] 连接池配置是否合理
- [ ] 幂等性是否有保证
3.5 编写 scripts/format_report.py
#!/usr/bin/env python3
"""
Code Review 报告格式化脚本
Agent 调用此脚本时，只接收输出结果，脚本本身不进入 context window
"""
import sys
import json
from datetime import datetime
def format_report(review_data: dict) -> str:
"""将 Agent 生成的结构化数据格式化为 Markdown 报告"""
now = datetime.now().strftime("%Y-%m-%d %H:%M")
filename = review_data.get("filename", "未知文件")
language = review_data.get("language", "未知语言")
lines = [
f"## 📋 Code Review Report",
f"",
f"**文件**：`{filename}` ",
f"**语言**：{language} ",
f"**审查时间**：{now} ",
f"",
"---",
"",
]
# 严重问题
critical = review_data.get("critical", [])
lines.append("### 🔴 严重问题（必须修复）")
if critical:
lines.append("| # | 位置 | 问题描述 | 修复建议 |")
lines.append("|---|------|---------|---------|")
for i, item in enumerate(critical, 1):
lines.append(f"| {i} | {item['location']} | {item['issue']} | {item['fix']} |")
else:
lines.append("_无严重问题_ ✅")
lines.append("")
# 一般建议
warnings = review_data.get("warnings", [])
lines.append("### 🟡 一般建议（建议修复）")
if warnings:
lines.append("| # | 位置 | 问题描述 | 修复建议 |")
lines.append("|---|------|---------|---------|")
for i, item in enumerate(warnings, 1):
lines.append(f"| {i} | {item['location']} | {item['issue']} | {item['fix']} |")
else:
lines.append("_无一般问题_ ✅")
lines.append("")
# 综合评分
scores = review_data.get("scores", {})
if scores:
lines.append("### 📊 综合评分")
lines.append("")
lines.append("| 维度 | 评分 |")
lines.append("|------|------|")
for dim, score in scores.items():
lines.append(f"| {dim} | {score}/10 |")
return "\n".join(lines)
if __name__ == "__main__":
# Agent 通过 stdin 传入 JSON 数据
try:
data = json.loads(sys.stdin.read())
print(format_report(data))
except json.JSONDecodeError:
# 如果 Agent 没有传入结构化数据，直接跳过格式化
print("<!-- format_report: no structured data provided, using raw output -->")
3.6 完整目录结构总览
code-review/
├── SKILL.md # ✅ 主指令文件
├── resources/
│ ├── checklist.md # ✅ 审查清单
│ └── examples/
│ ├── good_example.py # ✅ 好的代码示例
│ └── bad_example.py # ✅ 有问题的代码示例
└── scripts/
└── format_report.py # ✅ 报告格式化脚本
四、安装与使用
4.1 安装路径说明
graph TD
Q{"这个 Skill 是给\n谁用的？"}
Q --> |"只给我自己用\n所有项目都能用"| G["全局安装\n~/.claude/skills/code-review/"]
Q --> |"只在当前项目用\n团队共享"| P["项目级安装\n.claude/skills/code-review/"]
Q --> |"OpenClaw / 其他平台"| O["对应平台路径\n~/.openclaw/skills/ 等"]
路径速查表：
| 平台 | 全局路径 | 项目路径 |
|---|---|---|
| Claude Code | ~/.claude/skills/ | .claude/skills/ |
| OpenClaw | ~/.openclaw/skills/ | .openclaw/skills/ |
| Cursor | ~/.cursor/skills/ | .cursor/skills/ |
| GitHub Copilot | ~/.copilot/skills/ | .github/skills/ |
| 通用跨平台 | ~/.agents/skills/ | — |
4.2 在 Claude Code 中安装
方式一：手动安装
# 创建全局 skills 目录（如果不存在）
mkdir -p ~/.claude/skills
# 将你写的 Skill 复制进去
cp -r ./code-review ~/.claude/skills/
# 验证目录结构
ls ~/.claude/skills/code-review/
# 应输出：SKILL.md resources/ scripts/
方式二：从 GitHub 安装社区 Skill
# 使用官方包管理工具
npx skills add anthropics/code-review
# 或安装社区 Skill
npx skills add username/repo-name
方式三：Claude Code 内直接安装
/plugin add /path/to/code-review
4.3 验证 Skill 已加载
安装完成后，在 Claude Code 中输入：
/code-review
如果 Skill 加载成功，Agent 会提示你提交要审查的代码。
没有Skill时效果截图：
有Skill时效果截图：
4.4 实际使用演示
手动触发：
你：/code-review
[提交以下代码]
def get_user(user_id):
query = "SELECT * FROM users WHERE id = " + user_id
return db.execute(query)
自动触发：
你：帮我看下这段代码有没有问题
[粘贴代码]
Agent 会自动识别意图，加载 code-review Skill，输出规范报告。
自动调用 skill 截图：
期望输出示例：
## 📋 Code Review Report
**文件**：get_user.py
**语言**：Python
**审查时间**：2026-04-25 10:30
---
### 🔴 严重问题（必须修复）
| # | 位置 | 问题描述 | 修复建议 |
|---|------|---------|---------|
| 1 | Line 2 | SQL 注入漏洞：直接拼接用户输入到 SQL 语句 | 使用参数化查询：`db.execute("SELECT * FROM users WHERE id = ?", (user_id,))` |
### 🟡 一般建议（建议修复）
| # | 位置 | 问题描述 | 修复建议 |
|---|------|---------|---------|
| 1 | Line 1 | 缺少类型注解 | `def get_user(user_id: int) -> dict:` |
| 2 | Line 1 | 无错误处理，用户不存在时会返回 None | 添加 `if not result: raise UserNotFoundError(user_id)` |
### ✅ 亮点
- 函数命名清晰，职责单一
### 📊 综合评分
| 维度 | 评分 |
|------|------|
| 正确性 | 4/10 |
| 安全性 | 2/10 |
| 可读性 | 7/10 |
| **综合** | **4/10** |
4.5 跨平台使用
同一套 Skill 文件，复制到其他平台对应目录即可。以 OpenClaw 为例：
# 复制到 OpenClaw 的 skills 目录
cp -r ~/.claude/skills/code-review ~/.openclaw/skills/
# 或者使用 skillport 工具统一管理
pip install skillport
skillport add ./code-review
五、进阶与生态
5.1 Skill + MCP 组合使用
单独的 Skill 只能提供「指令和知识」，如果 Skill 需要访问数据库、调用 API 或读取文件系统，就需要配合 MCP。🔌
graph LR
subgraph "code-review Skill"
SK["SKILL.md\n工作流指令"]
CK["checklist.md\n审查清单"]
SC["format_report.py\n格式化脚本"]
end
subgraph "MCP Servers（工具层）"
FS["📁 Filesystem MCP\n读取项目文件"]
GH["🐙 GitHub MCP\n获取 PR 信息"]
DB["🗄️ Database MCP\n查询历史记录"]
end
U["用户：review 这个 PR"] --> SK
SK --> |"需要读取文件"| FS
SK --> |"需要 PR 详情"| GH
SK --> |"查询历史审查记录"| DB
SK --> CK
SK --> SC
在 SKILL.md 中声明允许使用的 MCP 工具：
---
name: code-review
description: 专业代码审查，支持读取本地文件和 GitHub PR
allowed-tools:
- filesystem:read_file
- filesystem:list_directory
- github:get_pull_request
---
5.2 Skill 的自我进化（OpenClaw 特有）
OpenClaw 有一个独特的能力：Agent 可以自己写 Skill 来扩展自己的能力。 （说人话：它会把“这次学到的经验”做成“下次直接用的模板”。）🦞
flowchart TD
A["用户遇到新任务：\n帮我每天备份桌面文档到 Dropbox"]
--> B["Agent 发现没有对应 Skill"]
--> C["Agent 自主编写代码并调试"]
--> D["验证成功"]
--> E["Agent 将成功经验封装成 SKILL.md"]
--> F["新 Skill 持久化保存\n下次同类任务直接复用"]
5.3 发现和安装社区 Skill
官方 Skill 仓库：
# Anthropic 官方 Skills
npx skills add anthropics/skills
# 安装特定 Skill
npx skills add anthropics/pptx # PowerPoint 生成
npx skills add anthropics/pdf # PDF 处理
npx skills add anthropics/xlsx # Excel 处理
社区资源：
| 资源 | 地址 | 说明 |
|---|---|---|
| awesome-agent-skills | github.com/VoltAgent/awesome-agent-skills | 1000+ 社区 Skills |
| agentskills.io | agentskills.io | 官方规范文档 |
| skills.sh | skills.sh | Vercel 维护的包管理器 |
| ClawHub | clawhub.io | OpenClaw 专属 Skill 市场 |
5.4 安全注意事项
⚠️ 重要：Skills 可以执行任意代码，安装前务必做好安全审查。
你是在给 Agent 装技能，不是在给电脑装“惊喜盲盒”。🎁（尽量别惊喜。）
graph TD
IN["准备安装一个 Skill"] --> Q1{"来源是否可信？\n官方 / 知名开源项目"}
Q1 --> |"是"| Q2{"是否包含 scripts/？"}
Q1 --> |"否"| R["❌ 不建议安装\n或在沙箱环境测试"]
Q2 --> |"否"| OK["✅ 可以安装"]
Q2 --> |"是"| Q3{"是否审查过脚本内容？\n确认无恶意代码"}
Q3 --> |"是"| OK2["✅ 可以安装"]
Q3 --> |"否"| R2["⚠️ 先阅读脚本再决定"]
安全检查清单：
- 只安装来自可信来源的 Skill（官方仓库、知名开发者）
- 安装前阅读
scripts/目录下的所有脚本 - 注意 Skill 是否请求了过多的工具权限（
allowed-tools） - 在生产环境使用前，先在隔离环境测试
总结
graph LR
A((Agent Skills))
%% 左边（理论）
A --> B[概念]
A --> C[核心机制]
%% 右边（实践）
A --> D[实战]
A --> E[生态]
A --> F[进阶]
B --> B1[开放标准]
B --> B2[Anthropic]
B --> B3[跨平台]
C --> C1[SKILL.md]
C --> C2[渐进加载]
C --> C3[触发机制]
D --> D1[code-review]
D --> D2[frontmatter]
E --> E1[Claude Code]
E --> E2[Cursor]
F --> F1[MCP 组合]
F --> F2[自进化]
核心记忆点：
- Agent Skills = 给 AI 的「操作手册」，打包专业知识和工作流
- 本质是一个含有
SKILL.md的文件夹，门槛极低 - 渐进式加载保证了 token 效率，可以同时安装几十个
- 这是跨平台开放标准，写一次，处处可用
- Skill 和 MCP 是互补关系：Skill 定义「怎么做」，MCP 提供「工具能力」
配套资源
📎 配套资源
- 本文完整代码：github.com/FelixBitSou…
- Agent Skills 官方规范：agentskills.io
- 社区 Skill 仓库：github.com/VoltAgent/a…
- Anthropic 官方 Skills：github.com/anthropics/…
如果这篇文章对你有帮助，欢迎点赞收藏，也欢迎在评论区分享你自己写的 Skill 🦞
