手把手教你编写自己的Agent技能教程

功能概述

先来说说 Agent Skills 到底是什么。简单而言，它是一种相当轻量级的开放格式，专门用于通过专业知识与预设的工作流，为 AI 智能体提供能力增强。

如今的智能助手能力确实越来越强大，但您可能已经发现，它们在实际执行任务时，往往缺少关键的信息——上下文。这就像一个非常能干的实习生，各种工具都会操作，却不了解公司内部的流程和规范，结果还是容易出错。技能模块正是为解决这一痛点而设计的：它允许智能助手按需加载程序化知识，以及企业、团队和用户独有的上下文信息。换句话说，一个配备了技能集的助手，能够根据当前任务实时扩展自身能力。

• 对技能开发者：一次性搭建完能力，即可部署到多种不同的智能体产品中。
• 对兼容智能体：用户获取后可直接为智能体安装新技能，实现开箱即用。
• 对团队和企业：可将组织内的各种知识封装为可移植、支持版本控制的知识包。

什么是技能

讲了很多概念，不如直接看看它的样子。一个技能本质上就是一个文件夹，里面必须包含一个名为 SKILL.md 的文件。

这个 SKILL.md 文件至少需要包含两项内容：元数据（例如名称、用途描述）和执行指令（指导智能体具体如何操作）。当然，技能文件中还可以附带脚本、模板、参考资料等附加资源，完全根据实际需求而定。

一个典型的技能目录结构如下所示：

my-skill/
├── SKILL.md          # 必需：指令 + 元数据
├── scripts/          # 可选：可执行代码
├── references/       # 可选：文档资料
└── assets/           # 可选：模板、资源

技能的工作原理

技能的工作方式非常巧妙，它采用一种称为“渐进式披露”的方法来管理上下文，避免一开始就将所有信息都塞给 AI。

1. 发现阶段：智能体启动时，只加载每个技能的名称和简短描述。够用就行，它只需知道“在什么场景下可能用到这个技能”。
2. 激活阶段：当智能体接到的任务与某个技能描述匹配时，它才会将完整的 SKILL.md 指令读入自己的上下文。
3. 执行阶段：此时智能体按照指令开始执行任务，如果指令中引用了其他文件或需要执行脚本，它也会进行加载和运行。

这套机制的优势很明显：既保证了响应速度，又能在需要深度执行时，获取足够多的上下文信息。

SKILL.md 文件结构

每个技能的核心就是 SKILL.md 文件。它主要包含两部分：YAML 格式的前置元数据和 Markdown 格式的指令正文。

---
name: pdf-processing
description: 从 PDF 提取文本和表格，填写表单，合并文档
---

# PDF Processing

# 什么时候用
用户需要处理 PDF 文件时用……

# 怎么提取文本
1. 用 pdfplumber 提取文本……

# 怎么填表单
……

前置元数据（必填）

文件顶部必须有一段前置元数据：

---
name: skill-name
description: 这个技能是干什么的，什么时候用
---

完整字段示例

---
name: pdf-processing
description: 从 PDF 提取文本和表格，填写表单，合并文档
license: Apache-2.0
compatibility: Python 3.8+, requires pdfplumber, pymupdf
metadata:
  author: example-org
  version: "1.0"
---

字段说明

name 命名规则

name 字段有几个硬性要求需要牢记：

• 长度必须控制在1到64个字符之间
• 只能使用Unicode小写字母、数字和连字符（a-z、0-9、-）
• 不能以 - 开头或结尾
• 不能包含连续的连字符（--）
• 最重要的是，这个名字必须与其父目录的名称完全一致

查看有效和无效的示例，应该会更加清晰：

有效示例：

name: pdf-processing
name: data-analysis
name: code-review

无效示例：

name: PDF-Processing      # 不能有大写字母
name: -pdf                # 不能以连字符开头
name: pdf--processing     # 不能有连续连字符

description 编写建议

description 字段的写法也有讲究：

• 长度在1到1024个字符之间，不能为空
• 需清晰说明技能的功能和应用场景
• 最好包含一些关键词语，以便智能体在判断“是否该使用这个技能”时更容易匹配

指令内容建议结构

至于 SKILL.md 中的指令正文部分，虽然没有强制格式要求，但以下结构在实践中被证明是较为有效的：

# 技能标题

# 概述
详细介绍技能的使用场景、技术背景等

# 前置条件
需要什么环境配置、依赖项

