文章目录Agent Skill 书写规范完整详解一、基础概念定义二、整体文件/结构体顶层书写规范1. 文件格式选择与命名规范2. 顶层固定字段所有Skill必须包含三、核心parameters 入参书写规范最关键3.1 parameters 顶层子字段强制规范3.2 单个参数 property 书写标准每个参数统一结构标准参数示例3.3 参数书写禁止项四、返回值 response 书写规范五、description 描述统一写作规范决定Agent会不会正确调用5.1 技能顶层 description 写作模板5.2 参数description写作模板5.3 描述通用禁忌六、examples 调用示例书写规范七、YAML / JSON 格式语法书写规范7.1 YAML规范推荐7.2 JSON规范八、代码层 Skill 函数实现书写规范Python示例九、分类、标签、权限扩展字段规范十、完整标准YAML模板可直接复用十一、常见书写错误汇总十二、不同框架差异化补充规范Agent Skill 书写规范完整详解一、基础概念定义Agent Skill智能体技能是大模型Agent可调用的工具/能力单元包含函数描述、入参、出参、触发规则、调用逻辑、格式约束整套标准化定义分为JSON/YAML结构化定义规范、自然语言描述规范、代码实现规范三大体系行业主流遵循 OpenAI Function Calling、Anthropic Tool、阿里Agent、LangChain 通用标准。二、整体文件/结构体顶层书写规范1. 文件格式选择与命名规范文件后缀配置定义.yaml/.yml可读性优先生产首选、.json程序解析优先代码实现.py/.ts/.go对应编程语言文档说明skill_readme.md命名规则技能ID/文件名小写蛇形命名 snake_case禁止驼峰、空格、中文、特殊符号示例weather_query、database_insert_user技能分组目录按业务分层skills/tool/weather/、skills/internal/calculate/禁止WeatherQuery、天气查询、weather-query横杠部分平台不兼容2. 顶层固定字段所有Skill必须包含字段类型书写规范要求示例namestring技能唯一标识snake_case全局不可重复长度2–64字符stock_price_querydescriptionstring核心用途描述只写功能不写参数清晰告知Agent什么时候调用本技能控制50–300字查询指定股票代码实时当日开盘、收盘、涨跌价格versionstring语义化版本x.y.z更新技能必须升版1.2.0authorstring开发人/团队可选agent_dev_teamvisibilityenumpublic/privatepublic允许Agent自主调用private仅内部流程调用publicparametersobject入参结构体强制标准化JSON Schema下文详细规范-responseobject返回结果结构定义可选复杂技能必填-examplesarray调用示例提升模型识别准确率至少1组-limitationstring调用限制、边界条件必填仅支持A股股票不支持美股单次最多查5支股票三、核心parameters 入参书写规范最关键采用JSON Schema 标准是各大模型Agent统一兼容标准内部包含type、properties、required、additionalProperties四部分。3.1 parameters 顶层子字段强制规范type固定值object所有技能入参统一是对象properties存放每个入参的详细定义required字符串数组列出必填参数key无必填则为空数组[]additionalProperties固定false禁止Agent传入未定义参数防止乱传参报错3.2 单个参数 property 书写标准每个参数统一结构每个参数key使用snake_case内部固定字段type基础数据类型仅允许string/integer/number/boolean/array/object不混合模糊类型description参数详细说明包含含义、取值范围、格式要求、特殊约束可选约束字段按需添加enum枚举值参数只能取列表内值固定选项必加minimum/maximum数字上下限minLength/maxLength字符串长度限制itemsarray数组内部元素类型定义数组必填format格式约束常用date/date-time/email/uuid/floatdefault参数缺省值不传时自动填充标准参数示例parameters:type:objectrequired:-stock_code-market_typeadditionalProperties:falseproperties:stock_code:type:stringdescription:A股股票6位数字代码如000001、600036不可为空minLength:6maxLength:6market_type:type:stringdescription:股票市场分类仅支持沪深A股enum:[sh,sz]query_date:type:stringdescription:查询日期格式YYYY-MM-DD不传默认今日format:datedefault:2026-06-263.3 参数书写禁止项描述模糊填日期→ 错误查询行情日期标准YYYY-MM-DD格式→ 正确混合多typetype: [string, null]部分老模型不兼容改用加default空字符串不写枚举约束固定选项参数不加enum会导致Agent乱传非法值不限制长度/范围手机号、编码、ID类参数必须加长度限制四、返回值 response 书写规范复杂工具必须定义返回结构简单工具可省略但生产环境建议统一规范顶层type统一object分层清晰区分code状态码、msg提示信息、data业务数据data内部字段同样遵循snake_case、JSON Schema约束response:type:objectproperties:code:type:integerdescription:状态码200成功400参数错误500接口异常msg:type:stringdescription:请求结果说明data:type:objectproperties:stock_code:type:stringcurrent_price:type:numberup_rate:type:number五、description 描述统一写作规范决定Agent会不会正确调用5.1 技能顶层 description 写作模板结构能力范围 适用场景 不能做什么错误示例查天气标准规范示例本技能用于查询国内城市当日及未来3天天气预报可返回温度、降水、风力仅支持国内地级市及以上城市无法查询国外地区、历史往年天气数据。5.2 参数description写作模板结构字段含义 格式/范围 特殊规则错误示例城市名字标准示例需要查询天气的城市中文名称仅限中国大陆地级市例如北京、上海、成都不支持区县、乡镇名称5.3 描述通用禁忌不使用模糊代词“相关、一些、大概”不写代码逻辑、实现细节Agent不需要知道底层怎么实现不写过长冗余文字控制单行可读性明确区分支持/不支持边界减少模型幻觉调用六、examples 调用示例书写规范作用给模型提供Few-shot样例大幅提升参数填充准确率规范要求每条示例包含input入参、output返回结果、scene使用场景说明至少1条正常调用示例有枚举、异常场景需补充异常示例examples:-scene:查询上海A股600036当日股价input:stock_code:600036market_type:shoutput:code:200msg:查询成功data:current_price:32.15七、YAML / JSON 格式语法书写规范7.1 YAML规范推荐缩进统一2空格禁止Tab制表符字符串无特殊字符可省略引号包含数字开头、冒号、空格必须加双引号数组短横线-后必须加空格键名后冒号:必须加空格再写值长文本description使用|换行保持排版整洁description:|本技能用于查询国内城市天气预报 支持未来3天温度、降雨、风力数据 仅中国大陆城市可用。7.2 JSON规范键名必须双引号禁止单引号末尾不能有多余逗号格式化分层缩进2空格禁止压缩单行八、代码层 Skill 函数实现书写规范Python示例如果Skill需要绑定可执行代码函数必须遵循函数名snake_case与skill name保持一致参数名与配置文件parameters字段完全同名增加标准文档字符串 docstring对齐配置description入参校验前置长度、枚举、格式校验抛出标准化错误返回统一结构体对齐response定义defweather_query(city:str,query_date:str2026-06-26)-dict: 国内城市天气预报查询技能 仅支持中国大陆地级市返回3天温度、降水、风力 :param city: 城市中文名称地级市 :param query_date: 查询日期 YYYY-MM-DD :return: 标准化天气返回结构体 # 参数校验iflen(city)2:return{code:400,msg:城市名称非法,data:{}}# 业务逻辑省略return{code:200,msg:成功,data:{...}}九、分类、标签、权限扩展字段规范tags数组小写蛇形用于Agent技能检索分类tags: [stock, finance, query]priority数字1–101最高优先级复杂决策Agent使用timeoutinteger调用超时毫秒默认3000auth_requiredbooleantrue代表调用需要鉴权token十、完整标准YAML模板可直接复用# 技能唯一标识 snake_casename:city_weather_queryversion:1.0.0author:agent_platformvisibility:publictimeout:3000auth_required:falsetags:-weather-life_service# 技能整体描述description:|查询中国大陆地级市未来3天天气预报返回日间夜间温度、降水概率、风向风力。 不支持国外城市、区县乡镇、历史天气查询。limitation:单次仅可传入1个城市不支持批量查询# 入参标准JSON Schemaparameters:type:objectrequired:-city_nameadditionalProperties:falseproperties:city_name:type:stringdescription:中国大陆地级市完整中文名称如北京、广州不可填写区县minLength:2maxLength:10forecast_days:type:integerdescription:需要预报天数仅支持1/2/3天enum:[1,2,3]default:3# 返回结构定义response:type:objectproperties:code:type:integerdescription:200成功400参数错误500服务异常msg:type:stringdata:type:arrayitems:type:objectproperties:date:type:stringformat:datetemp_low:type:integertemp_high:type:integer# 调用示例examples:-scene:查询北京未来3天天气input:city_name:北京forecast_days:3output:code:200msg:天气查询成功data:-date:2026-06-26temp_low:22temp_high:35十一、常见书写错误汇总命名混用驼峰/横杠/中文WeatherQuery、weather-queryparameters不写additionalProperties: falseAgent传入无效参数固定选项参数不配置enum模型传入非法值description写底层实现逻辑不写业务适用边界无limitation字段Agent超范围调用技能如查国外天气数组参数不写items模型不清楚数组内部结构日期、编码类参数不添加format、长度限制YAML使用Tab缩进、键后缺少空格十二、不同框架差异化补充规范OpenAI Function Calling字段完全兼容上述标准顶层字段仅保留name/description/parameters即可多余字段会被忽略LangChain Tool额外增加return_direct布尔值true代表工具结果直接返回用户不交给大模型二次总结阿里通义Agent / 文心智能体支持新增skill_type字段api/code/dataset区分技能类型Anthropic Claude Tool参数描述支持更长文本推荐在description中增加失败场景说明参考 https://swarmskills.openjiuwen.com/skills/c7dc8f03a5df49d78d2615f888495b11