一、引言

OpenClaw 的 Skills 生态系统是其最强大的特性之一。通过编写自定义 Skill，你可以为 AI 助手赋予全新的能力——从查询数据库到控制智能家居，从生成报告到自动化运维。本文将带你从零开始，完整地创建一个自定义 OpenClaw Skill，并深入理解其内部机制。

二、Skill 是什么？

在 OpenClaw 中，Skill 是一个包含特定元数据和指令的目录，它告诉 AI 助手：

• 何时使用：匹配特定类型的任务
• 如何使用：提供详细的步骤和示例
• 有何限制：定义安全边界和权限

每个 Skill 的核心文件是 SKILL.md，它使用 Markdown 格式编写，包含从识别触发条件到执行步骤的完整指令。

三、Skill 目录结构

一个标准的 OpenClaw Skill 目录结构如下：

my-skill/
├── SKILL.md          # 核心指令文件（必需）
├── tool-config.json  # 工具配置（可选）
├── assets/           # 静态资源（可选）
│   ├── icon.png
│   └── templates/
└── tests/            # 测试文件（可选）
    └── test-skill.sh

四、从零创建自定义 Skill

我们将创建一个名为 Server Monitor 的 Skill，它可以检查服务器状态、查看日志和监控资源使用情况。

4.1 创建目录结构

mkdir -p ~/.openclaw/workspace/skills/server-monitor/assets
touch ~/.openclaw/workspace/skills/server-monitor/SKILL.md

4.2 编写 SKILL.md

SKILL.md 是 Skill 的核心，它使用特定的结构来定义技能的行为：

# Server Monitor

监控 Linux 服务器状态，包括系统资源、进程、磁盘和网络。

## 适用场景

- 用户询问服务器状态（"服务器怎么样了？"、"检查一下系统负载"）
- 需要查看系统资源使用情况（CPU、内存、磁盘）
- 需要查看进程运行状态
- 需要检查网络连接和端口监听

## 不适用场景

- 需要修改系统配置（请使用专门的配置管理工具）
- 需要安装软件包（仅监控，不修改）

## 使用方式

当用户请求服务器状态检查时，按以下步骤执行：

### 1. 系统资源检查

```bash
# CPU 负载
cat /proc/loadavg

# 内存使用
free -h

# 磁盘使用
df -h

# 运行时间
uptime
```

### 2. 进程检查

```bash
# 查看 CPU 占用最高的 5 个进程
ps aux --sort=-%cpu | head -6

# 查看内存占用最高的 5 个进程
ps aux --sort=-%mem | head -6
```

### 3. 网络检查

```bash
# 监听端口
ss -tlnp

# 网络连接统计
ss -s
```

### 4. 日志检查

```bash
# 最近的系统日志
journalctl -n 20 --no-pager

# 最近的错误日志
journalctl -p err -n 10 --no-pager
```

## 输出格式

将结果整理为以下格式返回给用户：

```
📊 服务器状态报告
━━━━━━━━━━━━━━━━━━━━━━
🖥️  系统负载: [load1] [load5] [load15]
💾 内存: [used]/[total] ([percent]%)
💿 磁盘: [used]/[total] ([percent]%)
⏱️  运行时间: [uptime]

🔥 CPU Top 5:
1. [process] - [cpu]%
2. [process] - [cpu]%

📡 监听端口:
- [port] ([service])

⚠️ 最近错误:
- [error message]
```

## 安全注意事项

- 只读操作，不修改任何系统文件或配置
- 不执行需要 root 权限的命令
- 不查看敏感文件内容（如 /etc/shadow）
- 日志检查限制在最近 20 条以内

五、Skill 注册与发现

创建 SKILL.md 后，OpenClaw 会自动扫描 skills/ 目录下的所有子目录。Skill 的发现机制如下：

5.1 自动扫描

OpenClaw 在启动时会扫描 ~/.openclaw/workspace/skills/ 目录，查找所有包含 SKILL.md 的子目录。每个找到的 Skill 会被注册到技能调度系统中。