# 工作流程
详细步骤，指导智能体如何执行任务

# 最佳实践
经验总结、注意事项、常见陷阱

# 示例
具体使用案例

# 故障排查
常见问题和解决方案

使用脚本

技能还可以让智能体执行 shell 命令。当然，将可复用的脚本统一放在 scripts/ 目录中是更推荐的做法。

• 一次性命令：直接在指令中编写 shell 命令即可。
• 独立脚本：如果代码有自己的依赖，最好放在 scripts/ 目录下。
• 脚本接口设计：别忘了在指令中清晰说明智能体如何调用脚本以及传递哪些参数。

获取天气技能

光说不练假把式，我们来看一个具体示例——一个调用高德地图 API 查询实时天气的技能。

项目目录结构如下：

weather-skill/
├── SKILL.md        # 技能定义文件
└── weather.py      # API查询文件

获取 API Key

首先，你需要访问高德开放平台，申请一个 Web 服务 API Key。

SKILL.md 文件

---
name: weather-skill
description: 通过高德地图 API 查询指定城市的实时天气信息
license: Apache-2.0
metadata:
  author: zhoupb
  version: "1.0.0"
---

# 城市天气查询技能

## 功能描述
查询指定城市的实时天气信息，包括温度、天气状况、风力风向等。

## 使用方式
直接描述你要查询的天气，例如：
- "[城市]天气怎么样"
- "[城市]今天的天气"
- "[城市]现在多少度"

## 环境变量
使用前请设置高德 API Key：
```bash
export AMAP_MAPS_API_KEY=your_api_key
```

## 安装依赖
```bash
pip install -r requirements.txt
```

## 使用方法
```bash
python weather.py [城市]
```

## 示例输出
```
北京天气：晴
温度：15°C
风力：3 级 北风
湿度：45%
发布时间：2026-03-03 10:00:00
```

## API 说明
使用高德地图天气 API：
- **城市查询 API**: `https://restapi.amap.com/v3/config/district`
- **天气查询 API**: `https://restapi.amap.com/v3/weather/weatherInfo`

## 获取 API Key
访问 高德开放平台 申请 Web 服务 API Key。

weather.py 文件

#!/usr/bin/env python3
"""城市天气查询 - 使用高德 API"""
import os
import sys
import requests

def get_city_code(city_name: str, api_key: str) -> str | None:
    """根据城市名获取城市 code"""
    url = "https://restapi.amap.com/v3/config/district"
    params = {
        "key": api_key,
        "keywords": city_name,
        "subdistrict": 0,
    }
    resp = requests.get(url, params=params, timeout=5)
    resp.raise_for_status()
    data = resp.json()
    if data.get("status") == "1" and data.get("districts"):
        return data["districts"][0]["adcode"]
    return None

def query_weather(city_code: str, api_key: str) -> dict | None:
    """查询城市天气"""
    url = "https://restapi.amap.com/v3/weather/weatherInfo"
    params = {
        "key": api_key,
        "city": city_code,
        "extensions": "base",
    }
    resp = requests.get(url, params=params, timeout=5)
    resp.raise_for_status()
    data = resp.json()
    if data.get("status") == "1" and data.get("lives"):
        return data["lives"][0]
    return None

def main():
    if len(sys.argv) < 2:
        print("用法：python weather.py <城市名>")
        print("示例：python weather.py 北京")
        sys.exit(1)
    city_name = sys.argv[1]
    api_key = os.environ.get("AMAP_MAPS_API_KEY")
    if not api_key:
        print("错误：请设置环境变量 AMAP_MAPS_API_KEY")
        sys.exit(1)
    city_code = get_city_code(city_name, api_key)
    if not city_code:
        print(f"未找到城市：{city_name}")
        sys.exit(1)
    weather = query_weather(city_code, api_key)
    if not weather:
        print(f"无法获取 {city_name} 的天气信息")
        sys.exit(1)
    print(f"{weather['city']}天气：{weather['weather']}")
    print(f"温度：{weather['temperature']}°C")
    print(f"风力：{weather['windpower']} {weather['winddirection']}风")
    print(f"湿度：{weather['humidity']}%")
    print(f"发布时间：{weather['reporttime']}")

if __name__ == "__main__":
    main()

官方技能

最后，如果您想了解和获取更多官方技能示例，可以直接访问 Anthropic 在 GitHub 上的相关仓库进行查阅。