1. 技能文档的本质认知
在AI Agent开发领域,SKILL.md文件绝不是简单的API说明书或功能清单。它本质上是一个动态的能力契约,需要同时满足三个核心诉求:
- 机器可解析的结构化数据(供Agent系统自动加载)
- 人类可理解的语义化描述(供开发者协作维护)
- 场景化的能力边界定义(供任务调度系统决策)
我见过太多团队把技能文档写成"函数签名+几句注释"的形式,这会导致三个典型问题:
- Agent无法自主判断何时调用该技能
- 技能组合时出现参数语义冲突
- 异常场景下产生不可控行为
2. 技能元数据规范设计
2.1 基础声明区块
markdown复制<!-- METADATA -->
- identifier: weather_query
- version: 1.2.0
- capability: environment_awareness
- privacy_level: public_data
- latency: <500ms
- required_context:
- location
- timezone
- output_schema:
- temperature: float
- humidity: integer
- precipitation_prob: percentage
关键设计要点:
- capability需要遵循统一的分类体系(建议采用IEEE P1872.2标准)
- privacy_level应该明确定义数据敏感度(internal/public_data/personal_data等)
- latency声明直接影响调度优先级,需要实测P99值
2.2 自然语言描述规范
markdown复制## [天气查询] 当用户询问与当前或未来天气状况相关的问题时触发
**典型场景**:
- "今天需要带伞吗?"
- "明天上海气温多少?"
- "旧金山下周会下雪吗?"
**不适用场景**:
- 历史天气数据查询(需调用weather_archive)
- 气象学术语解释(需调用science_glossary)
经验教训:
- 必须包含否定用例(negative examples)
- 场景描述要具体到真实对话片段
- 区分显式触发(直接提问)和隐式触发(对话上下文推导)
3. 参数处理进阶实践
3.1 多模态参数处理
markdown复制<!-- PARAMETERS -->
- location:
- type: string
- formats:
- 城市名("北京")
- 行政区划("上海市浦东新区")
- 地理坐标("39.9042,116.4074")
- normalization:
- 中文转拼音
- 别名映射("帝都"→"北京")
- fallback:
- 用户最近提及的位置
- IP地理定位
3.2 参数依赖关系
markdown复制- date:
- type: date
- relative: true
- constraints:
- future_only: true
- max_range: 7d
- dependencies:
- timezone: required
- location: optional
避坑指南:
- 必须声明时空参数的相对性(relative/absolute)
- 约束条件要用机器可解析的表达式
- 依赖关系要区分强/弱依赖
4. 异常处理与边界控制
4.1 错误代码体系
markdown复制<!-- ERROR_CODES -->
- 4001: 地理位置解析失败
- recovery: 要求用户澄清
- fallback: 使用IP定位
- 5003: 气象数据过期
- retry: 3次
- timeout: 2s
4.2 能力边界声明
markdown复制**物理限制**:
- 仅支持地表以上10米至对流层底部的气象数据
- 空间分辨率不超过5km×5km
**数据时效性**:
- 实时数据: ±15分钟
- 预报数据: 每日8时/20时更新
5. 版本管理与技能进化
5.1 变更日志规范
markdown复制## Version 1.2.0 (2024-03-15)
- 新增: 支持台风路径查询
- 废弃: 移除紫外线指数(迁移至health_advisor)
- 变更: 降水概率精度从5%调整为1%
5.2 技能测试用例
markdown复制<!-- TEST_CASES -->
- input: "朝阳区明天会下雨吗"
expect:
location: "北京市朝阳区"
date: tomorrow
output_contains: "precipitation_prob"
- input: "纽约现在气温"
expect:
timezone: "America/New_York"
latency: <300ms
6. 技能组合设计模式
6.1 前置技能声明
markdown复制<!-- PREREQUISITES -->
- location_parse: 1.1.0
- time_converter: 2.0.0
6.2 后置技能建议
markdown复制<!-- FOLLOWUPS -->
- clothing_suggestion:
condition: temperature < 10
- travel_alert:
condition: precipitation_prob > 0.7
实战建议:
- 前置技能要指定最低版本号
- 后置条件使用可量化的阈值
- 避免循环依赖(可通过技能图谱工具检测)
7. 性能优化记录
markdown复制**缓存策略**:
- 实时数据: 60s TTL
- 预报数据: 6h TTL
- 缓存键: md5(location+date+timezone)
**降级方案**:
- 主API超时: 切换至CMAC数据源
- 数据缺失: 返回邻近区域数据(标注估算范围)
8. 合规性声明
markdown复制**数据来源**:
- 中国: 中央气象台CMA
- 海外: NOAA
**使用限制**:
- 商业用途需额外授权
- 每日调用上限: 10,000次/IP
9. 文档维护建议
- 使用Swagger UI自动生成交互式文档
- 集成jest测试框架验证示例代码
- 通过git hook强制要求变更日志更新
- 文档与代码实现必须同步更新(建议使用OpenAPI规范)
10. 技能效果评估
markdown复制**准确率指标**:
- 温度预测: ±1℃ (24h内)
- 降水预测: 85%召回率
**用户体验指标**:
- 首屏时间: <800ms
- 会话完成率: 92%
关键提示:所有量化指标必须包含测量方法和样本量(如"基于10万次真实对话统计")