Agent Skills

Agent Skills 是由 Anthropic 于 2025 年确立并推进为开放标准的AI 智能体能力扩展方案，本质是将复杂的 Prompt 工程、领域知识库、执行逻辑与脚本，封装成标准化的文件夹结构（核心为 SKILL.md ），支持模型动态发现、按需加载，大幅提升任务执行的稳定性与 Token 效率，避免重复的 Prompt 粘贴与维护。通过模块化技能封装提升AI智能体的专业能力，让AI模型能够按需加载、自主调用特定任务的能力包。

Agent被视为AI系统的基本构成单元。一个功能完备的智能体必须具备一套核心技能，即 “Agent skills”。这些技能使其不仅能执行简单指令，还能像人类一样进行复杂的任务处理。文档明确指出，这些技能包括：

• 规划能力（Planning）: 智能体能够将复杂的用户目标分解成一系列可执行的子任务和步骤，并制定出合理的行动方案。
• 推理能力（Reasoning）: 智能体具备逻辑思考和因果推断的能力。它能够根据已知信息、环境状态和物理常识，判断如何行动以及为什么要这样行动。这在解决现实世界中的“长尾问题”（罕见或不可预见的场景）时至关重要。
• 执行能力（Execution）: 智能体能够调用工具、API或模型，将规划好的任务步骤转化为具体的操作。例如，编写代码、操控软件、控制机械臂等。
• 研究能力（Research）: 智能体能够主动搜索、获取并整合新信息和知识，以完成当前任务或优化未来的决策。这使其具备持续学习和适应的潜力。

核心设计

Agent Skills 标准的核心思想是技能封装。它将复杂的逻辑简化为一个标准化的文件夹结构：

• 核心文件：每个技能（Skill）是一个独立的文件夹，其心脏是 SKILL.md 文件。该文件以 YAML 格式开头，定义了技能的元数据（如名称、描述、版本），并包含执行该技能的具体指令和逻辑。

• 可选组件：文件夹内还可包含辅助脚本（如 Python 代码）、配置文件、模板等资源。

为了极致优化效率，体系采用了 “渐进式披露” 的加载策略：

• 第一层（启动时）：仅加载所有技能的元数据（如描述），占用极少的 Token。

• 第二层（任务匹配时）：当用户请求与某个技能的描述语义匹配时，系统才动态加载该技能的完整 SKILL.md 内容。

• 第三层（必要时）：在执行过程中，若需要，再进一步加载该技能相关的附加资源或脚本。这种方式最大程度地节省了宝贵的上下文窗口资源，提升了整体运行速度。

其标准调用流程清晰高效：

用户提出请求 → 系统语义匹配技能描述 → 自动加载匹配技能的 SKILL.md → 按照指令执行 → 返回执行结果 。整个过程可在合适场景下由 Claude 等模型自动触发

主要优势与能力

• 专业能力扩展：将领域专业知识（如业务规则、编码规范）封装成可复用单元，把通用Agent转变为专用Agent，支持复杂任务如PDF处理、数据库分析等。

• 确定性执行：通过集成可执行脚本（如Python代码），将需要精准操作的任务交给代码完成，减少LLM幻觉和错误，例如数据清洗或表单填写。

• 开放标准与可移植性：作为简单、开放的标准格式，支持跨产品互操作，一次构建即可在多个兼容Agent产品中复用，避免生态碎片化。

• 安全与控制：通过allowed-tools白名单限制技能可调用的工具，提供安全编码环境，降低误操作风险，例如仅允许文件读取或特定脚本执行。

Agent Skills 与 MCP 的区别

MCP（Model Context Protocol） 是 Anthropic 提出的开放工具连接标准，定义 AI 与外部数据源、API、系统的安全、统一连接方式（MCP Server/Client 架构）；而 Agent Skills 解决的是 “模型拿到数据后该怎么做事”（SOP / 格式 / 规则 / 脚本），二者是互补而非替代关系。

维度	Agent Skills	MCP
核心问题	教模型如何做事（流程、规则、格式、脚本）	让模型安全获取数据 / 调用系统（连接器、工具协议）
主要载体	文件夹 + SKILL.md + reference + scripts	MCP Server/Client + 协议 + 工具清单
Token 成本	低（渐进式披露，按需加载）	取决于工具调用次数与返回数据量
工程边界	适合流程规则、轻量自动化、知识封装	适合系统级连接、权限与审计、生产稳定性
常见误用	把所有制度塞进 SKILL.md （巨型 Prompt）	把 “写作规范 / 汇报模板” 做成工具（过重）
协同方式	MCP 拉数据 → Skills 定格式 / 审计口径；Skills 指挥如何使用 MCP 工具

