OpenClaw 技能开发与最佳实践：从入门到精通

┌─────────────────────────────────────────┐
│  Layer 1: 元数据 (始终加载，~100 词)      │
│  name + description → 触发判断          │
└─────────────────────────────────────────┘
                    ↓ 触发匹配
┌─────────────────────────────────────────┐
│  Layer 2: SKILL.md (触发后加载，<5000 词) │
│  工作流程 + 工具调用 + 资源配置           │
└─────────────────────────────────────────┘
                    ↓ 按需加载
┌─────────────────────────────────────────┐
│  Layer 3: 捆绑资源 (执行时使用)          │
│  scripts/ + references/ + assets/       │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│  Layer 1: 元数据 (始终加载)              │
│  - name: 技能名称                        │
│  - description: 触发条件和功能描述        │
│  大小：~100 词                           │
└─────────────────────────────────────────┘
                    ↓ 触发匹配
┌─────────────────────────────────────────┐
│  Layer 2: SKILL.md 主体 (触发后加载)     │
│  - 工作流程指导                          │
│  - 工具调用说明                          │
│  - 资源配置信息                          │
│  大小：<5000 词（建议<500 行）            │
└─────────────────────────────────────────┘
                    ↓ 按需加载
┌─────────────────────────────────────────┐
│  Layer 3: 捆绑资源 (按需加载)            │
│  - scripts/: 可执行脚本                  │
│  - references/: 参考文档                 │
│  - assets/: 输出资源                     │
│  大小：无限制（脚本可不加载直接执行）     │
└─────────────────────────────────────────┘

skill-name/
├── SKILL.md              # 必需：技能定义文件
│   ├── YAML Frontmatter  # 元数据（name, description）
│   └── Markdown 正文     # 使用指南
├── scripts/              # 可选：可执行脚本
│   ├── rotate_pdf.py
│   └── process_xlsx.sh
├── references/           # 可选：参考文档
│   ├── api_docs.md
│   └── workflows.md
└── assets/               # 可选：输出资源
    ├── templates/
    └── logo.png

# ✅ 好的描述：包含功能和触发场景
description: 技术调研标准流程，用于执行技术相关的调研和分析任务。
trigger_conditions:
  - 用户提到"调研"、"研究"、"分析技术"、"技术对比"

# ✅ 好的描述：明确列出使用场景
description: 综合文档创建、编辑和分析技能。使用当需要：(1) 创建新文档，(2) 修改内容，(3) 处理修订标记，(4) 添加评论

# ❌ 避免：过于模糊
description: 文档处理技能

# ❌ 避免：在正文中写触发条件（正文触发后才加载）
# SKILL.md 正文中不要写"当用户提到 X 时使用此技能"

用户请求："调研 LangGraph 并写博客"
    ↓
1. tech-research-sop 触发 → 生成调研报告
    ↓
2. tech-blog-writer 触发 → 基于报告创作文章
    ↓
3. blog-formatter 触发 → 格式化发布

mcp-builder 技能
    ↓
引用 references/python_mcp_server.md
    ↓
引用 references/evaluation.md

用户可能说：
- "帮我旋转这个 PDF"
- "合并这两个 PDF 文件"
- "从 PDF 中提取表格"

分析需求：
- 旋转 PDF → 需要 scripts/rotate_pdf.py
- 合并 PDF → 需要 scripts/merge_pdfs.py
- 提取表格 → 需要 scripts/extract_tables.py

# 语法
scripts/init_skill.py <skill-name> --path <output-directory>

# 示例：创建 weather 技能
scripts/init_skill.py weather --path ~/.openclaw/skills/weather

---
name: skill-name
description: 清晰描述功能和触发条件
version: 1.0  # 可选
author: your-name  # 可选
---

# 技能名称

简要介绍（1-2 段）

## 快速开始

最简使用示例

## 工作流程

详细步骤说明

## 资源配置

scripts/、references/、assets/ 使用说明

## 错误处理

常见问题和解决方案

## 最佳实践

使用建议和注意事项

#!/usr/bin/env python3
"""
旋转 PDF 文件

用法：python rotate_pdf.py input.pdf output.pdf 90
"""

import sys
from pypdf import PdfReader, PdfWriter

def rotate_pdf(input_path, output_path, degrees):
    """旋转 PDF 文件指定角度"""
    reader = PdfReader(input_path)
    writer = PdfWriter()

    for page in reader.pages:
        page.rotate(degrees)
        writer.add_page(page)

    with open(output_path, 'wb') as f:
        writer.write(f)

if __name__ == '__main__':
    if len(sys.argv) != 4:
        print("用法：python rotate_pdf.py input.pdf output.pdf degrees")
        sys.exit(1)

    input_path = sys.argv[1]
    output_path = sys.argv[2]
    degrees = int(sys.argv[3])

    rotate_pdf(input_path, output_path, degrees)
    print(f"✓ PDF 已旋转 {degrees}°，保存到 {output_path}")

