一、简介

Agent Skills 是为 AI 智能体（Agent）提供的模块化、标准化、可复用的专业化能力单元，是连接大模型 “推理能力” 与外部 “工具执行” 的核心中间层，让通用 Agent 能像专业人员一样完成特定领域任务。

简单理解：Agent 是 “大脑 + 身体”，Skills 是 “专业技能包 + 操作手册”—— 没有 Skills 的 Agent 只会基础推理，有了 Skills 才能精准、稳定地落地复杂任务。

1.1 相关概念的区别

概念	定位	核心作用	与 Skills 的关系
大模型（LLM）	思考中枢	理解意图、规划路径、生成决策	提供 “想怎么做” 的能力
工具（Tools）	执行载体	读写文件、调用 API、运行代码	提供 “能做什么” 的能力
Agent Skills	能力引擎	标准化流程、工具调度、结果校验	连接 “思考” 与 “执行”，提供 “怎么做才对” 的能力
传统 Prompt	单次指令	临时引导模型输出	无状态、不可复用；Skills 是持久化、可组合的 “超级 Prompt”

1.2 核心价值（对比传统提示词）

对比项	传统长提示词	Agent Skills
复用性	不可复用，每次任务重写	一次编写，多场景 / 多模型复用
上下文占用	全量加载，易炸窗口	渐进式加载，仅用时加载
可维护性	零散、难管理	结构化、版本化、可审计
能力边界	模糊、易偏离	明确触发条件、执行流程、校验规则
扩展性	差，新增能力需重写	模块化组合，新增技能即插即用

1.3 适用场景

1. 领域专家能力封装（如代码规范、法律审查、数据分析）
2. 标准化工作流（如需求分析、测试用例编写、部署流程）
3. 工具调用自动化（如 API 调用、CLI 执行、数据库操作）
4. 团队知识沉淀（新人培训、流程标准化、最佳实践固化）

二、核心架构：三层渐进式加载

Agent Skills 最核心的是渐进式披露（Progressive Disclosure），分三层加载，既保证能力完整，又不浪费上下文。一个完整的 Skill 是一个独立文件夹，核心文件为SKILL.md，配套脚本、参考资料等：

skills/
└── order-timeout-cancel/       # 技能名称（小写、短横线分隔）
    ├── SKILL.md                # 核心文件（必须全大写）
    ├── scripts/                # 可执行脚本（CLI/API/代码片段）
    │   ├── cancel_order.sh     # 订单取消脚本
    │   └── delay_mq.py         # RabbitMQ 延迟消息代码
    ├── references/             # 参考文档（规范、原理、案例）
    │   ├── rabbitmq-delay.md   # RabbitMQ 延迟队列原理
    │   └── business-rule.md    # 订单超时业务规则
    └── assets/                 # 模板、配置、示例
        ├── application.yml     # SpringBoot 配置模板
        └── example.sql         # 数据库示例

2.1 元数据层（始终加载）

• 内容：SKILL.md 顶部的 YAML 元数据（name、description、trigger）

• 作用：AI 启动时加载，用于判断任务是否匹配该技能，不占大量 Token

• 示例：

  ---
  name: 订单超时取消处理
  description: 处理 RabbitMQ 延迟消息实现订单超时未支付自动取消，含死信队列/延迟插件两种方案
  trigger: 订单、超时、取消、延迟消息、RabbitMQ、死信队列
  ---
  

2.2 核心流程层（触发加载）

• 内容：SKILL.md 正文（执行步骤、输入输出、边界处理、校验规则）
• 作用：当用户输入匹配 trigger 时，AI 加载完整流程，按步骤执行任务
• 特点：结构化、可执行，像 “操作手册” 而非 “百科全书”

2.3 扩展资源层（按需加载）

• 内容：scripts/（可执行脚本）、references/（参考文档）、assets/（模板 / 案例）
• 作用：仅当流程需要时加载（如执行脚本、查阅规范），结果进上下文，文件本身不占 Token

三、SKILL.md 编写规范

SKILL.md 是 Skill 的 “心脏”，由 YAML 元数据 + 结构化正文 组成，必须严格遵循格式。

3.1 元数据（Frontmatter）

必须放在文件顶部，用 — 包裹

---
# 基础信息（必填）
name: 订单超时取消处理          # 技能名称（简洁、唯一）
description: 基于 RabbitMQ 实现订单超时未支付自动取消，支持死信队列与延迟插件两种方案，含完整流程、代码、校验规则  # 清晰描述能力
version: 1.0.0                 # 版本号（语义化）
author: your-name               # 作者
created: 2026-05-05            # 创建时间

# 触发规则（必填，AI 匹配任务的关键）
trigger:
  - 订单超时
  - 取消订单
  - 延迟消息
  - RabbitMQ 死信队列
  - 延迟插件
  - 未支付自动取消

# 兼容性（可选）
compatible:
  - Claude 3
  - Cursor
  - Gemini
  - SpringBoot

