完全开源的语言模型学习记录--agent skill规范研究

snakecy2026-06-27 8:11

文章目录

  • [Agent Skill 书写规范完整详解](#Agent Skill 书写规范完整详解)
    • 一、基础概念定义
    • 二、整体文件/结构体顶层书写规范
      • [1. 文件格式选择与命名规范](#1. 文件格式选择与命名规范)
      • [2. 顶层固定字段（所有Skill必须包含）](#2. 顶层固定字段（所有Skill必须包含）)
    • [三、核心：parameters 入参书写规范（最关键）](#三、核心：parameters 入参书写规范（最关键）)
      • [3.1 parameters 顶层子字段强制规范](#3.1 parameters 顶层子字段强制规范)
      • [3.2 单个参数 property 书写标准（每个参数统一结构）](#3.2 单个参数 property 书写标准（每个参数统一结构）)
      • [3.3 参数书写禁止项](#3.3 参数书写禁止项)
    • [四、返回值 response 书写规范](#四、返回值 response 书写规范)
    • [五、description 描述统一写作规范（决定Agent会不会正确调用）](#五、description 描述统一写作规范（决定Agent会不会正确调用）)
      • [5.1 技能顶层 description 写作模板](#5.1 技能顶层 description 写作模板)
      • [5.2 参数description写作模板](#5.2 参数description写作模板)
      • [5.3 描述通用禁忌](#5.3 描述通用禁忌)
    • [六、examples 调用示例书写规范](#六、examples 调用示例书写规范)
    • [七、YAML / JSON 格式语法书写规范](#七、YAML / JSON 格式语法书写规范)
      • [7.1 YAML规范（推荐）](#7.1 YAML规范（推荐）)
      • [7.2 JSON规范](#7.2 JSON规范)
    • [八、代码层 Skill 函数实现书写规范（Python示例）](#八、代码层 Skill 函数实现书写规范（Python示例）)
    • 九、分类、标签、权限扩展字段规范
    • 十、完整标准YAML模板（可直接复用）
    • 十一、常见书写错误汇总
    • 十二、不同框架差异化补充规范

Agent Skill 书写规范完整详解

一、基础概念定义

Agent Skill（智能体技能）是大模型Agent可调用的工具/能力单元，包含函数描述、入参、出参、触发规则、调用逻辑、格式约束整套标准化定义，分为JSON/YAML结构化定义规范 、自然语言描述规范 、代码实现规范三大体系，行业主流遵循 OpenAI Function Calling、Anthropic Tool、阿里Agent、LangChain 通用标准。

二、整体文件/结构体顶层书写规范

1. 文件格式选择与命名规范

  1. 文件后缀
    • 配置定义：.yaml / .yml（可读性优先，生产首选）、.json（程序解析优先）
    • 代码实现：.py/.ts/.go（对应编程语言）
    • 文档说明：skill_readme.md
  2. 命名规则
    • 技能ID/文件名：小写蛇形命名 snake_case ，禁止驼峰、空格、中文、特殊符号
      示例：weather_query、database_insert_user
    • 技能分组目录：按业务分层 skills/tool/weather/、skills/internal/calculate/
    • 禁止：WeatherQuery、天气查询、weather-query（横杠部分平台不兼容）

2. 顶层固定字段（所有Skill必须包含）

字段 类型 书写规范要求 示例
name string 技能唯一标识，snake_case，全局不可重复，长度2--64字符 stock_price_query
description string 核心用途描述，只写功能，不写参数，清晰告知Agent什么时候调用本技能；控制50--300字 查询指定股票代码实时当日开盘、收盘、涨跌价格
version string 语义化版本 x.y.z，更新技能必须升版 1.2.0
author string 开发人/团队，可选 agent_dev_team
visibility enum public/private；public允许Agent自主调用，private仅内部流程调用 public
parameters object 入参结构体，强制标准化JSON Schema，下文详细规范 -
response object 返回结果结构定义，可选复杂技能必填 -
examples array 调用示例，提升模型识别准确率，至少1组 -
limitation string 调用限制、边界条件，必填 仅支持A股股票，不支持美股；单次最多查5支股票

三、核心：parameters 入参书写规范（最关键）

采用 JSON Schema 标准 ，是各大模型Agent统一兼容标准，内部包含 type、properties、required、additionalProperties 四部分。

3.1 parameters 顶层子字段强制规范

  1. type：固定值 object（所有技能入参统一是对象）
  2. properties：存放每个入参的详细定义
  3. required：字符串数组，列出必填参数key；无必填则为空数组 []
  4. additionalProperties：固定 false，禁止Agent传入未定义参数，防止乱传参报错

3.2 单个参数 property 书写标准（每个参数统一结构）

每个参数key使用snake_case，内部固定字段：

  1. type：基础数据类型，仅允许 string/integer/number/boolean/array/object，不混合模糊类型
  2. description：参数详细说明，包含：含义、取值范围、格式要求、特殊约束
  3. 可选约束字段（按需添加）
    • enum：枚举值，参数只能取列表内值，固定选项必加
    • minimum/maximum：数字上下限
    • minLength/maxLength：字符串长度限制
    • items：array数组内部元素类型定义（数组必填）
    • format：格式约束，常用 date/date-time/email/uuid/float
    • default：参数缺省值，不传时自动填充
标准参数示例
yaml 复制代码 
parameters:
  type: object
  required:
    - stock_code
    - market_type
  additionalProperties: false
  properties:
    stock_code:
      type: string
      description: A股股票6位数字代码，如000001、600036，不可为空
      minLength: 6
      maxLength: 6
    market_type:
      type: string
      description: 股票市场分类，仅支持沪深A股
      enum: [sh, sz]
    query_date:
      type: string
      description: 查询日期，格式YYYY-MM-DD，不传默认今日
      format: date
      default: "2026-06-26"

3.3 参数书写禁止项

  1. 描述模糊：填日期 → 错误；查询行情日期，标准YYYY-MM-DD格式 → 正确
  2. 混合多type：type: [string, null] 部分老模型不兼容，改用加default空字符串
  3. 不写枚举约束：固定选项参数不加enum，会导致Agent乱传非法值
  4. 不限制长度/范围：手机号、编码、ID类参数必须加长度限制

四、返回值 response 书写规范

复杂工具必须定义返回结构，简单工具可省略，但生产环境建议统一规范：

  1. 顶层type统一 object
  2. 分层清晰，区分 code（状态码）、msg（提示信息）、data（业务数据）
  3. data内部字段同样遵循snake_case、JSON Schema约束
yaml 复制代码 
response:
  type: object
  properties:
    code:
      type: integer
      description: 状态码，200成功，400参数错误，500接口异常
    msg:
      type: string
      description: 请求结果说明
    data:
      type: object
      properties:
        stock_code:
          type: string
        current_price:
          type: number
        up_rate:
          type: number

五、description 描述统一写作规范（决定Agent会不会正确调用）

5.1 技能顶层 description 写作模板

结构：能力范围 + 适用场景 + 不能做什么

错误示例：查天气

标准规范示例：

本技能用于查询国内城市当日及未来3天天气预报，可返回温度、降水、风力；仅支持国内地级市及以上城市，无法查询国外地区、历史往年天气数据。

5.2 参数description写作模板

结构：字段含义 + 格式/范围 + 特殊规则

错误示例：城市名字

标准示例：

需要查询天气的城市中文名称，仅限中国大陆地级市，例如北京、上海、成都，不支持区县、乡镇名称

5.3 描述通用禁忌

  1. 不使用模糊代词："相关、一些、大概"
  2. 不写代码逻辑、实现细节（Agent不需要知道底层怎么实现）
  3. 不写过长冗余文字，控制单行可读性
  4. 明确区分支持/不支持边界，减少模型幻觉调用

六、examples 调用示例书写规范

作用：给模型提供Few-shot样例，大幅提升参数填充准确率，规范要求：

  1. 每条示例包含 input（入参）、output（返回结果）、scene（使用场景说明）
  2. 至少1条正常调用示例；有枚举、异常场景需补充异常示例
yaml 复制代码 
examples:
  - scene: 查询上海A股600036当日股价
    input:
      stock_code: "600036"
      market_type: "sh"
    output:
      code: 200
      msg: "查询成功"
      data:
        current_price: 32.15

七、YAML / JSON 格式语法书写规范

7.1 YAML规范（推荐）

  1. 缩进统一2空格，禁止Tab制表符
  2. 字符串无特殊字符可省略引号；包含数字开头、冒号、空格必须加双引号
  3. 数组短横线-后必须加空格
  4. 键名后冒号:必须加空格再写值
  5. 长文本description使用 | 换行，保持排版整洁
yaml 复制代码 
description: |
  本技能用于查询国内城市天气预报，
  支持未来3天温度、降雨、风力数据，
  仅中国大陆城市可用。

7.2 JSON规范

  1. 键名必须双引号，禁止单引号
  2. 末尾不能有多余逗号
  3. 格式化分层缩进2空格，禁止压缩单行

八、代码层 Skill 函数实现书写规范（Python示例）

如果Skill需要绑定可执行代码，函数必须遵循：

  1. 函数名：snake_case，与skill name保持一致
  2. 参数名：与配置文件parameters字段完全同名
  3. 增加标准文档字符串 docstring，对齐配置description
  4. 入参校验前置：长度、枚举、格式校验，抛出标准化错误
  5. 返回统一结构体，对齐response定义
python 复制代码 
def weather_query(city: str, query_date: str = "2026-06-26") -> dict:
    """
    国内城市天气预报查询技能
    仅支持中国大陆地级市，返回3天温度、降水、风力
    :param city: 城市中文名称，地级市
    :param query_date: 查询日期 YYYY-MM-DD
    :return: 标准化天气返回结构体
    """
    # 参数校验
    if len(city) < 2:
        return {"code": 400, "msg": "城市名称非法", "data": {}}
    # 业务逻辑省略
    return {"code": 200, "msg": "成功", "data": {...}}

九、分类、标签、权限扩展字段规范

  1. tags：数组，小写蛇形，用于Agent技能检索分类
    tags: [stock, finance, query]
  2. priority：数字1--10，1最高优先级，复杂决策Agent使用
  3. timeout：integer，调用超时毫秒，默认3000
  4. auth_required：boolean，true代表调用需要鉴权token

十、完整标准YAML模板（可直接复用）

yaml 复制代码 
# 技能唯一标识 snake_case
name: city_weather_query
version: 1.0.0
author: agent_platform
visibility: public
timeout: 3000
auth_required: false
tags:
  - weather
  - life_service
# 技能整体描述
description: |
  查询中国大陆地级市未来3天天气预报，返回日间夜间温度、降水概率、风向风力。
  不支持国外城市、区县乡镇、历史天气查询。
limitation: 单次仅可传入1个城市，不支持批量查询
# 入参标准JSON Schema
parameters:
  type: object
  required:
    - city_name
  additionalProperties: false
  properties:
    city_name:
      type: string
      description: 中国大陆地级市完整中文名称，如北京、广州，不可填写区县
      minLength: 2
      maxLength: 10
    forecast_days:
      type: integer
      description: 需要预报天数，仅支持1/2/3天
      enum: [1, 2, 3]
      default: 3
# 返回结构定义
response:
  type: object
  properties:
    code:
      type: integer
      description: 200成功，400参数错误，500服务异常
    msg:
      type: string
    data:
      type: array
      items:
        type: object
        properties:
          date:
            type: string
            format: date
          temp_low:
            type: integer
          temp_high:
            type: integer
# 调用示例
examples:
  - scene: 查询北京未来3天天气
    input:
      city_name: "北京"
      forecast_days: 3
    output:
      code: 200
      msg: "天气查询成功"
      data:
        - date: "2026-06-26"
          temp_low: 22
          temp_high: 35

十一、常见书写错误汇总

  1. 命名混用驼峰/横杠/中文：WeatherQuery、weather-query
  2. parameters不写additionalProperties: false，Agent传入无效参数
  3. 固定选项参数不配置enum，模型传入非法值
  4. description写底层实现逻辑，不写业务适用边界
  5. 无limitation字段，Agent超范围调用技能（如查国外天气）
  6. 数组参数不写items，模型不清楚数组内部结构
  7. 日期、编码类参数不添加format、长度限制
  8. YAML使用Tab缩进、键后缺少空格

十二、不同框架差异化补充规范

  1. OpenAI Function Calling
    • 字段完全兼容上述标准，顶层字段仅保留name/description/parameters即可，多余字段会被忽略
  2. LangChain Tool
    • 额外增加return_direct布尔值：true代表工具结果直接返回用户，不交给大模型二次总结
  3. 阿里通义Agent / 文心智能体
    • 支持新增skill_type字段：api/code/dataset区分技能类型
  4. Anthropic Claude Tool
    • 参数描述支持更长文本，推荐在description中增加失败场景说明

参考： https://swarmskills.openjiuwen.com/skills/c7dc8f03a5df49d78d2615f888495b11

热门推荐
012026年6月AI大模型全景报告：GPT-5.6、Claude Opus 4.8、Gemini 3.5，中美AI三足鼎立谁主沉浮？022026年6月AI行业全景：从百模大战到Agent元年，这30天发生了什么？032026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf04【AI】2026 年具身智能模型和世界模型总结05Trae国际版与国内版深度测评：AI原生IDE的双生花06飞书长连接_事件订阅（接收消息，审批任务状态变更）07Claude Code、Codex、Cursor三分天下：2026年AI编程Agent生态全景剖析08GitHub 镜像站点092026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？102026年AI架构实战：彻底解决OpenAI接口超时与封号，Python调用GPT-5.2/Sora2企业级架构详解（附源码+压测报告）