Agent Skills 从入门到精通 —— 从概念到实战，打造你的第一个 AI 技能包

Agent Skills（智能体技能）是 Anthropic 于 2025 年 10 月推出、同年 12 月作为开放标准发布在 agentskills.io 的一项技术。截至 2026 年，它已被 30+ 工具平台采用，社区注册表超过 70,000 个 Skills。本文将带你从零开始，一步步掌握 Skills 的核心概念与实战编写技巧。

一、什么是 Agent Skill？

用一个比喻来开场：

Agent Skill = AI 的”入职手册 + 工具箱”

假设你新招了一位非常聪明的实习生（AI Agent）。他很聪明，但对你公司的流程、规范、工具链一无所知。每次你都要口头交代一遍：”先这样，再那样，注意 XXX，别忘了 YYY”——这就是 Prompt。

MCP 相当于给这个实习生配了工卡和钥匙——让他能进数据库、调 API、读文件。但他依然不知道该怎么做。

Skill 是什么？是你给他写的一份入职手册。手册里说清楚了：

• 遇到什么场景该做什么（触发条件）
• 具体怎么做，分几步（工作流程）
• 有哪些注意事项（最佳实践）
• 工具箱里有什么脚本可以用（可执行资源）

更棒的是——这份手册写完一次，就能在任何支持 Skills 的 AI 工具中复用（Claude Code、Cursor、VS Code、GitHub Copilot 等 30+ 平台）。

核心设计：渐进式披露（Progressive Disclosure）

Skills 最精妙的设计在于分层加载，极致节省 AI 的上下文窗口（也就是你的 token 费用）：

graph TB
    subgraph "L1 发现层 - 启动时自动加载"
        A["name + description<br/>~100 tokens/Skill"]
    end
    subgraph "L2 激活层 - 任务匹配时加载"
        B["SKILL.md 正文<br/>建议 <5000 tokens"]
    end
    subgraph "L3 穿透层 - 执行时按需加载"
        C["scripts/ + references/<br/>理论上无上限"]
    end

    A -->|"description 匹配用户意图"| B
    B -->|"指令中引用时才读取"| C

    style A fill:#e1f5fe,stroke:#0288d1
    style B fill:#fff3e0,stroke:#f57c00
    style C fill:#e8f5e9,stroke:#388e3c

这意味着：即使你安装了 50 个 Skills，AI 启动时也只多花 ~5000 tokens（50 × 100），相当于一段简短对话的开销。

---

二、Skill vs Function Call vs MCP：三者的关系

这是一个经常被问到的问题。我们通过一个厨房做饭的比喻来理解：

概念	比喻	定位	一句话
Function Call	切菜、开火、倒油（单个动作）	模型调用单个原子操作	“执行这个函数”
MCP	厨房（提供食材、锅具、炉灶）	AI 连接外部系统的协议	“连上那个数据库”
Skill	菜谱（教你一步步做出成品菜）	可复用的任务流程 + 规范	“教你按这个流程做”

用一张表看清区别

维度	Function Call	MCP	Agent Skill
解决的问题	单次函数调用	“能不能连上”	“怎么做”
形态	API 定义（JSON Schema）	需运行 MCP Server	静态文件夹（Markdown + 脚本）
跨工具复用	❌ 厂商锁定	✅ 标准协议	✅ 开放标准
Token 开销	每次调用都在上下文	启动时全量加载（可达 26K+ tokens）	启动时 ~100 tokens，按需加载
包含工作流	❌	❌	✅
运维成本	低	高（需开发/部署 Server）	极低（就是 Markdown 文件）

三者如何协同工作？

最佳实践是三层协同：

graph LR
    A["🎯 Skill<br/>（怎么做事——流程+规范）"] --> B["🔧 MCP Tools<br/>（原子操作——连外部系统）"]
    B --> C["🖥 MCP Server<br/>（后端系统+安全管控）"]

    style A fill:#ffccbc,stroke:#e64a19
    style B fill:#b3e5fc,stroke:#01579b
    style C fill:#c8e6c9,stroke:#2e7d32

一个真实例子——“生成周报”任务：

• MCP：连接 Jira（拉取本周任务）、连接 Git（拉取提交记录）
• Skill：定义了周报模板格式、需要汇总的维度、发送时机、发送对象
• Function Call：底层调用 jira.search_issues()、git.log() 等具体操作