# 依赖（可选，执行需前置技能）
depends:
  - rabbitmq-basic
  - springboot-mq
---

3.2 正文结构：5 大模块（标准化执行流程）

正文必须结构化，让 AI 能按步骤执行、校验、处理异常，推荐以下模块：

1. When to Use（适用场景）：明确技能的使用边界，避免滥用。

   ## When to Use
   - 电商订单超时未支付（如 15 分钟未支付自动取消）
   - 需延迟执行的业务（如短信延迟发送、优惠券到期提醒）
   - 基于 RabbitMQ 实现延迟消费的场景
   - 不适用：实时性要求极高（<1s）、无延迟需求的业务
   

2. Process（执行流程：核心步骤）：分点列出可执行步骤，含输入、操作、输出，AI 严格按此执行。

   ## Process
   ### Step 1：需求确认（必做）
   - 输入：订单超时时间（如 15min）、业务系统（SpringBoot）、MQ 类型（RabbitMQ）
   - 操作：确认是否需要死信队列（固定延迟）或延迟插件（动态延迟）
   - 输出：延迟方案选型结果
   
   ### Step 2：环境准备
   - 操作：安装 RabbitMQ（3.5.8+），如需动态延迟则安装 `rabbitmq_delayed_message_exchange` 插件
   - 输出：RabbitMQ 环境就绪、插件启用状态
   
   ### Step 3：方案实现（二选一）
   #### 方案 A：死信队列（固定延迟）
   1. 创建 TTL 队列（设置 `x-message-ttl`、`x-dead-letter-exchange`）
   2. 创建死信交换机（DLX）与业务消费队列
   3. 生产者发送消息到 TTL 队列
   4. 消费者监听业务队列，处理超时订单
   
   #### 方案 B：延迟插件（动态延迟，推荐）
   1. 声明延迟交换机（类型 `x-delayed-message`，参数 `x-delayed-type=direct`）
   2. 生产者发送消息时设置 `x-delay` 头（延迟毫秒数）
   3. 消费者监听业务队列，到期自动消费
   
   ### Step 4：代码开发
   - 操作：编写 SpringBoot 生产者/消费者代码，配置 MQ 连接、队列、交换机
   - 输出：可运行的 MQ 延迟消息代码
   
   ### Step 5：测试验证
   - 操作：发送测试订单，等待超时后检查订单状态、MQ 消息流转
   - 输出：测试报告、异常日志
   

3. Verification（校验规则：确保正确）：明确如何判断任务完成，AI 执行后自动校验。

   ## Verification
   1. 订单超时后，状态自动变为“已取消”，库存回滚
   2. MQ 消息：TTL 队列消息过期 → 转发到 DLX → 进入业务队列 → 消费成功（ACK）
   3. 无消息丢失、无重复消费、无死信堆积
   4. 日志：包含订单 ID、超时时间、取消结果、MQ 路由日志
   

4. Common Rationalizations（常见借口：避免偷懒）：列出 AI 可能跳过步骤的借口，强制按流程执行。

   ## Common Rationalizations
   - “延迟时间固定，不用死信队列，直接用普通队列+定时任务” → 拒绝，必须用 MQ 延迟方案
   - “延迟插件安装麻烦，用死信队列就行” → 需确认业务是否需要动态延迟，否则按推荐方案
   - “测试太麻烦，直接上线” → 拒绝，必须完成 Step 5 测试验证
   

5. Red Flags（风险预警：异常处理）：列出异常场景与处理方式，AI 遇到时自动触发。

   ## Red Flags
   1. 死信队列消息堆积 → 检查消费者是否正常、是否 ACK、是否有异常
   2. 延迟插件消息不转发 → 检查插件是否启用、`x-delay` 头是否正确、交换机类型是否正确
   3. 订单取消失败 → 回滚事务、记录死信、告警通知
   4. 消息重复消费 → 实现业务幂等（数据库唯一键、分布式锁）
   

3.3 正文编写原则

• 可执行性：写 “步骤” 而非 “概念”，AI 能直接照着做
• 简洁性：删除冗余解释，细节放 references/
• 边界清晰：明确适用 / 不适用场景、异常处理
• 标准化：统一格式，团队协作易维护

四、扩展文件编写（scripts/references/assets）

4.1 scripts/：可执行脚本（让 AI “动手”）

• 用途：封装重复操作、工具调用、代码执行（如 CLI、API、Python/Shell 脚本）

• 特点：AI 直接执行，结果进上下文，代码不占 Token

• 示例（scripts/delay_mq.py）：

  # RabbitMQ 延迟插件生产者示例
  import pika
  connection = pika.BlockingConnection(pika.ConnectionParameters('localhost'))
  channel = connection.channel()
  # 声明延迟交换机
  channel.exchange_declare(
      exchange='delay_exchange',
      exchange_type='x-delayed-message',
      arguments={'x-delayed-type': 'direct'}
  )
  # 发送延迟消息（延迟 15 分钟）
  channel.basic_publish(
      exchange='delay_exchange',
      routing_key='order.timeout',
      body='{"orderId":"123456","timeout":900000}',
      properties=pika.BasicProperties(
          headers={'x-delay': 900000}  # 15 分钟 = 900000ms
      )
  )
  connection.close()
  

