Skills 技能系统

Skill 是什么

Skills 是给 Agent 看的「任务说明书 + 工具包」。每个 Skill 是一个包含 SKILL.md 的目录，用 Markdown 指令引导 Agent 完成特定任务。不需要复杂的编译，全靠自然语言描述。

当 Agent 推理时识别到任务与某个 Skill 匹配，就会读取对应的 SKILL.md 来获取执行指引。

内置 Skill 和自定义 Skill

OpenClaw 的 Skills 分为三类：

类型	说明	来源
内置 Skills	系统自带的通用能力（浏览器自动化、画布、任务流等）	随 OpenClaw 安装
本地 Skills	你自己写的专属技能	放在 workspace skills 目录下
插件 Skills	通过 ClawHub 安装的社区技能	openclaw skills install

SKILL.md 结构

一个完整的 Skill 目录结构：

skills/
└── weather/
    ├── SKILL.md          # 核心：技能说明书
    ├── scripts/           # 可选：辅助脚本
    │   └── fetch_weather.sh
    └── assets/            # 可选：资源文件
        └── icons/

SKILL.md 示例

---
name: weather
description: Current weather and forecasts using web APIs
version: 1.0.0
requires:
  binaries: ["curl"]
---

# Weather Skill

## When to use this skill
Use this skill when the user asks about:
- Current weather conditions
- Weather forecasts for a specific location
- Temperature, humidity, wind speed, or precipitation

## How to use
1. Identify the location from user's message
2. Call the weather API:
   ```bash
   curl -s "https://wttr.in/Beijing?format=j1"

3. Parse the JSON response
4. Present results in a human-readable format with emoji

Example output format

🌤️ 北京今日天气

• 温度：22°C ~ 30°C
• 湿度：65%
• 风速：3级，东南风
• 建议：适合户外活动

Notes

• Always show both Celsius and Fahrenheit
• Include a friendly outfit suggestion for extreme weather

## 加载优先级

Skills 有六级加载优先级，当同名 Skill 存于多位置时，**优先级高者胜出**：

| 优先级 | 来源 | 路径 |
|--------|------|------|
| 1（最高） | Workspace Skills | `<workspace>/skills` |
| 2 | Project Agent Skills | `<workspace>/.agents/skills` |
| 3 | Personal Agent Skills | `~/.agents/skills` |
| 4 | Managed Skills | `~/.openclaw/skills` |
| 5 | Bundled Skills | 随安装附带 |
| 6（最低） | Extra Dirs + Plugin Skills | `skills.load.extraDirs` |

## Skill Workshop

**Skill Workshop** 是 Agent 和你的活跃 Skill 文件之间的「提案队列」。Agent 发现可复用的工作模式时，会自动起草提案而非直接写入 `SKILL.md`。你审核通过后才会生效。

```bash
# 查看提案列表
openclaw skills workshop list

# 查看某个提案详情
openclaw skills workshop inspect <proposal-id>

# 批准提案（写入 SKILL.md）
openclaw skills workshop apply <proposal-id>

# 拒绝提案
openclaw skills workshop reject <proposal-id>

安装 Skills

# 从 ClawHub 安装
openclaw skills install @owner/my-skill

# 从 Git 仓库安装
openclaw skills install git:owner/repo@main

# 安装本地 Skill 目录
openclaw skills install ./path/to/skill --as my-tool

# 全局安装（所有 Agent 可用）
openclaw skills install @owner/my-skill --global

# 更新所有 workspace skills
openclaw skills update --all

实战：写一个"天气查询"Skill

# 1. 创建 Skill 目录
mkdir -p ~/.openclaw/workspace/skills/weather

# 2. 编写 SKILL.md
cat > ~/.openclaw/workspace/skills/weather/SKILL.md << 'SKILLEOF'
---
name: weather
description: 天气查询与预报
version: 1.0.0
---

# 天气查询 Skill

## 触发条件
用户询问某地的天气、温度、是否下雨、穿衣建议等。

## 执行流程
1. 从用户消息中提取地点名称
2. 调用 `web_fetch` 工具请求 `https://wttr.in/{city}?format=j1`
3. 解析 JSON，提取当前温度和天气描述
4. 输出格式化的天气卡片

## 输出模板
{地点} {日期} 天气情况：
- 温度：{最低}°C ~ {最高}°C
- 天气：{描述}
- 湿度：{湿度}%
- 风速：{风速}km/h
SKILLEOF

# 3. 重启 Gateway 生效
openclaw gateway restart

然后对 Agent 说「查询北京天气」，Agent 会加载 weather Skill 并按指引执行。

Agent 级别的 Skill 管控

{
  agents: {
    defaults: {
      skills: ["github", "weather"],  // 默认可见的 skills
    },
    list: [
      { id: "writer" },               // 继承默认 skills
      { id: "docs", skills: ["docs-search"] }, // 替换：仅 docs-search
      { id: "locked-down", skills: [] },        // 禁用所有 skills
    ],
  },
}

经验：什么时候该写 Skill、什么时候不用

✅ 该写 Skill 的场景

• 操作流程固定：如"创建飞书多维表格并填入数据"，步骤是固定的
• 需要特殊领域知识：如"解析 AWS ECS 日志"，需要特定命令和参数
• 高频复用：同一类任务出现 3 次以上，值得抽象成 Skill
• 多人共享：团队共用的最佳实践，写一次大家受益

❌ 不用写 Skill 的场景

• 一次性任务：只做一次的操作，不值得花时间写 Skill
• 过于通用：如"帮我查资料"—— 太宽泛，Agent 自己就能处理
• 纯问答：技术问答类不需要 Skill，Agent 有足够常识
• 变体太多：每次执行路径差异太大，Skill 写不完整

Skill 编写原则

Skill 不是教程，是操作手册。 写清楚「什么情况触发 → 第一步做什么 → 第二步做什么 → 输出什么格式」就够了。别写原理和背景，那是给人类看的。

安全提醒

把第三方 Skills 当作不受信任的代码对待。安装前先阅读 SKILL.md 内容，确认不会执行危险操作。

下一步

掌握了 Skills 系统后，继续学习 Memory 记忆系统 →

加载练习题中...

---

🎯 本章要点

• Skill 是包含 SKILL.md 的目录，用 Markdown 引导 Agent 完成任务
• 分为内置（系统自带）、本地（自己写）、插件（ClawHub 社区）三类