• Agent Skills 让 Agent 具备“专项能力与一致流程”，核心是 SOP 的可复用与按需加载
• MCP让Agent 具备“连接真实世界系统的标准接口”，核心是prompts/resources/tools 的标准化暴露与治理
• Skills 跑通高频闭环 → 再 MCP 平台化统一接入与治理 → 最后形成可复用的 Agent 基础设施

Demo

还以获取天气信息为例创建一个**SKILL，**并在TRAE（SOLO模式）中调用

设计思路

1. 触发条件：用户输入包含「天气」「气温」「预报」+ 城市名时自动触发

2. 核心功能：

   • 支持中文城市名 / 拼音查询（如「北京」「beijing」）

   • 输出标准化格式的实时天气 + 未来 3 天预报

   • 包含异常处理（城市不存在、API 调用失败、无网络等）

3. 技术选型：使用免费的天气 API，脚本用 Python 编写，通过环境变量管理 API 密钥

目录结构

weather-query/
├── SKILL.md              # 核心配置文件（元数据+执行规则）
└── scripts/
    └── weather_query.py  # 天气查询脚本（调用API+数据格式化）

核心文件

1. SKILL.md（必选）

---
name: weather-query
description: 查询指定城市的实时天气和未来3天预报，支持中文/拼音城市名，输出标准化格式；用户输入包含「天气」「气温」「预报」+城市名时触发
version: 1.0.0
author: otqsoft
dependencies:
  - python >= 3.8
  - requests >= 2.31.0
---

## 天气查询技能执行规则
### 1. 触发后执行步骤
1. 从用户输入中提取目标城市名（优先识别中文，其次拼音）
2. 调用 scripts/weather_query.py 脚本，传入城市名参数
3. 按以下格式整理并输出结果（无数据时标注「暂无数据」）

### 2. 输出格式（必须严格遵守）
#### 【XX市天气】
- 实时天气：温度 XX℃ | 体感 XX℃ | 天气状况（晴/雨/多云等） | 风力 XX 级
- 空气质量：AQI XX | 等级（优/良/轻度污染等）
- 未来3天预报：
  ① X月X日：XX℃~XX℃ | 天气状况 | 风力
  ② X月X日：XX℃~XX℃ | 天气状况 | 风力
  ③ X月X日：XX℃~XX℃ | 天气状况 | 风力

### 3. 异常处理规则
- 城市不存在：输出「未查询到「XX」的天气数据，请检查城市名是否正确」
- API调用失败：输出「天气服务暂时不可用，请稍后重试」
- 无网络/参数错误：输出「查询失败，请检查网络或输入格式（示例：查询北京天气）」

2. scripts/weather_query.py

# -*- coding: utf-8 -*-
"""
天气查询脚本：调用和风天气API，返回标准化天气数据
前置条件：
1. 安装依赖：pip install requests
2. 申请和风天气API Key：https://dev.qweather.com/
3. 配置环境变量：QWEATHER_API_KEY=你的API密钥
"""
import os
import sys
import requests
from typing import Dict, Optional

# 和风天气API配置
BASE_URL = "https://api.qweather.com/"
# 从环境变量读取API密钥（安全起见，不硬编码）
API_KEY = os.getenv("QWEATHER_API_KEY")

def get_city_location(city_name: str) -> Optional[str]:
    """
    根据城市名获取城市ID（和风天气需要城市ID查询天气）
    """
    if not API_KEY:
        print("错误：未配置QWEATHER_API_KEY环境变量")
        return None
    
    url = f"{BASE_URL}geo/v2/city/lookup"
    params = {
        "key": API_KEY,
        "location": city_name,
        "lang": "zh",
        "type": "city"
    }
    
    try:
        response = requests.get(url, params=params, timeout=10)
        response.raise_for_status()
        data = response.json()

        if data.get("code") != "200" or not data.get("location"):
            return None
        
        # 返回第一个匹配的城市ID
        return data["location"][0]["id"], data["location"][0]["lat"], data["location"][0]["lon"]
    
    except requests.exceptions.RequestException as e:
        print(f"获取城市位置失败：{str(e)}")
        return None

