1. Agent Skill 基础概念解析

Agent Skill 本质上是一种模块化的能力扩展机制，它让AI助手能够像人类专家一样掌握特定领域的知识和操作流程。想象你新入职一家公司时，HR会给你一本员工手册——这本手册不会教你如何呼吸或走路，但会详细说明公司特有的报销流程、门禁使用规范等。Agent Skill就是AI领域的"员工手册"，它专注于补充AI原本不具备的领域专有知识。

1.1 Skill的核心构成要素

一个标准的Skill目录包含以下结构（以物流客服场景为例）：

logistics-customer-service/ ├── SKILL.md # 核心指令文件 ├── scripts/ │ ├── query_logistics.py # 物流查询脚本 │ └── validate_status.py # 状态验证工具 ├── references/ │ ├── CARRIERS.md # 合作快递公司规范 │ └── STATUS_CODES.md # 状态码对照表 └── assets/ ├── reply_template.md # 回复话术模板 └── shipping_policy.pdf # 物流政策文档

这种结构设计体现了"按需加载"的工程思想。就像医生问诊时，不会一次性搬出所有医学典籍，而是根据患者症状逐步调取相关资料。Agent同样只在必要时加载特定资源，这种设计能显著降低内存消耗和提高响应速度。

关键经验：Skill目录命名建议全部使用小写字母和连字符（如>name: logistics-customer-service description: 当用户查询订单物流状态、发货时效或快递公司信息时使用此技能

技能激活阶段
当用户提问涉及"我的包裹到哪了"时，Agent会匹配description中的关键词，完整加载SKILL.md文件。这就像医生听到患者说"肚子疼"后，才去翻阅胃肠疾病的诊疗手册。

资源调用阶段
根据SKILL.md中的指令，按需加载references或执行scripts。例如发现用户询问"申通快递的时效"，就会加载references/CARRIERS.md文件。

实测数据显示，这种分层加载机制能使Agent的内存占用减少40%-60%，特别在处理数十个Skill时优势明显。

2. SKILL.md 文件编写实战

2.1 YAML前言的规范写法

YAML前言是Skill的"身份证"，需要包含以下关键信息（带*为必填项）：

字段	示例值	说明
name*	finance-report	遵循DNS命名规范：小写、连字符、无空格
description*	当用户请求生成季度财务报告时使用，支持PDF/Excel格式输出	用祈使句说明触发条件
license	MIT	建议明确许可证，避免法律风险
compatibility	requires: pandas>=1.5.0	声明依赖环境
metadata.author	@zhangsan	方便团队协作时追溯责任人

常见错误案例：

# 错误示范1：description过于宽泛 description: 处理财务数据 # 正确写法 description: 当用户要求分析季度营收、生成损益表或比较年度财务数据时使用此技能

避坑指南：description字段建议先列出3-5个典型用户问题，再用"当...时"的句式归纳。可用以下模板： "当用户[动作A]、[动作B]或询问[问题C]时使用此技能，特别适用于[场景D]的情况"

2.2 Markdown指令的编写技巧

指令正文是Skill的"大脑"，需要平衡详尽性和可操作性。以下是经过验证的有效结构：

2.2.1 条件判断模块

## 适用场景判断 满足以下任一条件时应用本技能： - 用户问题包含"物流"、"快递"、"包裹"等关键词 - 上下文出现订单号且缺少物流信息 - 用户明确提及合作快递公司（中通/圆通/申通） 排除情况： - 仅询问价格、退换货政策（应转接售后技能） - 涉及国际物流（本技能仅限国内）

2.2.2 工作流引擎

## 物流查询流程 1. 【订单提取】识别用户提供的订单号格式： - 纯数字且≥8位 → 直接使用 - 含字母前缀 → 去除字母后使用（如"JD123"取"123"） 2. 【API调用】执行脚本获取数据： ```bash python scripts/query.py --order {{order_id}} --carrier auto

3. 【状态解析】对照references/STATUS_CODES.md：
   • "已签收" → 提供签收时间和网点
   • "运输中" → 显示最新路由节点
   • "异常" → 触发scripts/alert.py通知客服

#### 2.2.3 回复模板系统 ````markdown ## 回复话术模板 根据状态选择对应模板（完整模板见assets/reply_template.md）： ```markdown 【签收确认】 尊敬的客户，订单{{order_id}}已于{{time}}由{{person}}签收。 签收网点：{{location}} 如有疑问请联系：{{contact}} 【运输中】 您的包裹当前位于：{{last_node}} 预计到达时间：{{eta}} 最新路由轨迹： {{#each tracking}} - {{time}} {{location}} {{status}} {{/each}}

