Claude Code Agent Skills 入门指南（上）：原理与规范 —— 让 AI Agent 拥有"肌肉记忆"的可扩展能力

Claude Code Agent Skills 入门指南（上）：原理与规范 ------ 让 AI Agent 拥有"肌肉记忆"的可扩展能力

摘要

Skills 让 Agent 拥有"肌肉记忆"，启动时每个 Skill 仅占用 ~100 tokens （官方数据）。本文详解：核心原理 + SKILL.md 规范 + 5 种提示词编程模式。

引言

问题：上下文窗口的困境

你想让 Agent 拥有多种专业能力：

按团队规范审查代码
写符合约定式提交的 commit message
生成符合模板的 API 文档
...还有更多

传统做法：把这些能力写进系统提示词

问题来了：能力一多，上下文就爆了。

yaml 复制代码

10个专业能力 × 500字 = 5000 tokens
还没开始对话，上下文就占了一大半！

类似的问题也存在于 MCP（Model Context Protocol）：每连接一个 MCP 服务器，所有工具描述都要塞进上下文。连接 3 个服务器，轻松占用 10,000+ tokens。

Agent Skills 的解决方案：渐进式披露

Skills 采用"用多少加载多少"的策略：

时机	加载内容	占用
启动时	所有 Skills 的 name + description	~100 tokens/个
激活时	完整 SKILL.md	~3000 tokens
需要时	references/ 资源	按需

效果：20 个 Skills 启动时只占 2000 tokens，用哪个才加载哪个。

💡 简单理解：如果把 Agent 比作一个实习生，Skills 就是他的"操作手册"------不用把所有手册背在脑子里，需要时才翻开对应的那本。

本文将带你从零理解 Skills，学会如何让 Agent 高效获得专业能力。

一、5 分钟快速入门

1.1 创建你的第一个 Skill

bash 复制代码

# 在项目的 .claude/skills/ 目录下创建
mkdir -p .claude/skills/code-reviewer

创建 SKILL.md 文件：

yaml 复制代码

---
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
1. Read the code - Understand purpose and context
2. Identify issues - Security, bugs, performance
3. 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,))

shell 复制代码

### 1.2 使用 Skill