def get_weather(city_name: str) -> Optional[Dict]:
    """
    根据城市ID查询实时天气+未来3天预报
    """
    weather_data = {}
    
    city_id, latitude, longitude = get_city_location(city_name)
    if not city_id:
        print(f"未查询到「{city_name}」的天气数据，请检查城市名是否正确")
        return None
    
    # 1. 查询实时天气
    now_url = f"{BASE_URL}v7/weather/now"
    now_params = {"key": API_KEY, "location": city_id, "lang": "zh"}
    try:
        now_resp = requests.get(now_url, params=now_params, timeout=10)
        now_resp.raise_for_status()
        now_data = now_resp.json()
        
        if now_data.get("code") == "200":
            weather_data["now"] = {
                "temp": now_data["now"]["temp"],
                "feels_like": now_data["now"]["feelsLike"],
                "text": now_data["now"]["text"],
                "wind_scale": now_data["now"]["windScale"]
            }
            weather_data["city_name"] = city_name
        else:
            print(f"实时天气查询失败：{now_data.get('code')}")
            return None
    
    except requests.exceptions.RequestException as e:
        print(f"实时天气请求失败：{str(e)}")
        return None
    
    # 2. 查询未来3天预报
    forecast_url = f"{BASE_URL}v7/weather/3d"
    forecast_params = {"key": API_KEY, "location": city_id, "lang": "zh"}
    try:
        forecast_resp = requests.get(forecast_url, params=forecast_params, timeout=10)
        forecast_resp.raise_for_status()
        forecast_data = forecast_resp.json()
        
        if forecast_data.get("code") == "200":
            weather_data["forecast"] = forecast_data["daily"][:3]  # 取前3天
        else:
            print(f"预报查询失败：{forecast_data.get('code')}")
            return None
    
    except requests.exceptions.RequestException as e:
        print(f"预报请求失败：{str(e)}")
        return None
    
    # 3. 查询空气质量
    aqi_url = f"{BASE_URL}airquality/v1/current/{latitude}/{longitude}"
    aqi_params = {"key": API_KEY}
    try:
        aqi_resp = requests.get(aqi_url, params=aqi_params, timeout=10)
        aqi_resp.raise_for_status()
        aqi_data = aqi_resp.json()
        
        weather_data["aqi"] = {
            "value": aqi_data["indexes"][0]["aqi"],
            "level": aqi_data["indexes"][0]["category"]
        }
    except requests.exceptions.RequestException:
        # 空气质量非必需，失败不影响主功能
        weather_data["aqi"] = {"value": "暂无", "level": "暂无"}
    
    return weather_data

def format_weather_output(weather_data: Dict) -> str:
    """
    按SKILL.md规定的格式格式化输出
    """
    if not weather_data:
        return "查询失败：未获取到天气数据"
    
    # 构建输出字符串
    output = f"【{weather_data['city_name']}天气】\n"
    now = weather_data["now"]
    output += f"- 实时天气：温度 {now['temp']}℃ | 体感 {now['feels_like']}℃ | 天气状况（{now['text']}） | 风力 {now['wind_scale']} 级\n"
    
    aqi = weather_data["aqi"]
    output += f"- 空气质量：AQI {aqi['value']} | 等级（{aqi['level']}）\n"
    
    output += "- 未来3天预报：\n"
    for i, day in enumerate(weather_data["forecast"], 1):
        date = day["fxDate"].replace("-", "月") + "日"
        output += f"  ① {date}：{day['tempMin']}℃~{day['tempMax']}℃ | {day['textDay']} | 风力 {day['windScaleDay']} 级\n"
    
    return output

def main():
    """
    脚本主入口：接收城市名参数，输出格式化天气信息
    """
    # 检查参数
    if len(sys.argv) < 2:
        print("使用方法：python weather_query.py <城市名>")
        sys.exit(1)
    
    city_name = sys.argv[1]
    
    
    # 查询天气数据
    weather_data = get_weather(city_name)
    if not weather_data:
        print("天气服务暂时不可用，请稍后重试")
        sys.exit(1)
    
    # 3. 格式化输出
    print(format_weather_output(weather_data))

if __name__ == "__main__":
    main()

TRAE

先将TRAE升级到最新版，目前只有在SOLO模式可以使用SKILL。打开【设置】选择【规则和技能】，在技能中点击【创建】，然后选择你的SKILL.MD文件

确认之后，在SOLO模式中输入关于天气信息的提问，如：