Agent Skills 基础知识

你是否遇到过这样的场景：每次和 Claude 对话时，都要反复重复同样的代码规范或工作流程？有没有想过，能不能把这些”经验”打包成一个可复用的工具，让 AI 自动调用？

Agent Skills 就是为解决这个问题而生的。简单来说，它是一种将专业知识、工作流程固化为可复用资产的方式——就像给 AI 配备了一本”专业手册”，它可以根据任务类型自动翻阅相应章节，而不是每次都从头学习。

理解 Agent Skills，关键在于把握它的本质：

它不是一种新工具，而是「行为规范 + 专业知识 + 触发时机」的组合封装

它的存在形式非常简单：

• 一个 Skill = 一个文件夹 + 一个 SKILL.md 文件（核心配置）
• SKILL.md 告诉 Claude：什么情况下用这个技能、具体怎么做、要注意什么
• 相当于给 AI 写了一份”操作指南”，它遇到相关任务时会自动查阅
• 你可以把它理解为「升级版的提示词」——不仅能复用，还能自动触发、团队共享

Agent Skills 是如何工作的？

Agent Skills 采用「渐进式披露」的加载机制，分三个层次逐步加载内容：

• 第一层：快速扫描 — AI 先读取所有 Skill 的元数据（名称和描述），判断当前任务是否需要某个技能。这些元数据始终常驻在系统提示中，就像书籍的目录。
• 第二层：按需加载 — 当任务匹配到某个 Skill 时，AI 自动读取该 SKILL.md 的完整内容，获取详细的操作指导。
• 第三层：深度调用 — 如果需要，AI 会读取技能包中的额外文件（如示例代码、参考文档），或直接执行其中的脚本。

哪些平台支持 Agent Skills？

目前 Agent Skills 已经在多个主流 AI 编程工具中得到支持：

• Claude 全家桶：包括 Claude.ai 网页版、Claude Code 命令行工具、Agent SDK
• VS Code + GitHub Copilot：支持项目级技能（.github/skills/）和用户级技能
• Cursor 编辑器：支持项目级和全局技能，可从 GitHub 直接安装
• 其他平台：开放标准正在持续扩展，详见 GitHub 开源标准

为什么需要 Agent Skills？

虽然 Claude、Copilot 等 AI 助手已经很强大，但在实际使用中仍会遇到一些痛点：

• 重复劳动：团队有统一的代码规范，但每次都要手动提醒 AI 遵循
• 上下文缺失：处理 PDF 表单、调试 GitHub Actions 等复杂任务时，AI 可能不了解最佳实践
• 提示词冗长：每次都要复制粘贴大段提示词，效率低下

Agent Skills 带来的改变是显而易见的：

• 智能触发：AI 自动识别任务类型，调用对应技能，无需手动干预
• 一次创建，无限复用：团队成员可以共享同一个 Skill，支持 Git 版本管理
• 节省上下文：采用渐进式加载，只在需要时读取对应内容，避免上下文窗口溢出
• 跨平台通用：同一个 Skill 可以在 Claude、Copilot、Cursor 等多工具中使用

四个核心概念

概念	生活类比	具体作用
Skill（技能包）	一套完整的工具箱或菜谱	完成特定任务（如写邮件、数据分析）的全部材料和说明
Instruction（指令）	工具说明书或菜谱步骤	告诉 Claude 做什么、怎么思考、输出格式是什么
Knowledge（知识库）	工具零件清单或食材资料	作为技能参考的上传文件（如 API 文档、产品手册）
Tool（工具）	工具的特殊功能部件	技能可调用的外部 API 或函数，用于获取数据或执行操作

Skill 的执行流程

• 用户发出指令 → AI 分析意图，判断是否需要调用某个 Skill
• 匹配到 Skill 后 → 加载对应的 SKILL.md，明确行为边界和可用工具
• 执行过程中 → 只在必要时调用被允许的外部工具，否则按规则内部处理
• 输出结果 → 整合约束后返回给用户，等待下一次指令

---

最简 Skill 结构

创建一个 Skill，最低只需要一个文件：

my-skill/
└── SKILL.md   （这是唯一必需的文件）

SKILL.md 的基本模板如下：

---
name: your-skill-name
description: 技能功能说明及使用场景
---

# 技能标题

## 具体指令
这里写清楚、可执行的规则。

## 使用示例
- 示例场景 1
- 示例场景 2

## 注意事项
- 注意点 1
- 注意点 2

SKILL.md 开头的 YAML 区域称为「元数据」，包含以下字段：

字段	必填	说明
name	否	技能名称，默认使用文件夹名，只能含小写字母、数字、短横线（最长 64 字符）
description	推荐	技能用途及触发时机，Claude 依据此判断是否自动调用
argument-hint	否	参数提示，如 [issue-number] 或 [filename] [format]
disable-model-invocation	否	设为 true 禁用自动触发，仅可通过 /name 手动调用（默认 false）
user-invocable	否	设为 false 从 / 菜单隐藏，作为后台能力使用（默认 true）
allowed-tools	否	技能激活时 Claude 可直接使用的工具列表
model	否	指定技能使用的模型
context	否	设为 fork 时在子代理上下文中运行
agent	否	子代理类型（需配合 context: fork 使用）
hooks	否	技能生命周期钩子配置

