什么是 Skill

本文聚焦：Skill 的本质定义 + Skill 的目录结构

前置知识：第一个 Agent 下一篇：创建第一个 Skill

知识点 1：Skill 的本质——Agent 的能力扩展包

是什么

Skill 是 OpenClaw 中用于扩展 Agent 能力的模块化单元。你可以把它理解为 Agent 的"技能插件"——每个 Skill 封装了一组特定的工具、知识和行为模式，让 Agent 能够完成特定领域的任务。

举个例子：

• 没有 Skill 的 Agent 只能进行基础对话
• 安装了 web_search Skill 后，Agent 就能搜索网络信息
• 安装了 feishu-doc Skill 后，Agent 就能读写飞书文档

为什么需要 Skill

OpenClaw 采用"最小核心 + 插件扩展"的架构设计：

1. 保持核心轻量：Gateway 只负责消息路由和会话管理，不内置具体工具
2. 按需加载能力：用户只安装需要的 Skill，避免资源浪费
3. 社区生态：任何人都可以开发并分享 Skill，形成生态
4. 版本隔离：Skill 可以独立更新，不影响核心系统

Skill vs 原生工具

特性	Skill	原生工具
安装方式	clawhub install 或手动复制	内置在 Gateway 中
更新频率	独立更新	随 Gateway 版本更新
代码位置	~/.openclaw/skills/	Gateway 源码
开发门槛	低（只需写 SKILL.md）	高（需要改 Gateway）
适用场景	特定领域工具、第三方集成	通用基础能力

常见陷阱

陷阱 1：把 Skill 当成简单的命令别名

❌ 错误理解：Skill 就是 "ls = 列出文件"
✅ 正确理解：Skill 包含工具定义、参数校验、错误处理、使用说明等完整逻辑

陷阱 2：认为 Skill 越多越好

❌ 错误做法：安装几十个 Skill "以防万一"
✅ 正确做法：按需安装，Skill 过多会增加 token 消耗和响应延迟

陷阱 3：忽略 Skill 的权限范围

❌ 错误假设：所有 Skill 都有 exec 权限
✅ 正确做法：检查每个 Skill 的权限声明，高危操作（如 exec、write）要谨慎授权

知识点 2：Skill 的目录结构

标准目录布局

一个完整的 Skill 目录结构如下：

~/.openclaw/skills/
└── skill-name/
    ├── SKILL.md          # 核心：技能定义文档
    ├── scripts/          # 可选：辅助脚本
    │   └── helper.py
    ├── references/       # 可选：参考资料
    │   └── api-reference.md
    └── examples/         # 可选：示例代码
        └── example.js

SKILL.md 的核心作用

SKILL.md 是 Skill 的灵魂，它告诉 Agent：

1. 这个 Skill 是做什么的（描述、适用场景）
2. 提供了哪些工具（工具名称、参数、返回值）
3. 什么时候应该使用（触发条件、优先级）
4. 如何使用（示例代码、注意事项）

典型的 SKILL.md 结构：

# Skill 名称

## 描述
简要说明这个 Skill 的功能

## 适用场景
- 场景 1
- 场景 2

## 工具清单

### tool_name
描述这个工具的作用

**参数：**
- `param1`: 参数说明
- `param2`: 参数说明

**示例：**
```json
{
  "tool": "tool_name",
  "arguments": {
    "param1": "value"
  }
}

注意事项

• 注意点 1
• 注意点 2

### Skill 的安装位置

OpenClaw 默认从以下位置加载 Skill：

1. **系统级**：`/usr/share/openclaw/skills/`（全局可用）
2. **用户级**：`~/.openclaw/skills/`（当前用户）
3. **项目级**：`./.openclaw/skills/`（当前项目）

优先级：**项目级 > 用户级 > 系统级**

这意味着你可以在项目中覆盖全局 Skill，实现项目特定的定制。

### 查看已安装的 Skill

```bash
# 列出所有已安装的 Skill
openclaw skills list

# 查看特定 Skill 的详情
openclaw skills info skill-name

# 检查 Skill 是否有更新
openclaw skills check-update

常见陷阱

陷阱 1：Skill 目录命名不规范

❌ 错误：MySkill/、my skill/、web-search-v2/
✅ 正确：my-skill/、web_search/（小写，用连字符或下划线）

陷阱 2：修改 SKILL.md 后不重启 Gateway

❌ 问题：改了 SKILL.md，但 Agent 行为没变
✅ 解决：Gateway 启动时会缓存 Skill，修改后需要重启生效
   openclaw gateway restart

陷阱 3：Skill 路径硬编码

❌ 错误：在代码里写死 ~/.openclaw/skills/my-skill/
✅ 正确：使用环境变量或 Gateway 提供的路径解析

实践建议

1. 从需求出发选择 Skill

   • 先明确要解决什么问题
   • 再搜索对应的 Skill（clawhub search <关键词>）
   • 阅读 SKILL.md 确认是否满足需求

2. 定期清理不用的 Skill

   • 每月检查一次已安装的 Skill
   • 删除长期不用的 Skill，减少 token 开销

3. 关注 Skill 的权限声明

   • 安装前阅读 SKILL.md 的权限部分
   • 对需要 exec/write 权限的 Skill 保持警惕
   • 优先选择来源可信的 Skill

4. 版本锁定重要 Skill

   • 生产环境使用 clawhub install skill-name@version
   • 避免自动更新带来的兼容性问题

5. 学会阅读源码

   • Skill 本质是 Markdown + 可选脚本
   • 有疑问时直接查看 ~/.openclaw/skills/<skill-name>/
   • 这是理解 Skill 工作原理的最佳方式

相关阅读

• 创建第一个 Skill —— 动手创建自己的 Skill
• 安装 Skills —— ClawHub 和本地安装详解
• 什么是子智能体 —— Agent 的另一种扩展方式
• 第一个 Agent —— Agent 基础概念

Skill 是 OpenClaw 的灵魂。理解 Skill，你就理解了如何让 Agent 从"能聊天"进化到"能干活"。