4.2 references/：参考文档（知识补充）

• 用途：存放原理、规范、长文档，AI 按需查阅，不污染核心流程
• 示例（references/rabbitmq-delay.md）：讲解死信队列、延迟插件原理、配置参数

4.3 assets/：资源文件（模板 / 案例）

• 用途：存放配置模板、SQL、示例代码，AI 可直接复用
• 示例（assets/application.yml）：SpringBoot RabbitMQ 配置模板

五、工作机制：Agent 如何使用 Skills

1. 加载与发现

   • Agent 启动时，扫描指定目录（如~/.claude/skills），加载所有 Skill 的元数据
   • 建立 “技能索引”，根据用户请求的关键词、任务类型，自动匹配最合适的 Skill

2. 执行流程（以 “会议总结” 为例）

   1. 意图识别：用户输入 “帮我总结这个会议录音”，Agent 识别为 “会议处理” 任务
   2. Skill 匹配：匹配会议总结Skill，加载其执行流程
   3. 分步执行：
      • 调用语音识别工具转文本
      • 按 Skill 流程提取 “参会人、议题、决议、待办”
      • 生成结构化纪要
      • 校验输出完整性
   4. 结果返回：输出符合规范的会议纪要，同时触发任务分派Skill，自动推送待办

3. 组合调用（复杂任务）
   Agent 可自动组合多个 Skills 完成端到端流程：

   • 示例：订单处理 = 订单解析 + 库存校验 + 支付确认 + 物流通知
   • 每个 Skill 专注一个环节，协同完成全流程自动化

六、Skill 加载与使用（3 种方式）

编写好 Skill 后，需加载到 AI 智能体中使用，主流方式如下：

1. 系统提示词加载（极简）
   • 方式：将 SKILL.md 内容复制到 AI 的系统提示词（System Prompt）开头
   • 适用：快速测试、单技能使用
   • 示例：

     你是专业的后端开发助手，严格遵循以下技能执行任务：
     [粘贴 SKILL.md 完整内容]
     现在请处理：实现订单 15 分钟未支付自动取消
     

2. 规则文件加载（团队推荐）
   • 方式：将 Skill 放入项目规则文件（如 .cursorrules、CLAUDE.md），AI 启动时自动加载
   • 适用：Cursor、Claude Code、Gemini 等工具，团队共享技能
   • 示例（.cursorrules）：

     [skills]
     path = ./skills
     auto_load = true
     

3. 动态触发加载（高级）
   • 方式：AI 先加载所有 Skill 的元数据（Level 1），匹配用户输入后，自动加载对应 Skill 的完整流程（Level 2）
   • 适用：多技能管理、大型项目，避免上下文爆炸
   • 工具：支持 Agent Skills 标准的 AI 助手（如 Claude 3、Cursor、腾讯云智能体）

七、实战：从零编写第一个 Skill（订单超时取消）

Step 1：创建目录

mkdir -p skills/order-timeout-cancel/{scripts,references,assets}
touch skills/order-timeout-cancel/SKILL.md

Step 2：编写 SKILL.md（按前面规范）

• 元数据：name、description、trigger
• 正文：When to Use、Process、Verification、Common Rationalizations、Red Flags

Step 3：编写 scripts/ 脚本

• scripts/delay_mq_producer.py：延迟消息生产者
• scripts/order_consumer.py：订单消费者

Step 4：编写 references/ 文档

• references/rabbitmq-delay.md：RabbitMQ 延迟队列原理

Step 5：加载并测试

• 将 Skill 放入 .cursorrules，启动 Cursor
• 输入：“帮我实现订单 15 分钟未支付自动取消，用 RabbitMQ 延迟插件”
• AI 自动匹配 Skill，按流程执行：选型 → 环境准备 → 代码开发 → 测试验证

八、最佳实践与避坑

8.1 编写最佳实践

1. 单一职责：一个 Skill 只做一件事，复杂任务拆分子 Skill
2. 触发精准：trigger 关键词简洁、唯一，避免误匹配
3. 流程闭环：从需求到校验，形成完整闭环，无遗漏步骤
4. 脚本化：重复操作放入 scripts/，减少 AI 重复编写
5. 版本化：Skill 纳入 Git 管理，迭代更新

8.2 常见坑点

• 元数据缺失：name/description/trigger 不完整，AI 无法匹配
• 正文模糊：写概念而非步骤，AI 无法执行
• 边界不清：未明确适用 / 不适用场景，AI 滥用技能
• 无校验规则：AI 执行后无法判断是否正确
• 脚本无异常处理：执行失败无回滚、无日志
• 过度加载：一次性加载所有 Skill，导致上下文爆炸