Agent Skills 架构解析与实践指南

✅ 核心速览：
Agent Skills通过“结构化能力封装+渐进式披露+主动规划调用”，破解了LLM在复杂任务中的局限性，是AI工程从“通用智能”走向“可靠专用智能”的关键架构升级。

一、大语言模型（LLM）的局限性

LLM在文本生成、问答等任务中表现卓越，但在复杂任务中存在不可忽视的瓶颈，核心局限如下：

1. 本质：概率预测而非语义理解

LLM基于海量文本的统计规律预测“下一个词”，缺乏对语义的真正理解。在深层逻辑推导（如数学证明）、跨领域知识整合等场景中易出错，产生“看似合理但错误”的幻觉输出。

2. 无状态：难以维护实时上下文

LLM每次调用仅依赖当前输入，无法感知实时上下文（如当前时间、用户状态、系统日志）。例如：客服场景中用户中途修改合同信息，模型若未获知变更，仍基于旧上下文作答，导致服务偏差。

3. 多步骤任务易断裂

即使通过提示工程拆解任务，LLM仍难以可靠维护中间状态、验证步骤结果或出错回滚。长任务处理中易出现“中途失忆”“流程断裂”，脆弱性显著。

4. 工具调用可靠性不足

工具调用可扩展LLM能力，但存在三大问题：

• 误用/虚构/拼错工具参数；
• 无法自主判断工具执行结果是否成功；
• 缺乏外部验证机制时，错误沿任务链传播，导致流程失败。

5. 决策黑箱：不可验证、不可解释

高风险场景（金融、医疗、法律）需每一步可追溯的依据，而LLM的“黑箱特性”无法满足信任需求。

二、什么是Agent Skills？

Agent Skills是标准化、模块化、可动态加载的能力单元，以SKILL.md为核心，包含指令、脚本和资源的结构化文件夹体系，用于指导LLM在特定任务中正确、可靠地调用外部能力或执行程序性操作。

核心定位：“能力适配器”

• 既非传统函数库（无代码依赖），也非普通提示词（结构化资源）；
• 介于LLM与真实世界之间，将专业知识打包为“可组合资源”，扩展LLM能力；
• 类比：为新员工准备的“入职指南”——通过捕获和共享流程知识，用可组合能力将通用智能体转化为专用智能体（无需为每个用例构建碎片化定制智能体）。

示例：意图识别Skill

---
name: intent_recognition
description: 当需要识别用户输入的意图时，请使用此技能。该技能只识别在意图列表中定义的具体意图，以便系统能够准确理解用户需求并提供相应的服务。
---

# 意图识别

## 功能概述
本技能用于识别和分类用户输入的意图。通过分析用户对话内容，系统能够判断用户的真实需求，并在预定义的意图列表中进行匹配。该技能只识别在指定意图列表中定义的意图，有助于后续业务流程的正确引导。

## 使用方法
请按照以下步骤进行意图识别操作：

1. **接收用户输入**  
   - 获取用户发送的文本内容。  
   - 分析文本中的关键词、语义和表达意图。

2. **意图分类**  
   - 识别并分类用户意图，仅识别 `references/intent_list.md` 文件中定义的具体意图。  
   - 如果用户意图不在预定义列表中，返回"无法应答"。

3. **返回意图分类结果**  
   - 将识别到的意图返回给调用方  
   - 提供意图的详细描述和置信度评分  
   - 返回格式示例：  
     ```json
     {
       "intent": "咨询",
       "description": "用户希望获取特定信息或解释",
       "confidence": 0.95
     }
     ```

**最佳实践**  
- 始终分析用户输入的上下文，全面理解用户意图  
- 确保意图识别的准确性，避免误判  
- 严格遵循预定义的意图列表，不在列表中的意图应返回"无法应答"  
- 在处理复杂或含糊表达时，提供多个可能意图的选项（仅限于列表中的意图）  
- 建议在无法识别明确意图时，向用户提供澄清问题

