如何使用SKILLS

前言

本文以结构化视角解释 SKILLS 体系，并明确 agent.md 与 skill.md 的分工关系，帮助读者在构建 AI Agent 时更快完成技能模块化与执行链路落地。

第一部分：SKILLS 是什么

1.1 从"大而全"到"精而专"

单一、巨大的 Prompt 往往导致上下文过长、维护困难、复用性差和错误率升高。SKILLS 的设计意图是将能力拆成可复用的模块，让 Agent 在合适的时机调用对应技能，形成"工具箱式"工作流。

典型场景：一个 Agent 需要同时具备"搜索"“总结”"发送邮件"能力。若全部写入一个 Prompt，会造成职责混乱；将其拆成独立技能后，Agent 可以按需组合与调度。

1.2 SKILLS 的核心定义

SKILLS 不只是指令片段，而是可复用能力单元。它将任务方法固化为可执行模块，使 Agent 从"理解指令"升级为"执行技能"。常见收益包括：

  • 结构更清晰，技能能独立维护
  • 复用性更高，可被多个 Agent 引用
  • 出错更可控，便于定位和更新

1.3 渐进式三层披露

SKILLS 的设计分为三层：元数据层、技能主体、附加文本与脚本。它们共同构成一个完整的技能定义。

1.3.1 元数据层（Metadata Layer）

元数据用于"技能发现"和"技能选择"。Agent 会根据名称、描述与标签迅速判断技能是否匹配当前任务。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
name: web_search
description: 搜索互联网以获取特定信息。
parameters:
  query:
    type: string
    description: 搜索的关键词或短语。
    required: true
  num_results:
    type: integer
    description: 返回结果的数量。
    default: 5
    optional: true
output:
  type: array
  description: 包含搜索结果的列表，每个结果包含标题、URL 和摘要。
tags: [internet, research]

1.3.2 技能内容主体（Skill Content Body）

这一层是技能的"执行逻辑"。它定义了具体步骤与操作顺序，是 Agent 的行动指南。

1
2
3
4
5
6
7
8
9
name: web_search
steps:
  - 检查 query 是否为空，若为空返回错误
  - 构建搜索引擎 API 请求 URL，包含 query 与 num_results
  - 使用 HTTP GET 调用搜索引擎 API
  - 解析 JSON 响应
  - 提取 title、url、summary
  - 以列表形式返回结果
  - API 调用失败时记录错误并返回空列表

1.3.3 附加文本及脚本（Additional Text & Scripts）

附加内容用于增强鲁棒性与适配复杂情况，例如错误处理、安全策略和性能优化。

1
2
3
4
5
6
7
8
9
error_handling:
  - 搜索引擎 API 返回 5xx 时等待 10 秒后重试，最多 3 次
  - 连续失败后返回"搜索引擎暂时不可用"的错误信息
  - 返回 4xx 时提示具体参数问题
security:
  - 构建请求时避免泄露内部敏感信息
  - 处理外部链接时保持授权边界
performance:
  - 频繁搜索场景建议引入缓存机制

1.4 skill 文件的创建路径

在 Claude Code 中，技能文件存放在用户目录下，支持两种组织方式：

方式一：单文件技能

1
~/.claude/skills/<skill-name>.skill

方式二：带附属资源的技能目录

1
2
3
4
5
~/.claude/skills/<skill-name>/
├── SKILL.md          # 技能主文件
└── references/       # 附属资源（可选）
    ├── guide.md
    └── prompts.md

完成创建后，可在 Claude Code 中通过 /skill-name 命令调用该技能。

第二部分：agent.md 与 skill.md 的关系

2.1 核心分工

agent.md 定义 Agent 的身份、使命与可用资源；skill.md 定义具体任务的执行方式。

  • agent.md：回答"我是谁、我在哪里、我做什么"
  • skill.md：回答"这件事如何做"

可以理解为：agent.md 是公司的战略规划，skill.md 是各部门的操作手册。

2.2 agent.md 的职责