简单来说：MCP 负责”连接数据”，Skill 负责”处理数据”，Function Call 负责”执行操作”。

---

三、深入理解：为什么 Skills 在 2025-2026 年爆发？

1. 解决真实痛点：告别”每次重写 Prompt”

在此之前，AI 协作最大的痛点是什么？每次开新对话，你都要把上下文重新说一遍。

有了 Skill，你的流程规范、代码风格偏好、最佳实践被固化为文件，AI 每次对话都能自动加载。

2. 极度省 Token（渐进式披露的威力）

对比一下：

• 一个 GitHub MCP Server 启动时占用 ~26,000 tokens
• 一个 Skill 启动时只占 ~100 tokens
• 50 个 Skills = 5,000 tokens ≈ 一个 MCP Server 的 1/5

3. 简单到离谱

Skill = 一个 SKILL.md 文件 + 可选的脚本和模板。不需要：

• ❌ 部署服务端
• ❌ 维护协议
• ❌ 写 JSON Schema
• ✅ 只需要写 Markdown 和一点点 YAML

4. 开放标准，一次构建多端复用

2025 年 12 月 18 日作为开放标准发布在 agentskills.io，目前已被 Claude Code、OpenAI Codex、Cursor、VS Code、Gemini CLI、GitHub Copilot、JetBrains 等 30+ 平台支持。

---

四、Skill 的文件结构与规范

最小有效 Skill

一个 Skill 最少只需要一个文件：

my-skill/
└── SKILL.md    # 这就够了！

完整结构

skill-name/
├── SKILL.md          # 必需：YAML 元数据 + Markdown 指令
├── scripts/          # 可选：可执行的脚本（Python/Bash/JS）
│   └── helper.py
├── references/       # 可选：按需加载的参考文档
│   └── api-docs.md
└── assets/           # 可选：模板、图片、静态资源
    └── template.md

SKILL.md 内部结构详解

---
# ============ 必需字段 ============
name: my-awesome-skill         # 1-64字符，小写字母+数字+连字符
description: This skill should be used when...  # 1-1024字符，描述触发条件

# ============ 可选字段 ============
license: Apache-2.0            # SPDX 标识符
compatibility: "requires: git, python>=3.10"  # 环境要求（<500字符）
metadata:                      # 自定义元数据
  author: your-name
  version: "1.0.0"
allowed-tools: "Bash(git:*) Read"  # 预批准的工具列表
---

# 技能名称（Markdown 正文从这里开始）

## 工作流程
1. 步骤一
2. 步骤二

## 具体操作
详细的指令和代码示例...

## 注意事项
- 要点一
- 要点二

关键字段约束

字段	必需	约束
name	✅	≤64字符，小写字母+数字+连字符，不能首尾连字符
description	✅	≤1024字符，必须包含触发条件
license	否	SPDX 标识符（如 Apache-2.0, MIT）
compatibility	否	≤500字符，如 "requires: git, python>=3.10"
allowed-tools	否	预批准的工具，如 "Bash(git:*) Read"

description 怎么写？（最重要的技巧）

核心原则：description 要描述”什么时候触发”，而不是”做什么”。

# ✅ 好的 description —— 聚焦触发条件
description: This skill should be used when the user asks to
"create a hook", "add a PreToolUse hook", "validate tool use",
or mentions hook events. It provides guidance on hook structure,
event types, and best practices for Claude Code hooks.

# ❌ 差的 description —— 太笼统
description: Helps with hooks.

# ❌ 差的 description —— 描述做什么而非触发条件
description: This skill creates hooks by writing hook scripts
and configuring JSON files.

---

五、从入门到精通：手把手写三个 Skill

入门篇：一个”自动生成 Git 提交信息”的 Skill

这是我们写的第一个 Skill。场景：每次 git commit 前，让 AI 根据 diff 自动生成规范的提交信息。

文件结构：

git-commit-helper/
└── SKILL.md

SKILL.md 内容：

---
name: git-commit-helper
description: This skill should be used when the user asks to "commit", "git commit", "生成提交信息", or mentions writing git commit messages. It generates conventional commit messages based on the current git diff.
compatibility: "requires: git"
metadata:
  author: tony
  version: "1.0.0"
allowed-tools: "Bash(git:*)"
---

# Git 提交信息生成器

## 工作流程

