编写一个优秀的 Agent Skills（智能体技能/工具）

编写一个优秀的 Agent Skills（智能体技能/工具），本质上是为大模型（LLM）编写一份清晰的“使用说明书”。大模型通过阅读技能的名称和描述，来判断在什么情况下调用它。

通常，一个完整的 Agent Skill 包含四个核心要素：名称 (Name)、描述 (Description)、参数 (Parameters) 和 输出 (Output)。

1. 技能编写的标准模板 (JSON 格式)

大多数现代框架（如 LangChain, OpenAI Functions, Vercel AI SDK）都遵循类似的定义方式：

JSON

{
  "name": "get_weather_data",
  "description": "当用户询问特定城市的实时天气或预报时使用此工具。",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "城市或地区的名称，例如：北京, 东京, 伦敦"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "温度单位，默认为摄氏度"
      }
    },
    "required": ["location"]
  }
}

2. 编写高质量技能的 3 个原则

🎯 描述要“场景化” (Scenario-driven)

不要只写“这是一个搜索工具”，要告诉模型什么时候该用它。

• 坏例子： search_google – “在谷歌上搜索内容。”
• 好例子： search_web – “当用户提出的问题涉及实时新闻、最新政策或模型训练截止日期之后的事实，且当前知识库无法回答时，请调用此工具。”

🛠 参数要“最小化”且“具体化”

确保参数名称通俗易懂，并利用 enum（枚举）限制模型胡乱生成参数。

• 如果参数是日期，说明格式（如：YYYY-MM-DD）。
• 如果参数有固定选项，务必列出。

🛡 增加边界说明 (Guardrails)

在描述中加入一些限制条件，防止模型滥用技能。

• 例如：“此工具仅能查询过去 30 天内的财务报表，无法查询更早的数据。”

3. 实战案例：编写一个“会议预订”技能

假设你正在为一个办公助手编写技能：

技能定义

• 名称: schedule_meeting
• 描述: 用于在用户的日历中创建新会议。在调用前，必须确保已经明确了会议的主题、开始时间和持续时间。
• 参数:
  • topic: (String) 会议标题。
  • start_time: (String) ISO 8601 格式的开始时间（如 2024-05-20T10:00:00Z）。
  • duration_minutes: (Integer) 会议时长，以分钟为单位。
  • attendees: (Array) 参与者的邮箱列表。

4. 给开发者的建议

如果您正在开发自己的 Agent，可以参考以下分类来构建技能库：