# API 文档

## 认证

```bash
curl -H "Authorization: Bearer $API_KEY" \
     https://api.example.com/v1/resource

{
  "data": [...],
  "total": 1000
}

**组织模式**：

对于支持多框架/多领域的技能，按变体组织：

SKILL.md 包含选择指南：

```markdown
## 选择云提供商

- **AWS**: 需要 EC2、S3、Lambda → 读取 references/aws.md
- **GCP**: 需要 GKE、Cloud Run → 读取 references/gcp.md
- **Azure**: 需要 AKS、Functions → 读取 references/azure.md

技能使用方式：
1. 复制模板到工作区
2. 填充内容
3. 保存为最终文件

# 1. 语法检查（Python 脚本）
python -m py_compile scripts/your_script.py

# 2. 运行测试
pytest tests/  # 如果有测试套件

# 3. 实际使用测试
# 在 OpenClaw 中触发技能，验证行为

# 4. 打包验证
scripts/package_skill.py ~/.openclaw/skills/your-skill

# 基本用法
scripts/package_skill.py <path/to/skill-folder>

# 指定输出目录
scripts/package_skill.py ~/.openclaw/skills/weather ./dist

❌ 验证失败：
- description 字段缺少触发条件
- scripts/rotate_pdf.py 缺少 shebang

修复后重新运行打包命令。

1. 在真实任务中使用技能
2. 记录问题和低效点
3. 更新 SKILL.md 或资源
4. 重新测试
5. 重新打包

# ✅ 好的命名
tech-research-sop      # 清晰描述功能
cognitive-memory       # 简洁且有意义
frontend-design        # 领域 + 功能

# ❌ 避免的命名
skill1                 # 无意义
my-awesome-skill       # 主观描述
pdf-processor-v2-final # 版本信息放 version 字段

# ✅ 好的命名
scripts/rotate_pdf.py
references/api_docs.md
assets/logo.png

# ❌ 避免的命名
scripts/script1.py     # 无意义
references/doc.md      # 太通用

# ❌ 过于冗长的 SKILL.md（避免）

## API 端点详解

### GET /users
这个端点返回用户列表。它接受多个参数：
- page: 页码，从 1 开始
- limit: 每页数量，默认 20
- sort: 排序字段，可选 name/email/created_at
...
（继续 200 行 API 文档）

# ✅ 简洁的 SKILL.md（推荐）

## API 使用

调用用户 API：
```bash
curl -H "Authorization: Bearer $API_KEY" \
     "https://api.example.com/users?page=1&limit=20"

#### 渐进式披露模式

**模式 1：基础 + 高级**

```markdown
## PDF 处理

### 基础用法
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

**模式 2：按领域组织**

```markdown
## 数据库查询

根据查询类型加载对应文档：
- **财务数据**（收入、账单）：读取 references/finance.md
- **销售数据**（机会、管道）：读取 references/sales.md
- **产品数据**（API 使用、功能）：读取 references/product.md

## 云部署

选择云提供商后加载对应文档：
- **AWS**：读取 references/aws.md
- **GCP**：读取 references/gcp.md  
- **Azure**：读取 references/azure.md

#!/usr/bin/env python3
"""处理 Excel 文件"""

import sys
import os
from openpyxl import load_workbook

def process_xlsx(input_path, output_path):
    """处理 Excel 文件，添加计算列"""

    # 验证输入文件
    if not os.path.exists(input_path):
        raise FileNotFoundError(f"输入文件不存在：{input_path}")

    if not input_path.endswith('.xlsx'):
        raise ValueError(f"仅支持 .xlsx 文件：{input_path}")

    try:
        wb = load_workbook(input_path)
        ws = wb.active

        # 添加计算列
        for row in ws.iter_rows(min_row=2):
            if row[0].value and row[1].value:
                row[2].value = row[0].value * row[1].value

        wb.save(output_path)
        return True

    except PermissionError as e:
        print(f"❌ 权限错误：无法访问文件", file=sys.stderr)
        print(f"详情：{e}", file=sys.stderr)
        return False

    except Exception as e:
        print(f"❌ 处理失败：{e}", file=sys.stderr)
        return False

if __name__ == '__main__':
    if len(sys.argv) != 3:
        print("用法：python process_xlsx.py input.xlsx output.xlsx")
        sys.exit(1)

    success = process_xlsx(sys.argv[1], sys.argv[2])
    sys.exit(0 if success else 1)

## 常见问题

### 问题：脚本运行时提示"模块未找到"
**原因**：缺少 Python 依赖
**解决**：
```bash
pip install pypdf pdfplumber openpyxl

#### 优雅降级

当依赖服务不可用时，提供降级方案：

