把任何服务包装成 Skill 让 Claude 学会你的业务

baviya
0 阅读6分钟

🛠 Claude / AI 工程化

把任何服务包装成 Skill 让 Claude 学会你的业务

从零理解 Skill 体系 → 动手封装自己的服务 → 一键安装用起来

Claude OpenClaw Skill 开发 MCP AI 工程化

💡 这篇文章解决什么问题？
你有一个内部服务（查订单、发通知、爬数据……），想让 Claude 直接帮你调用，而不是每次都复制粘贴 API 文档给它讲一遍。Skill 就是解决方案。

想象一下这个场景：你跟 Claude 说「帮我查一下今天的发货单」，它不仅理解你的意图，还真的去调了你们公司内部接口，把数据整理好返回给你。

这不是科幻，这就是 Skill 机制的核心玩法。

🧠 一、Skill 是个什么东西？

一句话解释：Skill 就是一份「使用说明书」，告诉 Claude 遇到某类问题该怎么干。

把它想象成新员工入职时收到的 SOP 手册——不同的是，Claude 记性极好，而且真的会照着做。

Skill 本质上是一个文件夹，核心是一个 Markdown 文件（SKILL.md），里面写着：

  • 这个 Skill 叫什么、管什么范围（触发条件）
  • 遇到任务时 Claude 该执行哪些步骤
  • 需要跑哪些脚本、查哪些文档

Claude 在回答问题前，会扫描所有已安装的 Skill 描述，判断「这个任务要不要用某个 Skill」。命中了就读取 Skill 内容，按说明行事。

⚠️ 关键认知： 触发不是靠关键词匹配，是 Claude 自主判断。所以 Skill 的描述（description）要写得主动积极，把场景说清楚，避免"欠触发"。

📁 二、Skill 的物理结构

先看标准目录长什么样：

my-skill/

  ├── SKILL.md      ← 必须有，核心文件

  ├── scripts/      ← 可选：Claude 会直接执行的脚本

  │    └── call_api.py

  ├── references/  ← 可选：大段文档，按需加载

  │    └── api_doc.md

  └── assets/      ← 可选：模板、字体等

三层加载策略，越往后越「按需」：

1

YAML 头部（始终在上下文）

只有 name + description，约 100 词。Claude 用它判断要不要触发这个 Skill。

2

SKILL.md 正文（触发后加载）

详细的操作步骤、命令示例、错误处理。建议控制在 500 行以内，保持上下文干净。

3

scripts / references（需要时才读）

大段 API 文档、可执行脚本。Claude 会在 SKILL.md 中找到明确指引后才去加载，不浪费 token。

✍️ 三、写 SKILL.md 的完整姿势

3.1 YAML 头部 ——「触发器」

这是最重要的部分，直接决定 Claude 会不会来用你的 Skill：

---
name: order-query
description: >
  查询订单、发货单、退款单等电商业务数据。
  当用户提到"查订单"、"发货情况"、"退款状态"、
  "今天有多少单"等场景时，必须使用本 Skill。
  即使用户没有明确说"查订单系统"，
  只要涉及订单业务，就应触发。
---

YAML

🪄 描述写作技巧： 要「积极主动」。不要写「可以查询订单」，要写「当用户提到 XX 时，必须使用本 Skill」。Claude 天生有点保守，稍微推一把效果更好。

3.2 正文 —— 「操作手册」

告诉 Claude 怎么干活，越具体越好。来看一个完整示例：

# 订单查询 Skill

## 前置条件
- Python 3.10+
- 需要环境变量：ORDER_API_KEY

## 执行步骤

### 第一步：调用查询脚本
```bash
python scripts/query_order.py \
  --type "{订单类型}" \
  --date "{日期，默认今天}" \
  --output /tmp/orders.json
```

### 第二步：解析结果
读取 /tmp/orders.json，提取以下字段：
- total_count：总数
- status_breakdown：各状态分布
- exceptions：异常订单列表

