Phase 4 / Ep 19: 从零开发你的第一个 Skill —— \"快递查询\"实战

⏱ 预计阅读 4 分钟 更新于 2026/4/13

🎯 学习目标：亲手开发一个完整的自定义 Skill。

1. 目标：快递查询 Skill

我们要开发一个 package-tracker Skill，让 Agent 能够根据快递单号查询物流状态。

2. 创建目录结构

cd ~/.openclaw/agents/personal/skills/
mkdir -p package-tracker/scripts

最终结构：

package-tracker/
├── SKILL.md            # 技能定义（必须）
├── scripts/
│   └── track.sh        # 查询脚本
└── examples/
    └── usage.md        # 使用示例

3. 编写 SKILL.md

name: package-tracker
description: 根据快递单号查询物流状态，支持顺丰、圆通、中通等主流快递
version: 1.0.0
author: your-name
tags: [logistics, tracking, utility]
permissions: [network]

# 快递查询技能

## 使用场景
当用户提供快递单号并询问物流状态时使用此技能。

## 操作步骤
1. 从用户消息中提取快递单号（通常是 10-20 位数字或字母+数字）
2. 自动识别快递公司（根据单号前缀）
3. 调用 scripts/track.sh <单号> <快递公司代码>
4. 解析返回的 JSON 数据
5. 以时间线格式展示给用户

## 快递公司代码
- SF: 顺丰
- YTO: 圆通
- ZTO: 中通
- STO: 申通
- YD: 韵达

## 输出格式示例
📦 快递单号: SF1234567890
🏢 快递公司: 顺丰速运
📍 当前状态: 派送中

物流轨迹:
⏰ 04-06 09:30 - 正在派送，快递员张三 138xxxx
⏰ 04-06 06:00 - 到达北京朝阳区分拨中心
⏰ 04-05 18:00 - 已从深圳发出

## 错误处理
- 单号格式不正确：提示正确格式
- 查询无结果：建议检查单号或稍后重试
- API 超时：告知用户稍候

4. 编写辅助脚本

#!/bin/bash
# scripts/track.sh
# $1 = 快递单号, $2 = 快递公司代码
curl -s "https://api.kuaidi100.com/query?num=$1&company=$2"

chmod +x scripts/track.sh

5. 本地测试

# 重启 Agent 加载新 Skill
openclaw gateway restart

# 验证 Skill 已加载
openclaw skills list
# → package-tracker  v1.0.0  ✅ loaded

# 测试对话
openclaw chat "帮我查一下快递 SF1234567890"

6. 开发技巧

  • 保持 SKILL.md 简洁：不超过 1000 字，减少 Token 消耗
  • 指令要具体：给 Agent 清晰的操作步骤，不要含糊
  • 错误处理完整：告诉 Agent 每种异常情况怎么应对
  • 使用示例：在 examples/ 中放入真实的使用案例

下节预告： Ep 20，高级 Skill 开发——多脚本协作、Resources 目录、跨 Agent 共享。