## 可用资源
- references/intent_list.md: 意图列表详细描述

三、Agent Skills如何破局？

Agent Skills是LLM的“外挂操作系统”：让LLM专注理解与生成语言能力（协调、沟通），Skills提供确定性执行保障、状态感知、反馈闭环、可解释决策依据和模块化扩展（做事）。

LLM局限性与Skills解决机制对照表

实战案例：用户诉求“取消订单并投诉”

• 纯LLM方案：直接生成道歉文本，但无法确认订单状态、是否可取消、投诉流程合规性，易产生幻觉。
• LLM + Skill方案：
  1. 意图识别Skill → 输出“取消订单+投诉”意图；
  2. 技能匹配器 → 加载“订单查询Skill”“取消订单Skill”“投诉处理Skill”；
  3. 渐进式披露技能，按需执行（先查订单状态，再判断能否取消，最后走投诉流程）。

四、Agent Skills vs Function Calling

两者均扩展模型能力，但设计哲学、抽象层级、可维护性差异显著：Tool是“怎么做”，Skill是“做什么+何时做+做错了怎么办”。

核心差异对比表

4.1 抽象层级

4.2 封装方式

4.3 调用逻辑

五、Agent Skills标准结构

AgentScope完全对齐Claude Agent Skills结构，采用三层递进式设计（基础→详细→扩展），兼顾灵活性、可读性与上下文效率。

5.1 Skill文件夹结构

skill-name/                  # 技能根目录（名称小写字母、数字、下划线）
├── SKILL.md                 # 必需：入口文件（YAML前置元数据+指令）
├── references/              # 可选：详细参考文档
│   ├── api-doc.md           # API参考
│   └── best-practices.md    # 最佳实践
├── examples/                # 可选：工作示例
│   └── example1.java        # 示例脚本/代码
└── scripts/                 # 可选：可执行脚本
    └── process.py           # 数据处理/业务逻辑脚本

5.2 SKILL.md格式规范

---
name: 技能名称                    # 必需：技能名称（小写字母、数字、下划线）
description: 技能描述，技能使用场景等等...  # 必需：触发描述（说明何时使用）
---

# 技能名称

## 功能概述
[详细说明该技能的功能，如“用于识别用户输入的业务意图，匹配预定义意图列表”]

## 使用方法
[分步骤说明操作流程，含输入、处理逻辑、输出格式，如“1. 接收用户输入文本；2. 匹配references/intent_list.md；3. 返回意图JSON”]

## 可用资源
- references/api-doc.md: API 参考文档
- scripts/process.py: 数据处理脚本

5.3 性能优化建议

1. 控制SKILL.md大小：保持≤5k tokens，建议1.5-2k tokens（避免占用过多上下文窗口）；
2. 合理组织资源：详细文档放references/，示例放examples/，脚本放scripts/；
3. 清理旧版本：用clearSkillOldVersions()清理无用版本；
4. 避免重复注册：相同Skill对象配多个Tool时，利用重复注册保护机制（不创建重复版本）。

六、渐进式披露：无限上下文的秘密

核心思想：只在用户需要时展示信息/功能，像“手册从目录→章节→附录”一样，让智能体按需加载技能内容，节省上下文窗口，提升决策聚焦度。

上下文窗口变化过程（以PDF技能为例）

1. 初始状态：上下文含核心系统提示、所有技能的元数据（名称+描述）、用户初始消息；
2. 触发阶段：LLM调用Bash工具读取pdf/SKILL.md，触发PDF技能；
3. 深度加载：LLM选择读取技能捆绑的forms.md（如需处理表单）；
4. 执行阶段：加载PDF技能指令后，LLM继续处理用户任务（如提取PDF表格数据）。

价值

• 无需将整个技能内容读入上下文，技能可捆绑的上下文量理论上无限；
• 决策过程更聚焦（仅加载当前任务相关细节），效率显著提升。