实测表明，采用"条件→流程→模板"的三段式结构，能使Agent的任务完成率提升35%以上。 ## 3. 脚本与资源的深度集成 ### 3.1 脚本开发规范 Skill中的脚本不是普通程序，而是"AI可执行的工具"，需要特殊设计： #### 3.1.1 错误处理标准化 ```python # 错误示范：模糊的报错 if not order_id: print("Error: Invalid input") # 正确写法：结构化错误输出 try: validate_order(order_id) except ValueError as e: print(json.dumps({ "error": "INVALID_ORDER", "message": str(e), "suggestion": "请提供8-12位数字订单号", "valid_examples": ["12345678", "20230001"] })) sys.exit(1) ``` #### 3.1.2 帮助文档嵌入 ```python #!/usr/bin/env python3 """ 物流查询工具 Usage: query.py --order <order_id> [--carrier <code>] [--verbose] Options: --order 必填，订单号(8-12位数字) --carrier 可选，快递公司代码(auto/sto/yto/zto) --verbose 显示详细调试日志 示例： query.py --order 12345678 query.py --order JD123 --carrier auto --verbose """ from docopt import docopt # 必备依赖 ``` > 经验之谈：建议所有脚本都实现`--help`参数，并且错误信息包含修正建议。这能使Agent的首次尝试成功率提高50%以上。 ### 3.2 资源引用最佳实践 #### 3.2.1 文件路径规范 ```markdown <!-- 正确引用方式 --> 请查阅[快递公司规范](references/CARRIERS.md) 执行脚本：`scripts/validate.py --input {{file}}` <!-- 错误示范 --> 请查看C:\skills\ref\carriers.doc # 绝对路径不可移植 ``` #### 3.2.2 分块加载策略 对于大型参考文件，建议拆分为按场景加载的小文件： ``` references/ ├── CARRIERS_BASIC.md # 基础合作商(2KB) ├── CARRIERS_PREMIUM.md # 高端物流(3KB) └── CARRIERS_SPECIAL.md # 特殊地区(1KB) ``` 在SKILL.md中按需引导加载： ```markdown 如果用户询问普通快递时效 → 查看references/CARRIERS_BASIC.md 如果是生鲜冷链等特殊件 → 加载references/CARRIERS_PREMIUM.md ``` ## 4. 技能评估与持续优化 ### 4.1 测试用例设计模板 在`evals/`目录中建立评估体系： ```json { "skill_name": "logistics-customer-service", "evals": [ { "id": "normal-query", "prompt": "订单12345678到哪了？", "expected": { "contains": ["物流状态", "最新节点"], "excludes": ["错误", "无法查询"], "actions": ["called query.py"] } }, { "id": "error-handling", "prompt": "帮我查JD123的物流", "expected": { "contains": ["订单号格式", "8-12位数字"], "actions": ["showed error guidance"] } } ] } ``` ### 4.2 性能优化指标 建立迭代目录分析关键数据： ``` iteration-2/ ├── benchmark.json └── eval-* ├── with_skill/ │ ├── metrics.json # 包含： │ │ - tokens_used: 1245 │ │ - time_cost: 2.3s │ │ - accuracy: 0.92 │ └── outputs/ └── without_skill/ └── ... ``` 优化建议优先级： 1. 降低token使用：拆分大文件、精简指令 2. 提高准确率：补充边缘案例、增强错误处理 3. 减少耗时：优化脚本性能、预加载高频资源 ## 5. 高级开发技巧 ### 5.1 上下文感知设计 使Skill能根据对话历史动态调整： ```markdown ## 上下文处理规则 - 当用户连续询问同一订单： 1. 首次查询：完整展示所有信息 2. 后续查询：仅显示变更节点 3. 添加快捷操作："需要查看更多历史轨迹吗？" - 检测用户情绪词汇（急/担心/投诉）： 自动触发scripts/priority.py提升处理级别 ``` ### 5.2 多技能协作机制 通过metadata字段实现技能联动： ```yaml # 在售后技能中声明关联 metadata: related_skills: - logistics-customer-service - refund-processor ``` 在指令中定义交接规则： ```markdown ## 跨技能协作 当出现以下情况时转交售后技能： 1. 用户提及"退货"或"换货" 2. 物流状态持续5天未更新 3. 用户明确要求人工客服 交接时需传递以下数据： - 订单号 - 当前物流状态 - 问题分类标签 ``` 这种模块化设计能使技能集的整体效能呈指数级增长，而非简单叠加。