5.2 匹配机制

当用户发送消息时，OpenClaw 的调度器会基于以下维度匹配 Skill：

• 关键词匹配：消息中包含 “服务器”、”状态”、”监控” 等关键词
• 意图识别：分析用户意图是否匹配 Skill 的适用场景
• 上下文匹配：根据对话历史判断是否需要调用该 Skill

六、高级 Skill 开发

6.1 工具配置 (tool-config.json)

你可以通过 tool-config.json 为 Skill 配置特定的工具权限：

{
  "name": "server-monitor",
  "version": "1.0.0",
  "description": "Server monitoring skill",
  "tools": {
    "allow": ["exec", "read"],
    "deny": ["write", "edit"],
    "exec": {
      "allowed_commands": [
        "cat /proc/loadavg",
        "free -h",
        "df -h",
        "uptime",
        "ps aux --sort=-%cpu | head -6",
        "ss -tlnp",
        "journalctl -n 20 --no-pager"
      ],
      "deny_patterns": [
        "rm",
        "mkfs",
        "dd",
        "chmod",
        "chown",
        ">",
        "| sudo"
      ]
    }
  },
  "security": {
    "sandbox": true,
    "network_access": false,
    "max_execution_time": 30
  }
}

6.2 模板与动态内容

Skill 可以包含模板文件，用于生成结构化的输出：

<!-- assets/templates/report.html -->
<div class="server-report">
    <h2>📊 {{title}}</h2>
    <div class="metrics">
        <div class="metric">
            <span class="label">CPU 负载</span>
            <span class="value {{cpu_class}}">{{cpu_load}}</span>
        </div>
        <div class="metric">
            <span class="label">内存</span>
            <span class="value {{mem_class}}">{{mem_used}}/{{mem_total}}</span>
        </div>
    </div>
</div>

七、Skill 生命周期

理解 Skill 的生命周期有助于编写更可靠的技能：

八、调试与测试

8.1 日志调试

在 SKILL.md 的开发过程中，可以通过以下方式调试：

• 逐步执行：在 SKILL.md 中分步骤描述，便于定位问题
• 输出检查：在每个步骤后检查命令输出
• 错误处理：在 SKILL.md 中包含错误处理指令

8.2 测试脚本

#!/bin/bash
# tests/test-skill.sh - Server Monitor Skill 测试

echo "=== Server Monitor Skill Test ==="

# 测试 1: 检查 SKILL.md 存在
if [ -f "../SKILL.md" ]; then
    echo "✅ SKILL.md 存在"
else
    echo "❌ SKILL.md 缺失"
    exit 1
fi

# 测试 2: 检查必要字段
if grep -q "## 适用场景" ../SKILL.md; then
    echo "✅ 适用场景已定义"
else
    echo "❌ 缺少适用场景"
fi

# 测试 3: 检查命令可用性
for cmd in free df uptime ps ss journalctl; do
    if command -v $cmd &>/dev/null; then
        echo "✅ $cmd 可用"
    else
        echo "⚠️  $cmd 不可用（可能需要安装）"
    fi
done

echo "=== 测试完成 ==="

九、最佳实践

9.1 设计原则

• 单一职责：每个 Skill 只做一件事，做得专而精
• 明确边界：清晰定义适用和不适用场景，避免误触发
• 安全优先：始终考虑权限最小化原则
• 可测试性：提供测试脚本，确保 Skill 按预期工作

9.2 常见陷阱

十、总结

OpenClaw 的 Skill 系统为 AI 助手提供了强大的扩展能力。通过本文的学习，你应该已经掌握了：

• Skill 的目录结构和核心文件 SKILL.md 的编写方法
• Skill 的注册、匹配和执行机制
• 如何通过 tool-config.json 控制权限
• 测试和调试的最佳实践

随着你对 Skill 开发的深入，可以探索更高级的用法——如多步骤工作流、外部 API 集成、定时任务等。OpenClaw 的 Skills 生态正在快速发展，社区中已有数百个开源 Skill 可供参考和复用。