Claude Code Agent Skills 入门指南（上）：原理与规范 —— 让 AI Agent 拥有"肌肉记忆"的可扩展能力
摘要
引言
问题：上下文窗口的困境
你是否希望你的 Agent 能同时掌握多种专业能力？例如，依据团队规范审查代码、生成符合约定式提交规范的 commit message、或者输出格式统一的 API 文档……这个能力清单可以列得很长。
传统做法是将所有这些能力一次性塞进系统提示词中。然而，这会带来一个明显的痛点：当能力增多时，上下文窗口很快就会不堪重负。
我们来算一笔简单的账：
10 个专业能力 × 每个 500 字 = 5,000 tokens。请注意，在正式对话还未开始前，宝贵的上下文空间就已经被占去了一大半！
类似的问题在 MCP（Model Context Protocol）中也同样存在：每连接一个 MCP 服务器，所有工具的详细描述都需要占用上下文。一旦连接 3 个服务器，轻易就能吃掉 10,000+ tokens。
Agent Skills 提供的解决方案是：渐进式披露。
简单来说，就是"用到多少就加载多少"：
| 时机 | 加载内容 | 占用 |
|---|---|---|
| 启动时 | 所有 Skills 的 name + description | ~100 tokens/个 |
| 激活时 | 完整 SKILL.md | ~3000 tokens |
| 需要时 | references/ 资源 | 按需 |
效果非常直观：即使同时启用 20 个 Skills，启动时也仅占用 2,000 tokens。用到哪个，就加载哪个，上下文压力瞬间得到了显著缓解。
本文将从零开始，带你深入理解 Skills，并掌握如何让 Agent 高效获取并运用专业能力。
一、5 分钟快速入门
1.1 创建你的第一个 Skill
首先，在项目的 .claude/skills/ 目录下创建文件夹：
mkdir -p .claude/skills/code-reviewer
然后，创建 SKILL.md 文件：
---
name: code-reviewer
description: Review code for quality, security, and best practices. Use when asked to review code, check for bugs, audit security.
allowed-tools: "Read Grep Glob"
---
Code Reviewer
Review workflow
- Read the code - Understand purpose and context
- Identify issues - Security, bugs, performance
- Prioritize findings - Critical > Major > Minor > Suggestion
Output format
Critical Issues: X
Critical
- [Line 42] SQL injection vulnerability
```python
# Before: query = f"SELECT * FROM users WHERE id = {user_id}"
# After: cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,))
```
1.2 使用 Skill
# 方式1：Claude 自动识别（当你问"帮我审查代码"时）
# 方式2：手动调用
/code-reviewer
就是这么简单。现在，你的 Agent 已经具备了专业的代码审查能力，并且每次都会记得检查诸如 SQL 注入这类常见的安全漏洞。
二、核心原理：为什么 Skills 如此优雅？
2.1 元工具架构（Meta-Tool）
Skills 的核心是一个元工具（Meta-Tool）设计。我们来看一下 Claude API 的请求结构：
graph TB
subgraph "Claude API 请求"
A[system: You are Claude Code...]
B[messages: 用户消息 + 对话历史]
subgraph "tools 数组"
C["Skill (元工具)
管理所有 skills"]
D[Read]
E[Write]
F[Bash]
end
end
B --> C
C --> G[("skills 列表
(name + description)")]
关键洞察：
Skill（大写 S）是元工具，负责管理所有 individual skills。- Skills 并未放置在系统提示词中，而是位于 tools 数组的 Skill 工具描述里。
- 技能的选择完全由 LLM 推理完成，无需算法匹配或意图分类器。
这意味着什么？你只需写好 description，Claude 就能自动判断何时调用你的 Skill。你不需要编写正则表达式，更不需要训练分类模型——这才是真正的"LLM 原生"设计。
2.2 两消息模式（Two-Message Pattern）
当 Skill 被触发时，系统会注入两条消息：
sequenceDiagram
participant U as 用户
participant A as Agent
participant S as Skill 系统
U->>A: 帮我审查代码
A->>S: 决定调用 Skill(code-reviewer)
S-->>U: 消息1: "code-reviewer skill is loading"
S-->>A: 消息2: [完整 SKILL.md 内容]
A->>A: 根据指令执行代码审查
A-->>U: 返回审查结果
| 消息 | 受众 | 目的 | 典型长度 |
|---|---|---|---|
| 元数据消息 | 人类用户 | 状态通知，让用户了解当前操作 | ~50-200 字符 |
| Skill 提示词 | Claude (AI) | 执行指令，指导 AI 具体操作 | ~500-5000 词 |
为什么需要两条消息？这是用户体验与 AI 效能之间的一种精妙平衡——用户希望知道"Agent 正在做什么"，但无需看到冗长的指令；AI 则需要完整的操作指南，但这些内容对用户来说可能显得困惑。将两者分离，各取所需。
2.3 渐进式披露（Progressive Disclosure）
这是 Skills 最精妙的设计点之一——通过三层加载策略，高效管理宝贵的上下文窗口：
graph LR
subgraph "第一层：元数据 ~100 tokens"
A1[启动时加载]
A2["所有 skills 的
name + description"]
A3["→ LLM 据此选择"]
end
subgraph "第二层：指令 < 5000 tokens"
B1[Skill 激活时加载]
B2[完整 SKILL.md]
B3["→ AI 获得详细指导"]
end
subgraph "第三层：资源 按需"
C1[需要时才加载]
C2["references/
scripts/assets"]
C3["→ 通过 Read 工具"]
end
A1 --> A2 --> A3 --> B1 --> B2 --> B3 --> C1 --> C2 --> C3
我们再来算一笔账。假设你配置了 20 个 Skills：
- ❌ 一次性全部加载：20 × 3000 tokens = 60,000 tokens（直接撑爆上下文）
- ✅ 渐进式披露：启动时仅占 20 × 100 = 2,000 tokens，用到哪个才加载哪个。
这意味着可以节省高达 97% 的上下文空间！这也是为什么你可以在一个项目里配置几十个 Skills，而完全无需担心性能问题。
三、SKILL.md 规范详解
3.1 目录结构
skill-name/
├── SKILL.md # 必需：元数据 + 指令
├── scripts/ # 可选：可执行代码
├── references/ # 可选：详细文档（按需加载）
└── assets/ # 可选：模板、资源
3.2 YAML Frontmatter
---
name: pdf-processing # 必需：1-64字符
description: Extract text from PDF... # 必需：1-1024字符
license: MIT # 可选
compatibility: Python 3.8+ # 可选：环境要求
allowed-tools: "Read Bash(pdftotext:*)" # 可选：预批准工具
---
name 字段约束
| 规则 | 示例 |
|---|---|
| 1-64 字符 | ✅ code-reviewer |
| 只能包含小写字母、数字、连字符 | ✅ pdf-analyzer |
| 不能以连字符开头/结尾 | ❌ -helper, tool- |
| 不能有连续连字符 | ❌ my--tool |
| 必须与目录名匹配 | 目录 code-reviewer/ → name: code-reviewer |
description 写作要点（这是 LLM 选择 Skill 的唯一依据！）
# ✅ 好的描述：明确包含做什么、何时使用及相关关键词
description: Review code for quality, security, and best practices. Use when asked to review code, check for bugs, suggest improvements, or audit security.
# ❌ 差的描述：过于模糊，LLM 无法判断适用场景
description: Helps with code
写作技巧：
- 采用第三人称书写（"Review code..."而非"我来审查..."）
- 包含用户自然会使用的关键词（如"review code", "check for bugs"）
- 清晰描述使用场景（"Use when asked to..."）
3.3 Body 内容结构
推荐的章节结构：
# Skill 名称
## Quick start
简洁的快速开始示例（最为重要！请置于最前面）
## Step-by-step instructions
核心操作流程
## Examples
具体的代码示例
## Common edge cases
常见的边缘情况处理
## Advanced Resources
按需加载的详细参考资料：
- **完整检查清单**: See [references/checklist.md](references/checklist.md)
⚠️ 重要限制：
- SKILL.md 内容应控制在 500 行以下，并保持在 5,000 tokens 以内。
- 仅包含每次执行都需要的核心指令。
- 详细内容应放入
references/目录，由 AI 按需读取。
四、最佳实践
4.1 从真实专业知识开始
一个常见的误区：让 LLM 自行生成 skill，却不提供任何领域上下文。结果往往是一些泛泛而谈的"遵循最佳实践"——说了等于没说。
正确的做法有两种：
方法 1：从实际任务中提炼
1. 与 Agent 共同完成一个真实任务（例如代码审查）
2. 记录：成功的步骤、你做出的修正、输入/输出格式
3. 提取可复用的模式，编写为 Skill
方法 2：从现有项目工件中整合
- 内部文档、工作手册、风格指南
- API 规范、配置文件
- 代码审查评论、issue 历史记录
4.2 简洁至上
❌ 啰嗦（约150 tokens）：
PDF (Portable Document Format) is a common file format developed by Adobe...
To install the required library, first ensure you ha ve Python 3.8+...Then run pip install pdfplumber...
✅ 简洁（约50 tokens）：
Use pdfplumber for text extraction:
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
一个自检问题：如果没有这条指令，Agent 会出错吗？如果不会，那就删掉它。
4.3 设计一致的粒度
- 粒度过窄：
read-python-file、read-js-file→ 多个 skills 同时加载，容易引发混乱。 - 粒度过广：
do-everything→ 难以精准激活。 - 粒度适中：
code-reviewer→ 封装了一致的代码审查工作流。
4.4 偏好过程而非声明
❌ 声明式（针对特定实例，难以复用）：
Join the `orders` table to `customers` on `customer_id`...
✅ 过程式（可复用的方法论）：
1. Read the schema from `references/schema.yaml` to find relevant tables
2. Join tables using the `_id` foreign key convention
3. Apply filters from the user's request as WHERE clauses
五、SKILL.md 编写模式：用提示词"模拟"代码逻辑
核心问题在于：SKILL.md 是纯文本提示词，没有真正的 if/else、for 循环、while 循环。然而，我们需要 Agent 依据某种"逻辑"来执行任务。
解决方案：采用结构化的自然语言来模拟程序的控制流程。这就是"模式"的价值所在。
5.1 工作流模式 = 模拟 for 循环
场景：你希望 Agent 按步骤依次执行，不能跳过任何一步。
程序思维：
steps = ["检查代码结构", "检查安全漏洞", "检查性能", "生成报告"]
for step in steps:
execute(step)
SKILL.md 写法：
## 审查流程
请复制此检查清单，并逐步完成：
代码审查进度：
- [ ] 第1步：检查代码结构和组织方式
- [ ] 第2步：识别潜在的 bug 或逻辑错误
- [ ] 第3步：审查安全漏洞
- [ ] 第4步：提出性能优化建议
- [ ] 第5步：生成最终审查报告
为什么有效：
- Agent 会将清单视为"待办事项列表"。
- 每完成一项，Agent 会在对话中更新状态。
- 用户可以实时了解执行进度。
5.2 反馈循环模式 = 模拟 while 循环
场景：你希望 Agent "失败了就重试，直到成功为止"。
程序思维：
while not validation_passed:
fix_issues()
validation_passed = run_validation()
SKILL.md 写法：
## 文档编辑流程
1. 修改文档内容
2. **立即验证**：运行 `python scripts/validate.py`
3. 如果验证失败：
- 仔细阅读错误信息
- 修正刚才的修改
- **返回第2步**，重新进行验证
4. **只有验证通过，才能继续执行后续步骤**
为什么有效：
- 明确告知 Agent "失败后需要回头重试"。
- 设定了清晰的退出条件（"只有验证通过才能继续"）。
- 有效防止 Agent 草草了事。
5.3 模板模式 = 模拟格式化函数
场景：你希望 Agent 的输出格式完全统一，每次都能保持一致。
程序思维：
def format_report(title, summary, findings):
return f"""# {title}
## 摘要
{summary}
## 关键发现
{findings}
"""
SKILL.md 写法：
## 报告结构
**重要：必须严格使用以下模板：**
[分析标题]
摘要
[在此处撰写且仅撰写一段话，概述核心结论]
关键发现
- 发现1：[具体描述] + [支持数据]
- 发现2：[具体描述] + [支持数据]
- 发现3：[具体描述] + [支持数据]
建议
[基于发现的、可操作的具体建议]
为什么有效：
- 使用"必须"和"严格使用"等措辞，强调格式的严肃性。
- 提供具体的占位符（如
[分析标题]）。 - 限制内容长度（"撰写且仅撰写一段话"）。
5.4 示例模式（Few-shot）= 模拟训练数据
场景：你希望 Agent 模仿某种特定的输入→输出格式。
程序思维：需要训练数据，但提示词无法"训练"模型。
SKILL.md 写法：
## Commit Message 格式
请严格按照以下示例格式执行：
示例1：
- 输入："添加了用户登录功能，使用 JWT 认证"
- 输出：
feat(auth): 实现 JWT 用户认证
- 新增登录接口和 token 生成逻辑
- 添加 token 验证中间件
示例2：
- 输入："修复了用户无法重置密码的 bug"
- 输出：
fix(auth): 修复密码重置失败问题
- 修正重置流程中的邮箱验证逻辑
- 添加邮件发送的重试机制
现在，请按照同样格式为用户的变更生成 commit message。
为什么有效：
- Agent 通过具体例子理解模式，这比抽象描述更为直观。
- "严格按照以下示例"强调了模仿格式的重要性。
- 提供多个例子有助于 Agent 泛化规则。
5.5 计划-验证-执行模式 = 模拟 try-catch + 确认
场景：执行破坏性操作（如删除、批量修改）时，需要一个"安全网"。
程序思维：
plan = generate_plan()
if validate(plan):
if user_confirms(plan):
execute(plan)
else:
revise_and_retry()
SKILL.md 写法：
## PDF 表单填写（安全模式）
第1步：分析
运行 `python scripts/analyze_form.py input.pdf`
→ 生成 `form_fields.json`（列出所有字段）
第2步：计划
创建 `field_values.json`，填写你计划填入的值
第3步：验证（关键步骤！）
运行 `python scripts/validate_fields.py form_fields.json field_values.json`
- 检查项：字段名是否存在、类型是否匹配、必填字段是否已填写
- **如果验证失败**：修改 `field_values.json`，然后重新执行第3步
- **在验证通过之前，禁止执行下一步操作**
第4步：执行（验证通过后方可执行）
运行 `python scripts/fill_form.py input.pdf field_values.json output.pdf`
为什么有效：
- 强制插入验证环节。
- 明确禁止跳过验证步骤（"在验证通过之前，禁止执行下一步操作"）。
- 即使 Agent 试图简化流程，也有脚本层面的检查作为保障。
模式速查表
| 模式 | 模拟的程序逻辑 | 适用场景 | 关键词示例 |
|---|---|---|---|
| 工作流 | for 循环 | 多步骤任务 | "逐步完成"、"检查清单" |
| 反馈循环 | while 循环 | 需要确保质量 | "如果失败，重试"、"只有...才能继续" |
| 模板 | 格式化函数 | 输出格式固定 | "必须使用此模板"、"严格按格式" |
| 示例(Few-shot) | 训练数据 | 格式转换、风格统一 | "按以下示例格式"、"参照示例" |
| 计划-验证-执行 | try-catch | 有风险的操作 | "关键"、"禁止跳过"、"验证通过后" |
请记住：这些模式并非魔法，它们只是用自然语言描述了你所期望的执行逻辑。在编写时，想象你正在教导一位聪明的实习生——他需要清晰的步骤指引，但不必每行代码都写出。
六、小结
Agent Skills 的核心设计理念，可以归纳为下表：
| 概念 | 说明 | 解决的问题 |
|---|---|---|
| 元工具架构 | 通过单一 Skill 工具管理所有 skills | 无需维护复杂的技能注册表 |
| 两消息模式 | 分离用户可见的状态通知与 AI 执行指令 | 兼顾用户体验与 AI 效果 |
| 渐进式披露 | 采用三层加载策略优化上下文使用 | 20 个 Skills 仅占用 2000 tokens |
| LLM 驱动选择 | 无需算法匹配，由模型推理决定技能调用 | 实现零代码意图识别 |
我的观察是：Skills 的本质，是一个轻量级的上下文管理机制。它通过渐进式披露，成功解决了两个核心问题：
- MCP 上下文爆炸：避免了每连接一个 MCP 服务器都要塞入大量工具描述。
- 专业能力注入：能够为 Agent 添加多种专业能力，而无需一次性占用所有上下文资源。
相比于将所有指令写入系统提示词，Skills 让你能够"按需加载"——这正是它最大的价值所在。
关键资源
- Agent Skills 官方规范
- Claude Code Skills 文档
- Claude 官方最佳实践