在 SKILL.md 中，还可以使用以下动态变量：

变量	用途
$ARGUMENTS	调用技能时传入的所有参数
$ARGUMENTS[N]	按索引获取参数，如 $ARGUMENTS[0] 表示第一个参数
$N	参数简写，如 $0 等同于 $ARGUMENTS[0]
${CLAUDE_SESSION_ID}	当前会话 ID，可用于日志、临时文件命名等

举个实际例子：

---
name: session-logger
description: 记录当前会话的活动日志
---

请将以下内容追加到日志文件：

logs/${CLAUDE_SESSION_ID}.log

$ARGUMENTS

使用方式：

/session-logger 用户登录成功

系统会自动生成一个属于当前会话的专属日志文件。

SKILL.md 文件深度解析

以 Claude 的 PDF 处理技能为例：Claude 本身可以读取 PDF 内容，但无法直接编辑（如填写表单）。通过编写一个专门的 Skill，就可以补齐这块功能短板。

• 文件形态：一个包含 SKILL.md 的文件夹
• 必备元数据：文件开头的 YAML 块，至少包含 name 和 description，会在启动时预加载到系统提示中

多文件 Skill 与渐进式披露

当 Skill 变得复杂时，可以将内容拆分到多个文件，实现渐进式加载：

• 第一层：元数据 — 让 Claude 快速判断这个技能是做什么的，不加载全文
• 第二层：SKILL.md 主体 — 判定相关后，才加载完整的指令内容
• 第三层及更深层：附属文件 — 按需引用（如 forms.md），保持主文件精简

下图展示了一个技能被触发时，上下文窗口的变化过程：

• 初始状态：上下文包含系统提示词、所有技能的元数据、用户指令
• 触发技能：调用工具读取对应的 SKILL.md 文件
• 按需加载：根据需要读取附属文件（如 forms.md）
• 执行任务：所有必要信息加载完成后，执行用户要求的操作

推荐的 Skill 目录结构

为避免单个文件过于臃肿，建议采用以下结构组织你的 Skill：

• SKILL.md — 放置核心规则和必读内容
• reference.md — 存放详细参考资料
• examples.md — 收集使用示例
• scripts/ — 放置可执行脚本（运行时不加载，按需调用）

一个典型的 Skill 文件夹结构：

my-skill/
├── SKILL.md          # 核心配置和指令（必选）
├── reference.md      # 参考文档
├── examples.md       # 示例合集
└── scripts/
    └── helper.py     # 辅助脚本

---

动手创建第一个 Skill

光说不练假把式。让我们通过一个简单的实例，亲手创建一个 Skill，感受它的威力。

创建目录结构

Skill 可以存放在两个位置：

• ~/.claude-code/skills/ — 全局技能，所有项目都能用
• 项目目录/.claude/skills/ — 项目专属技能，仅当前项目有效

本教程在项目目录下演示。首先创建一个测试目录：

mkdir claude-test
cd claude-test
mkdir -p .claude/skills/python-naming-standard

编写 SKILL.md

在刚才创建的目录中新建 SKILL.md 文件：

---
name: python-naming-convention
description: 当用户编写、审查或重构 Python 代码时，强制执行内部函数命名规范
---

## 核心规则
1. 所有内部辅助函数必须以 \`_internal_\` 前缀开头
2. 发现不符合规则的代码时，主动指出并给出修改建议
3. 执行 \`claude commit\` 之前，必须检查是否符合此规范

## 代码示例
\`\`\`python
# ✅ 正确写法
def _internal_calculate_discount(user_score):
    return user_score * 0.1

# ❌ 错误写法
def calculate_discount(user_score):
    return user_score * 0.1
\`\`\`

元数据字段说明：

• name：只能包含小写字母、数字和连字符，不超过 64 个字符
• description：清晰描述技能的用途和触发时机，不超过 1024 个字符

创建完成后，目录结构应该如下所示：

一个完整的项目目录结构示例：

my-project/
├─ src/
│  └─ test.py              # 源代码文件
├─ .claude/
│  ├─ skills/
│  │  └─ python-naming-standard/
│  │     ├─ SKILL.md       # 技能定义（核心文件）
│  │     └─ README.md      # 技能说明（可选，供人类阅读）
│  └─ config.yml           # Claude 项目配置（可选）
├─ .gitignore
└─ README.md

测试 Skill 效果

在终端中启动 Claude Code：

claude

然后输入以下任务：

帮我写一个计算用户折扣的函数

Claude 会自动检测到你的请求涉及”Python 代码编写”，从而触发 python-naming-convention 技能：