1. 运行 `git diff --staged` 获取暂存区的改动
2. 如果暂存区为空，运行 `git diff` 获取工作区改动
3. 分析改动内容，按照 Conventional Commits 规范生成提交信息
4. 提供 2-3 个候选信息供用户选择
5. 用户确认后执行 `git commit -m "选中的信息"`

## Conventional Commits 格式
<type>(<scope>): <subject>
[optional body]

类型（type）：
- `feat`: 新功能
- `fix`: 修复 bug
- `docs`: 文档更新
- `style`: 代码格式（不影响功能）
- `refactor`: 重构
- `perf`: 性能优化
- `test`: 测试相关
- `chore`: 构建/工具链

## 示例

当用户说 "帮我 commit" 时：
1. 执行 `git diff --staged`
2. 发现改动：修改了 `app.py` 中的登录逻辑，修复了 token 过期问题
3. 生成候选信息：
   - `fix(auth): handle expired token gracefully`
   - `fix(auth): return 401 when token has expired`
4. 用户选择第一条后执行 commit

这个小 Skill 虽然简单，却解决了一个日常高频痛点——每次提交都要想怎么写 message。

---

进阶篇：一个带脚本的”API 文档生成器” Skill

这个 Skill 引入了 scripts/ 和 references/，展示渐进式披露的威力。

文件结构：

api-doc-generator/
├── SKILL.md
├── scripts/
│   └── parse_routes.py      # 解析 Python 路由的脚本
├── references/
│   └── doc-template.md       # 文档模板（按需加载）
└── assets/
    └── example-output.md     # 示例输出

SKILL.md：

---
name: api-doc-generator
description: This skill should be used when the user asks to "generate API docs", "create API documentation", "文档生成", or mentions documenting REST API endpoints. It parses Python FastAPI/Flask route definitions and generates OpenAPI-compatible documentation.
compatibility: "requires: python>=3.10"
metadata:
  author: tony
  version: "2.0.0"
allowed-tools: "Bash(python:*) Read"
---

# API 文档生成器

## 工作流程

1. 识别项目框架（FastAPI / Flask / Django REST Framework）
2. 运行 `scripts/parse_routes.py` 解析路由定义
3. 读取 `references/doc-template.md` 获取文档模板
4. 按照模板格式生成 API 文档
5. 输出到 `docs/api/` 目录

## 步骤详解

### 第一步：识别框架

检查项目依赖文件：
- `requirements.txt` 或 `pyproject.toml` 中是否有 fastapi/flask/django
- 查看 `references/doc-template.md` 了解各框架的文档格式差异

### 第二步：解析路由