```bash
# 方式1：Claude 自动识别（当你问"帮我审查代码"时）
# 方式2：手动调用
/code-reviewer

就这么简单！现在你的 Agent 就拥有了专业的代码审查能力，而且每次都记得检查 SQL 注入。

二、核心原理：为什么 Skills 如此优雅？

2.1 元工具架构（Meta-Tool）

Skills 的核心是一个元工具设计。看 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 目录结构

bash 复制代码

skill-name/
├── SKILL.md              # 必需：元数据 + 指令
├── scripts/              # 可选：可执行代码
├── references/           # 可选：详细文档（按需加载）
└── assets/               # 可选：模板、资源

3.2 YAML Frontmatter

yaml 复制代码

---
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 的唯一依据！）

yaml 复制代码

# ✅ 好的描述：包含做什么 + 何时使用 + 关键词
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 内容结构

推荐章节结构：

markdown 复制代码

# 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 但不提供领域上下文，结果只是模糊的"遵循最佳 practices"------废话连篇。

两种正确方法：

方法 1：从实际任务中提取

markdown 复制代码

1. 与 Agent 完成一个真实任务（比如代码审查）
2. 记录：成功的步骤、你做的修正、输入/输出格式
3. 提取可复用模式，写成 Skill

方法 2：从现有项目工件中综合

内部文档、runbook、风格指南
API 规范、配置文件
代码审查评论、issue 历史记录

4.2 简洁至上

markdown 复制代码

❌ 啰嗦（~150 tokens）：
PDF (Portable Document Format) is a common file format developed by Adobe...
To install the required library, first ensure you have 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 偏好过程而非声明

markdown 复制代码

❌ 声明式（针对特定实例，无法复用）：
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 按步骤执行，不能跳过任何一步。

程序思维：

python 复制代码

steps = ["检查代码结构", "检查安全漏洞", "检查性能", "生成报告"]
for step in steps:
    execute(step)

SKILL.md 写法：

markdown 复制代码

## 审查流程

复制这个检查清单，逐步完成：

代码审查进度：
- [ ] 第1步：检查代码结构和组织
- [ ] 第2步：识别潜在的 bug 或逻辑错误
- [ ] 第3步：审查安全漏洞
- [ ] 第4步：提出性能优化建议
- [ ] 第5步：生成最终报告

为什么有效：

Agent 会把清单当作"待办事项"
每完成一项，Agent 会在对话中更新状态
用户可以实时看到进度

5.2 反馈循环模式 = 模拟 while 循环

场景：你想让 Agent "失败了就重试，直到成功"。

程序思维：

python 复制代码

while not validation_passed:
    fix_issues()
    validation_passed = run_validation()

SKILL.md 写法：

markdown 复制代码

## 文档编辑流程

1. 修改文档内容
2. **立即验证**：运行 `python scripts/validate.py`
3. 如果验证失败：
   - 仔细阅读错误信息
   - 修复刚才的修改
   - **回到第2步**重新验证
4. **只有验证通过才能继续下一步**

为什么有效：

明确告诉 Agent "失败了要回头"
设定了明确的退出条件（"只有验证通过才能继续"）
防止 Agent 草草了事

5.3 模板模式 = 模拟格式化函数

场景：你想让 Agent 的输出格式完全统一，每次都一样。

程序思维：

python 复制代码

def format_report(title, summary, findings):
    return f"""
    # {title}
    ## 摘要
    {summary}
    ## 关键发现
    {findings}
    """

SKILL.md 写法：

markdown 复制代码

## 报告结构

**重要：必须严格使用以下模板：**

# [分析标题]

## 摘要
[这里写且只写一段话，概述核心结论]

## 关键发现
- 发现1：[具体描述] + [支持数据]
- 发现2：[具体描述] + [支持数据]
- 发现3：[具体描述] + [支持数据]

## 建议
[基于发现的具体行动建议]

为什么有效：

用"必须"和"严格使用"强调格式的重要性
提供具体的占位符（如 [分析标题]）
限制内容长度（"写且只写一段话"）

5.4 示例模式（Few-shot）= 模拟训练数据

场景：你想让 Agent 模仿某种特定的输入→输出格式。

程序思维：需要训练数据，但提示词不能"训练"模型。

SKILL.md 写法：

markdown 复制代码

## Commit Message 格式

严格按照以下示例格式：

**示例1：**
- 输入："添加了用户登录功能，使用 JWT 认证"
- 输出：

feat(auth): 实现 JWT 用户认证

新增登录接口和 token 生成逻辑
添加 token 验证中间件

markdown 复制代码

**示例2：**
- 输入："修复了用户无法重置密码的 bug"
- 输出：

fix(auth): 修复密码重置失败问题

修正重置流程中的邮箱验证逻辑
添加邮件发送的重试机制

sql 复制代码

现在按同样格式生成用户的 commit message。

为什么有效：

Agent 通过例子理解模式，比抽象描述更直观
"严格按照以下示例"强调要模仿格式
多个例子帮助 Agent 泛化规则

5.5 计划-验证-执行模式 = 模拟 try-catch + 确认

场景：破坏性操作（删除、批量修改），需要"安全网"。

程序思维：

python 复制代码

plan = generate_plan()
if validate(plan):
    if user_confirms(plan):
        execute(plan)
else:
    revise_and_retry()

SKILL.md 写法：

markdown 复制代码

## 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 指令	UX 和 AI 效果兼得
渐进式披露	三层加载优化上下文使用	20 个 Skills 只占 2000 tokens
LLM 驱动选择	无需算法匹配，由模型推理决定	零代码意图识别

我的观察 ：Skills 的本质是一个轻量的上下文管理机制。它通过渐进式披露解决了两个核心问题：

MCP 上下文爆炸：每连接一个 MCP 服务器都要塞入大量工具描述
专业能力注入：给 Agent 添加多个专业能力，但不想一次性占用所有上下文

相比把所有指令写进系统提示词，Skills 让你"用多少加载多少"------这就是它最大的价值。

关键资源

📌 下篇预告 ：《Claude Code Agent Skills 完全指南（下）：实战与进阶》------从零实现一个完整的 Skill 系统，包含 code-reviewer 深度案例、SkillsManager 核心代码、Agent 集成完整流程，以及踩坑心得。

💬 互动话题：你在用 AI 问题？欢迎评论区分享，我们一起探讨能否用 Skills 解决！