### 错误处理
| 错误码 | 原因        | 处理方式             |
| 401    | 鉴权失败    | 提示用户检查 API Key |
| 404    | 无数据      | 告知用户当日暂无记录 |
| 500    | 服务异常    | 重试一次后报错       |

## 返回格式
用自然语言总结数据，高亮异常订单，
结尾附上数据来源时间戳。

Markdown

⚙️ 四、把服务逻辑写进 scripts/

Claude 会用 bash_tool 直接执行你放在 scripts/ 里的脚本。写法就是普通 Python/Shell，唯一要注意的是：参数通过命令行传入，结果写到文件，Claude 来读。

# scripts/query_order.py
import argparse, requests, json, os
from datetime import date

parser = argparse.ArgumentParser()
parser.add_argument("--type", default="all")
parser.add_argument("--date", default=str(date.today()))
parser.add_argument("--output", required=True)
args = parser.parse_args()

# 调用你的内部服务
resp = requests.get(
    f"https://your-internal-api.com/orders",
    params={"type": args.type, "date": args.date},
    headers={"Authorization": f"Bearer {os.environ['ORDER_API_KEY']}"}
)

resp.raise_for_status()

# 写入结果文件
with open(args.output, "w", encoding="utf-8") as f:
    json.dump(resp.json(), f, ensure_ascii=False, indent=2)

Python

✅ 最佳实践： 所有敏感信息（API Key、密码）通过环境变量传入，不要硬编码进脚本。Claude 会在执行时自动继承宿主进程的环境变量。

🔄 五、完整流程图

用户说话

→

Claude 扫描
Skill 描述

→

命中？
读 SKILL.md

→

执行
scripts/

→

整理结果
回复用户

📦 六、打包与安装

Skill 写完，跑一行命令打包：

# 打包成 .skill 文件
python -m scripts.package_skill ./my-skill/

# 输出：my-skill.skill
# 把这个文件发给用户，拖入 OpenClaw 安装即可

Bash

用户安装后，再也不用给 Claude 解释你们公司的业务系统了。

🆚 七、Skill vs 其他方案对比

方案使用方式优点缺点
Skill安装后自动触发零操作、自动识别场景、可执行代码需要写 SKILL.md
System Prompt每次会话注入简单直接上下文占用大、不可执行代码
MCP Server工具调用标准化、跨平台需要搭服务、门槛较高
手动粘贴文档每次手动无需开发效率极低、容易忘

🪤 八、常见坑 & 避坑指南

坑

description 写得太保守 → 触发不了

❌ "可以用于查询订单数据" → ✅ "当用户提到订单、发货、退款时，必须使用本 Skill"

坑

SKILL.md 太长 → 上下文爆炸

超过 500 行就该把大段文档拆到 references/ 里，SKILL.md 只写指引路径。

坑

脚本报错没有处理 → Claude 不知道咋办

在 SKILL.md 里写清楚错误处理逻辑，或在脚本里把错误信息写入 output 文件。

坑

API Key 硬编码 → 安全风险

一律用环境变量，SKILL.md 里注明「需要配置 YOUR_API_KEY 环境变量」。

🎯 总结

Skill 的核心理念其实很简单：把你的服务的「怎么用」写成 Claude 能读懂的说明书，让 Claude 自己去调。

你需要做的事情，归纳起来就是三步：

1

写 SKILL.md

头部写触发描述（要主动！），正文写操作步骤（要具体！）

2

写 scripts/ 脚本

封装你的服务调用逻辑，命令行参数进，JSON 文件出

3

打包安装

一行命令生成 .skill 文件，拖入 OpenClaw 完事

「让 Claude 学会你的业务」这件事，门槛没你想象的高。一个 SKILL.md，一个 Python 脚本，就够了。

📌 如果这篇文章对你有用，欢迎点赞收藏！
有疑问或者你封装了有意思的 Skill，欢迎评论区分享 👇

avatar
文章
阅读
粉丝