```bash
python scripts/parse_routes.py --input ./app/ --output /tmp/routes.json

这个脚本会：

• 扫描所有 .py 文件
• 提取 @app.get(), @app.post() 等装饰器
• 提取函数签名和 docstring
• 输出 JSON 格式的路由列表

第三步：生成文档

根据 references/doc-template.md 中的模板，为每个端点生成：

• 请求方法 + 路径
• 请求参数表格
• 响应示例
• 错误码说明

注意事项

• 首次使用前确保 Python 环境有 ast 模块（标准库自带）
• 如果路由使用了装饰器工厂模式，可能需要手动补充

scripts/parse_routes.py（部分）：

#!/usr/bin/env python3
"""解析 Python Web 项目的路由定义"""
import ast
import json
import sys
from pathlib import Path

def extract_routes(filepath: str) -> list[dict]:
    """从 Python 文件中提取路由信息"""
    routes = []
    tree = ast.parse(Path(filepath).read_text())

    for node in ast.walk(tree):
        # 查找 @app.get("/path") 这样的装饰器
        if isinstance(node, ast.FunctionDef):
            for decorator in node.decorator_list:
                route_info = parse_decorator(decorator, node)
                if route_info:
                    routes.append(route_info)
    return routes

# ... 更多实现细节

references/doc-template.md（按需加载）：

# API 文档模板

## 端点：{METHOD} {PATH}

**描述**：{description}

**请求参数**：

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| {name} | {type} | {required} | {default} | {desc} |

**成功响应**：

{response_example}


**错误码**：
| 状态码 | 说明 |
|--------|------|
| 400 | 参数错误 |
| 401 | 未授权 |

这个 Skill 的关键设计点：

• scripts/parse_routes.py 只在需要解析路由时才被调用（L3 穿透层）
• references/doc-template.md 只在生成文档时才被读取
• AI 启动时只知道这个 Skill 能做什么（L1），具体怎么做在触发后才加载（L2）

---

精通篇：一个完整的”代码审查” Skill

这个 Skill 引入更复杂的工作流、更多条件分支，并展示了如何与 MCP 协同工作。

code-review-bot/
├── SKILL.md
├── scripts/
│   ├── diff_analyzer.sh      # 分析 git diff 统计
│   └── lint_runner.sh        # 运行 lint 检查
├── references/
│   ├── security-checklist.md # 安全检查清单
│   ├── style-guide.md        # 代码风格指南
│   └── review-template.md    # 审查报告模板
└── assets/
    └── config.json           # 可配置的审查规则

SKILL.md：

---
name: code-review-bot
description: This skill should be used when the user asks to "review code", "code review", "审查代码", "检查代码", or mentions pull request review. It performs comprehensive code review including security analysis, style checking, and logic review following best practices.
compatibility: "requires: git, python>=3.10"
metadata:
  author: tony
  version: "3.0.0"
allowed-tools: "Bash(git:*,python:*) Read Grep Glob"
---

# 代码审查机器人

## 工作流程总览


graph TD
    A[用户请求审查] --> B{指定了文件/PR?}
    B -->|是| C[获取目标代码]
    B -->|否| D[git diff 获取变更]
    C --> E[运行静态分析]
    D --> E
    E --> F[安全检查]
    F --> G[风格检查]
    G --> H[逻辑审查]
    H --> I[生成审查报告]
    I --> J{发现严重问题?}
    J -->|是| K[标记为需要修改]
    J -->|否| L[标记为通过]


## 审查维度

### 1. 安全性（最高优先级）
读取 `references/security-checklist.md`，逐项检查：
- [ ] SQL 注入风险（是否使用了参数化查询）
- [ ] XSS 风险（用户输入是否转义）
- [ ] 敏感信息泄露（密钥、token 是否硬编码）
- [ ] 权限校验缺失
- [ ] 文件上传漏洞

### 2. 代码风格
读取 `references/style-guide.md`，检查：
- 命名规范（变量、函数、类）
- 函数复杂度（行数、嵌套层级）
- 重复代码
- 注释质量

### 3. 逻辑正确性
- 边界条件处理
- 错误处理是否完整
- 并发安全
- 资源释放

## 使用方式

### 审查当前未提交的改动

用户："帮我审查代码"
→ Skill 执行 git diff，分析所有改动


### 审查指定 PR

用户："审查 PR #42"
→ Skill 通过 gh CLI 获取 PR diff


### 审查指定文件

用户："审查 src/auth.py"
→ Skill 读取文件并进行全面分析

审查报告格式

读取 references/review-template.md，生成如下格式的报告：

# Code Review Report

## 概览
- 审查文件：3 个
- 变更行数：+156 / -42
- 严重问题：1 个
- 建议改进：5 个

## 严重问题
### [SEC-001] SQL 注入风险
- 文件：src/user.py:42
- 问题：使用字符串拼接构建 SQL 查询
- 建议：改用参数化查询


## 与 MCP 协同（可选）

如果环境配置了 GitHub MCP，可以直接：
- 在 PR 上添加评论
- 创建 Review Summary
- 请求变更（Request Changes）

## 注意事项

- 安全问题是阻塞性的，必须修复
- 风格建议是非阻塞性的，可以讨论
- 逻辑问题需要人工确认（AI 可能误判业务逻辑）

references/security-checklist.md（按需加载，内容精简）：

# 安全检查清单

## 注入类
- SQL 注入：检查是否使用 ORM 参数化 / 预编译语句
- 命令注入：检查 os.system() / subprocess 的参数来源
- 模板注入：检查 Jinja2 / Django Template 的 autoescape

## 认证授权
- 检查每个端点是否有认证装饰器
- 检查是否有越权风险（用户 A 访问用户 B 的数据）

## 数据保护
- 密码是否哈希存储
- 敏感配置是否从环境变量读取

---

六、Skill 编写的黄金法则

经过上面三个示例，我们来总结编写高质量 Skill 的核心原则：

法则 1：description 决定一切

AI 靠 description 来判断是否激活你的 Skill。写 description 时问自己：

“当用户说什么话时，应该触发这个 Skill？”

把所有可能的触发词都列上去。

法则 2：L1 精简，L2 聚焦，L3 详尽

层级	写入内容	原则
L1（YAML 元数据）	name + description	能准确匹配即可，不要写流程
L2（SKILL.md 正文）	工作流程 + 核心指令	控制在 ~3000 tokens 内
L3（scripts/references）	脚本、模板、参考文档	放所有”看了才能执行”的细节

法则 3：脚本要”哑”但可靠

Skill 中的脚本不应该包含业务逻辑（那是 AI 的活），而应该提供 AI 无法直接完成的能力：

• 解析复杂文件格式（AST 解析、PDF 提取）
• 执行需要精确性的操作（数学计算、日期处理）
• 与系统交互（文件操作、进程管理）

法则 4：利用 allowed-tools 减少中断

在 YAML 中预声明 Skill 需要使用的工具，减少用户手动批准：

allowed-tools: "Bash(git:*,python:*) Read Grep Glob"

法则 5：测试后再发布

# 验证工具
npx skills-validator validate ./my-skill/

# 在 Claude Code 中加载测试
claude --skill ./my-skill/

---

七、常见问题（FAQ）

Q1: Skills 和 MCP 是不是竞争关系？

不是，它们是互补的分层架构。

• MCP 解决”连接”问题（能不能访问数据库、API、文件系统）
• Skill 解决”流程”问题（怎么用这些数据完成任务）

一个类比：MCP 是高速公路（连接城市），Skill 是导航地图（告诉你走哪条路、在哪下高速、到目的地后怎么办）。

Q2: 一个 Skill 可以调用另一个 Skill 吗？

可以。Claude Code 支持 Skills 之间的协作。例如 code-review-bot 可以引用 git-commit-helper 的工作流。

Q3: 我应该把 Skill 放在哪里？

项目级（推荐）：

项目根目录/.claude/skills/my-skill/SKILL.md

全局级：

~/.claude/skills/my-skill/SKILL.md

Q4: Skill 的安全性如何保障？

• allowed-tools 字段限制 Skill 可用的工具
• compatibility 字段声明环境要求
• 用户始终可以拒绝 Skill 发起的操作
• 2026 年社区已有 skills-validator 等工具进行安全审计

Q5: 怎么写好一个”大众且通俗易懂”的 Skill？

1. 面向场景，不面向功能：不是”这是一个 PDF 工具”，而是”当用户想把网页转成 PDF 时用这个”
2. 含完整示例：在 Skill 正文中给出输入 → 输出示例
3. 考虑错误路径：告诉 AI “如果遇到 X 情况，就做 Y”
4. 用中文写提示词（如果你的用户是中文用户）：AI 能理解多种语言

---

八、展望：Skills 生态的未来

2025-2026 年 Skills 的爆发不是偶然。这背后反映了一个趋势：

Prompt 工程  →  Skill 工程  →  Agent 工程
（临时口头指令）（持久化技能包）（自主决策+多技能协作）

未来，Skills 可能会：

• 出现技能市场（类似 VS Code 插件市场）
• 自动组合（AI 根据任务自动编排多个 Skills 协同工作）
• 动态优化（根据使用反馈自动调整 Skill 内容）
• 企业级治理（组织统一管理哪些 Skills 可用、需要什么权限）

---

九、总结

本文从概念到实战，完整覆盖了 Agent Skills 的方方面面：

1. Skill 是什么：一个包含 SKILL.md 的文件夹，是 AI 的”入职手册 + 工具箱”
2. 与其他概念的区别：MCP 负责连接，Skill 负责流程，Function Call 负责执行
3. 核心设计：渐进式披露（三层加载），极致省 token
4. 实战示例：从简单的 git-commit-helper 到复杂的 code-review-bot
5. 编写法则：description 决定触发、L1-L3 各司其职、脚本提供 AI 无法直接完成的能力

现在，打开你的编辑器，创建一个 SKILL.md，把你最常重复交代给 AI 的那套流程写进去。这就是你的第一个 Skill。

参考资料

• Agent Skills 官方规范
• Anthropic 官方博客：Equipping agents for the real world with Agent Skills
• Claude Code Skills 文档
• 官方示例仓库
• Skills 验证工具
• Skills 与 Prompts、MCP、Subagents 的区别
• 阿里云开发者：Agent Skills 的一次工程实践