agent.md 是 Agent 的根文件，用于定义行为边界与全局规范。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
name: ResearchAssistant
role: 专业的互联网研究助手，帮助用户快速、准确地获取和分析信息
goal: 为用户提供经过整理和总结的、与查询主题相关的最新信息和深度分析
constraints:
  - 始终引用信息来源
  - 不得进行虚假信息传播
  - 尊重用户隐私
environment:
  internet_access: true
  local_file_system_access: false
  email_sending: false
available_skills:
  - web_search
  - summarize_text
  - keyword_extract
persona:
  tone: Professional and objective
  language: Clear and concise

关键字段说明：

字段 作用
name Agent 名称标识
role 身份与核心职责
goal 存在的根本目的
constraints 行为约束与限制
environment 运行环境与可用资源
available_skills 可调用的技能列表
persona 交互语气与风格

2.3 skill.md 的职责

skill.md 是可执行的技能定义文件，内部包含元数据、技能主体与附加处理逻辑。一个 skill.md 就是一项可独立调用的能力。

完整的 skill.md 示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
---
name: web_search
description: 搜索互联网以获取特定信息
allowed-tools:
  - WebSearch
  - WebFetch
metadata:
  trigger: 需要搜索网络信息时
  source: 内置技能
---

# Web Search 技能

## 执行步骤

1. 检查 query 参数是否为空
2. 构建搜索请求
3. 调用 WebSearch 工具执行搜索
4. 解析并格式化返回结果

## 错误处理

- API 超时：重试最多 3 次
- 无结果：返回空列表并提示用户调整关键词

2.4 协同工作流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
┌─────────────┐
│   用户请求   │
└──────┬──────┘
       ▼
┌─────────────┐
│ 读取 agent.md│ ← 确认身份、目标、可用资源
└──────┬──────┘
       ▼
┌─────────────┐
│   任务拆分   │ ← 根据 goal 和 role 分解任务
└──────┬──────┘
       ▼
┌─────────────┐
│   技能匹配   │ ← 扫描 skill.md 元数据
└──────┬──────┘
       ▼
┌─────────────┐
│   技能执行   │ ← 按 skill.md 主体执行
└──────┬──────┘
       ▼
┌─────────────┐
│   结果输出   │ ← 按 persona 格式化反馈
└─────────────┘

流程说明：

  1. Agent 启动：读取 agent.md，确认身份、目标和可用资源
  2. 任务拆分：接收请求后根据 goal 和 role 分解为子任务
  3. 技能匹配：对每个子任务扫描 available_skills 中各技能的元数据
  4. 技能执行：选定技能后按其主体与附加逻辑完成操作
  5. 结果输出：汇总结果并按照 persona 向用户反馈

实战：创建一个自定义技能

以创建一个"代码审查"技能为例：

步骤 1：创建技能目录

1
mkdir -p ~/.claude/skills/code-review

步骤 2：编写 SKILL.md

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
---
name: code-review
description: 对代码进行审查，检查潜在问题和改进建议
allowed-tools:
  - Read
  - Grep
metadata:
  trigger: 代码审查、review 代码
---

# Code Review 技能

## 审查维度

1. **代码质量**：命名规范、代码风格
2. **潜在 Bug**：空指针、边界条件
3. **性能问题**：循环效率、内存使用
4. **安全隐患**：注入风险、敏感信息暴露

## 输出格式

| 严重程度 | 文件 | 行号 | 问题描述 | 建议 |
|---------|------|-----|---------|------|

步骤 3：使用技能

在 Claude Code 中输入 /code-review 即可调用该技能。

总结

SKILLS 的价值在于将 AI Agent 的能力从"会回答问题"推进为"会执行任务"。

文件 定位 核心内容
agent.md 战略层 身份、目标、约束、可用资源
skill.md 战术层 执行步骤、错误处理、输出格式

当 agent.md 负责战略方向、skill.md 负责战术执行时，Agent 的行为就具备了可控性、复用性与持续进化的基础。