```markdown
## 搜索服务降级

**正常流程**：
1. DuckDuckGo 初步搜索
2. Brave Search 深度搜索
3. Tavily 获取高质量结果

**降级方案**（搜索服务不可用时）：
- 使用已有技术资料库（tech-research/articles/）
- 使用历史调研报告
- 标注"搜索不可用，基于已有资料"

# tests/test_rotate_pdf.py
import pytest
from scripts.rotate_pdf import rotate_pdf

def test_rotate_pdf_creates_file(tmp_path):
    """测试 PDF 旋转生成输出文件"""
    input_pdf = tmp_path / "input.pdf"
    output_pdf = tmp_path / "output.pdf"

    # 创建测试 PDF（使用已知库）
    create_test_pdf(input_pdf)

    # 执行旋转
    rotate_pdf(str(input_pdf), str(output_pdf), 90)

    # 验证输出
    assert output_pdf.exists()
    assert output_pdf.stat().st_size > 0

#!/bin/bash
# tests/integration_test.sh

# 测试完整工作流程
echo "测试 PDF 处理流程..."

# 1. 准备测试文件
cp test_data/sample.pdf /tmp/test_input.pdf

# 2. 运行脚本
python scripts/rotate_pdf.py /tmp/test_input.pdf /tmp/test_output.pdf 90

# 3. 验证结果
if [ -f /tmp/test_output.pdf ]; then
    echo "✓ 测试通过"
    exit 0
else
    echo "✗ 测试失败：输出文件未生成"
    exit 1
fi

## 触发测试用例

### 应触发的请求
- "调研一下 LangChain 框架"
- "帮我做技术对比分析"
- "研究微服务架构"

### 不应触发的请求
- "今天天气如何"（weather 技能）
- "写个 Python 脚本"（coding-agent 技能）
- "打开浏览器"（browser 技能）

# 1. 检查 skill 元数据
cat ~/.openclaw/skills/your-skill/SKILL.md | head -10

# 2. 验证 description 是否包含触发词
# 确保 description 包含用户可能说的关键词

# 3. 检查技能是否被禁用
cat ~/.openclaw/openclaw.json | grep -A 10 '"skills"'

# 4. 重启 Gateway
openclaw gateway restart

# ❌ 模糊描述
description: 文档处理技能

# ✅ 具体描述
description: 综合文档创建、编辑和分析。使用当需要：(1) 创建新文档，(2) 修改内容，(3) 处理修订标记，(4) 添加评论，(5) 提取文本

# 1. 检查 SKILL.md 正文
cat ~/.openclaw/skills/your-skill/SKILL.md

# 2. 验证脚本可运行
python ~/.openclaw/skills/your-skill/scripts/your_script.py --help

# 3. 检查依赖是否安装
pip list | grep your-dependency

# 4. 查看 Gateway 日志
openclaw logs --follow

# 1. 检查 SKILL.md 大小
wc -l ~/.openclaw/skills/your-skill/SKILL.md

# 2. 检查 references/ 总大小
du -sh ~/.openclaw/skills/your-skill/references/

# 3. 查看上下文使用情况
# 在对话中询问："当前上下文使用情况如何？"

# 1. 列出所有技能
ls ~/.openclaw/skills/

# 2. 检查技能描述重叠
grep -r "description:" ~/.openclaw/skills/*/SKILL.md

# 3. 测试边界情况
# 发送模糊请求，观察哪个技能触发

import logging

logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

logger = logging.getLogger(__name__)

def process_file(path):
    logger.info(f"开始处理文件：{path}")
    # ... 处理逻辑
    logger.debug(f"读取到 {len(content)} 字节")

mkdir -p tests/test_data
cp sample.pdf tests/test_data/
cp sample.xlsx tests/test_data/

# 在脚本中使用测试数据
python scripts/process.py tests/test_data/sample.pdf

#!/bin/bash
# tests/simulate_requests.sh

requests=(
    "调研一下 LangChain"
    "分析微服务架构"
    "对比 React 和 Vue"
)

for req in "${requests[@]}"; do
    echo "测试请求：$req"
    # 发送请求到 OpenClaw（使用 CLI 或 API）
    # 观察技能触发情况
done

# Python 脚本性能分析
python -m cProfile -o output.prof scripts/your_script.py

# 查看分析结果
snakeviz output.prof

# 或使用 py-spy 实时分析
py-spy record -o profile.svg -- python scripts/your_script.py

# ✅ 好的描述（包含具体触发场景）
description: 技术调研标准流程。使用当：
  - 用户提到"调研"、"研究"、"分析技术"
  - 需要做技术对比、竞品分析
  - 需要生成结构化调研报告

# ❌ 避免（过于模糊）
description: 技术调研技能

skill-name/
├── SKILL.md              # 必需，<500 行
├── scripts/              # 可选，可执行脚本
├── references/           # 可选，详细文档
└── assets/               # 可选，输出资源