开发你的第一个 OpenClaw Skill

71次阅读

开发你的第一个 OpenClaw Skill

用了这么久 OpenClaw，你是否想过：为什么有些任务 AI 能秒懂，有些却要反复解释？答案就是 Skill。本文带你从零开发一个 Skill，让你的 OpenClaw 真正”懂”你的需求。

01 为什么要开发 Skill？

重复解释的痛苦

想象这个场景：

你：‘帮我生成一个二维码’
AI：‘好的，请问二维码内容是什么？尺寸多大？要不要 logo？’
你：‘链接是 https://example.com，尺寸 300×300，不要 logo’
AI：‘好的，正在生成…’
…第二天…
你：‘再帮我生成一个二维码’
AI：‘好的，请问二维码内容是什么？’
你：‘😫 昨天不是刚说过吗！’

问题核心： AI 没有”记忆”你的偏好和常用流程。

Skill 的价值

Skill 的本质： 把”我知道怎么做”变成”OpenClaw 知道怎么做”。

02 核心概念：Skill 是什么？

Skill 的定义

Skill 是一个 自包含的知识包，包含：

  1. SKILL.md —— 使用说明（何时触发、如何执行）

  2. scripts/ —— 可执行脚本（Python/Bash 等）

  3. references/ —— 参考资料（API 文档、规范等）

  4. assets/ —— 资源文件（模板、图片等）

my-skill/
├── SKILL.md              # 必需：使用说明
├── scripts/              # 可选：可执行脚本
│   └── generate.py
├── references/           # 可选：参考资料
│   └── api_docs.md
└── assets/               # 可选：资源文件
    └── template.html

Skill 的工作原理

OpenClaw 采用 渐进式披露 设计：

┌─────────────────────────────────────────────┐
│  Level 1: Metadata (始终加载)                │
│  ├── name: qr-code-generator                │
│  └── description: 生成二维码...              │
│  ~100 tokens                                 │
├─────────────────────────────────────────────┤
│  Level 2: SKILL.md (触发后加载)              │
│  ├── 使用说明                                │
│  ├── 代码示例                                │
│  └── 资源引用                                │
│  < 5000 tokens                               │
├─────────────────────────────────────────────┤
│  Level 3: Bundled Resources (按需加载)       │
│  ├── references/api_docs.md                  │
│  └── scripts/ (可直接执行，不占用上下文)      │
│  无限制                                       │
└─────────────────────────────────────────────┘

关键优势： – 不使用时零开销 – 使用时精准加载 – 脚本可直接执行，不占用上下文窗口

何时应该开发 Skill？

适合开发 Skill 的场景：

不需要 Skill 的场景： – 一次性任务 – 通用知识（AI 已掌握）– 简单到一句话能说清的操作

03 实战案例：开发 QR Code Generator Skill

接下来，我们将从零开发一个 二维码生成器 Skill，完整演示 Skill 开发流程。

需求分析

目标： 让用户只需说”生成二维码”，就能快速得到结果。

支持的功能： 1. 生成标准二维码 2. 支持自定义尺寸 3. 支持添加中心 logo 4. 批量生成多个二维码

Step 1: 初始化 Skill

使用 init_skill.py 脚本创建 Skill 模板：

# 找到 init_skill.py 脚本路径
INIT_SCRIPT="$HOME/.nvm/versions/node/v22.17.0/lib/node_modules/openclaw/skills/skill-creator/scripts/init_skill.py"

# 创建 Skill
python3 "$INIT_SCRIPT" qr-code-generator \
  --path ~/.openclaw/skills \
  --resources scripts,assets \
  --examples

输出：

[OK] Created skill directory: /home/east/.openclaw/skills/qr-code-generator
[OK] Created SKILL.md
[OK] Created scripts/example.py
[OK] Created assets/example_asset.txt

Next steps:
1. Edit SKILL.md to complete the TODO items and update the description
2. Customize or delete the example files in scripts/, references/, and assets/
3. Run the validator when ready to check the skill structure

生成的目录结构：

qr-code-generator/
├── SKILL.md
├── scripts/
│   └── example.py
└── assets/
    └── example_asset.txt

Step 2: 编写二维码生成脚本

替换 scripts/example.py 为实际的二维码生成脚本：

#!/usr/bin/env python3
"""
QR Code Generator - 二维码生成器

Usage:
    python generate.py <content> [options]
    python generate.py "https://example.com" --output ./qrcode.png --size 10
    python generate.py "https://example.com" --logo ./logo.png --size 15

Options:
    --output, -o    输出文件路径 (默认: ./qrcode.png)
    --size, -s      模块大小 (默认: 10)
    --logo, -l      中心 logo 图片路径
    --batch, -b     批量模式，从文件读取内容列表
"""

import argparse
import os
import sys
from pathlib import Path

try:
    import qrcode
    from PIL import Image
except ImportError:
    print("[ERROR] 请先安装依赖: pip install qrcode[pil] Pillow")
    sys.exit(1)

def create_qr_code(content, output_path, size=10, logo_path=None):
    """
    生成二维码

    Args:
        content: 二维码内容
        output_path: 输出文件路径
        size: 模块大小
        logo_path: 中心 logo 路径（可选）"""
    # 创建 QR 码实例
    qr = qrcode.QRCode(
        version=None,  # 自动选择版本
        error_correction=qrcode.constants.ERROR_CORRECT_H,  # 高容错率（支持 logo）box_size=size,
        border=4,
    )

    qr.add_data(content)
    qr.make(fit=True)

    # 生成图像
    img = qr.make_image(fill_color="black", back_color="white")

    # 添加 logo（如果提供）if logo_path and os.path.exists(logo_path):
        logo = Image.open(logo_path)

        # 计算 logo 大小（占二维码的 25%）qr_width, qr_height = img.size
        logo_size = int(qr_width * 0.25)

        # 调整 logo 大小
        logo = logo.resize((logo_size, logo_size), Image.Resampling.LANCZOS)

        # 计算居中位置
        logo_pos = ((qr_width - logo_size) // 2, (qr_height - logo_size) // 2)

        # 粘贴 logo
        img.paste(logo, logo_pos, logo if logo.mode == 'RGBA' else None)

    # 保存
    img.save(output_path)
    print(f"[OK] 二维码已生成: {output_path}")
    print(f"    内容: {content}")
    print(f"    尺寸: {img.size}")

    return output_path

def batch_generate(input_file, output_dir, size=10, logo_path=None):
    """
    批量生成二维码

    Args:
        input_file: 包含内容列表的文件（每行一个）output_dir: 输出目录
        size: 模块大小
        logo_path: 中心 logo 路径
    """
    output_dir = Path(output_dir)
    output_dir.mkdir(parents=True, exist_ok=True)

    with open(input_file, 'r', encoding='utf-8') as f:
        lines = [line.strip() for line in f if line.strip()]

    print(f"[INFO] 批量生成 {len(lines)} 个二维码...")

    for idx, content in enumerate(lines, 1):
        # 生成文件名（使用内容的前 20 个字符）safe_name = "".join(c if c.isalnum() else "_" for c in content[:20])
        output_path = output_dir / f"qrcode_{idx:03d}_{safe_name}.png"

        create_qr_code(content, str(output_path), size, logo_path)

    print(f"[OK] 批量生成完成，输出目录: {output_dir}")

def main():
    parser = argparse.ArgumentParser(description="QR Code Generator - 二维码生成器 ")
    parser.add_argument("content", nargs="?", help=" 二维码内容 ")
    parser.add_argument("-o", "--output", default="./qrcode.png",
                        help=" 输出文件路径 (默认: ./qrcode.png)")
    parser.add_argument("-s", "--size", type=int, default=10,
                        help=" 模块大小 (默认: 10)")
    parser.add_argument("-l", "--logo", help=" 中心 logo 图片路径 ")
    parser.add_argument("-b", "--batch", help=" 批量模式，从文件读取内容列表 ")

    args = parser.parse_args()

    # 批量模式
    if args.batch:
        if not os.path.exists(args.batch):
            print(f"[ERROR] 文件不存在: {args.batch}")
            sys.exit(1)
        batch_generate(args.batch, args.output, args.size, args.logo)
        return

    # 单条模式
    if not args.content:
        parser.print_help()
        sys.exit(1)

    create_qr_code(args.content, args.output, args.size, args.logo)

if __name__ == "__main__":
    main()

测试脚本：

# 安装依赖
pip install qrcode[pil] Pillow

# 测试单条生成
python3 ~/.nvm/versions/node/v22.17.0/lib/node_modules/openclaw/skills/qr-code-generator/scripts/generate.py \
  "https://openclaw.ai" \
  --output ./test-qr.png \
  --size 15

# 测试批量生成
echo -e "https://example.com\nhttps://openclaw.ai\nhttps://github.com" > /tmp/urls.txt
python3 ~/.nvm/versions/node/v22.17.0/lib/node_modules/openclaw/skills/qr-code-generator/scripts/generate.py \
  --batch /tmp/urls.txt \
  --output ./batch-qr \
  --size 10

Step 3: 编写 SKILL.md

替换 SKILL.md 为完整的使用说明：

---
name: qr-code-generator
description: 生成二维码图片。支持自定义尺寸、添加中心 logo、批量生成。Use when: (1) 用户需要生成二维码, (2) 需要批量生成多个二维码, (3) 需要在二维码中添加 logo。触发词：" 生成二维码 "、" 创建 QR code"、" 批量生成二维码 "。---

# QR Code Generator

生成二维码图片，支持自定义尺寸、添加中心 logo、批量生成。## 快速开始

### 单条生成

```bash
python3 ~/.nvm/versions/node/v22.17.0/lib/node_modules/openclaw/skills/qr-code-generator/scripts/generate.py \
  "https://example.com" \
  --output ./qrcode.png \
  --size 15

带 Logo 的二维码

python3 ~/.nvm/versions/node/v22.17.0/lib/node_modules/openclaw/skills/qr-code-generator/scripts/generate.py \
  "https://example.com" \
  --logo ./assets/logo.png \
  --output ./qrcode-with-logo.png \
  --size 20

批量生成

# 创建内容列表文件
cat > /tmp/urls.txt << EOF
https://example.com/page1
https://example.com/page2
https://example.com/page3
EOF

# 批量生成
python3 ~/.nvm/versions/node/v22.17.0/lib/node_modules/openclaw/skills/qr-code-generator/scripts/generate.py \
  --batch /tmp/urls.txt \
  --output ./batch-output \
  --size 10

参数说明

尺寸参考

依赖安装

首次使用前需要安装 Python 依赖：

pip install qrcode[pil] Pillow

注意事项

  1. Logo 尺寸：建议 logo 不超过二维码的 25%，否则可能影响扫描

  2. 容错率：使用高容错率（ERROR_CORRECT_H），支持 logo 遮挡

  3. 批量模式：内容文件每行一个，空行会被跳过

  4. 输出目录：批量模式下会自动创建目录


**SKILL.md 编写要点：**

1. **Frontmatter（YAML 头部）**：必须包含 `name` 和 `description`
2. **Description 是关键 **：决定 Skill 何时被触发，要写清楚使用场景和触发词
3. ** 结构清晰 **：快速开始 → 详细说明 → 注意事项
4. ** 代码可复现 **：所有示例都能直接运行

### Step 4: 添加资源文件

创建默认 logo 模板（可选）：```bash
# 创建简单的默认 logo
mkdir -p ~/.nvm/versions/node/v22.17.0/lib/node_modules/openclaw/skills/qr-code-generator/assets

# 使用 ImageMagick 创建简单 logo（或手动放置图片）convert -size 100x100 xc:lightblue \
  -pointsize 30 -fill black -gravity center \
  -annotate +0+0 "LOGO" \
  ~/.nvm/versions/node/v22.17.0/lib/node_modules/openclaw/skills/qr-code-generator/assets/default-logo.png

目录结构：

qr-code-generator/
├── SKILL.md
├── scripts/
│   └── generate.py
└── assets/
    └── default-logo.png

04 进阶技巧：scripts/references/assets 的使用场景

scripts/ —— 可执行脚本

适用场景： – 需要确定性结果的任务（如文件格式转换）– 重复编写的代码逻辑 – 复杂计算或数据处理

最佳实践：

# ✅ 好的脚本设计
#!/usr/bin/env python3
"""
清晰的文档字符串，说明用途和用法
"""
import argparse  # 支持命令行参数

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("input", help=" 输入文件 ")
    parser.add_argument("--output", "-o", help=" 输出文件 ")
    args = parser.parse_args()
    # ... 实现逻辑

if __name__ == "__main__":
    main()

references/ —— 参考资料

适用场景： – API 文档（太长不适合放 SKILL.md）– 数据库 schema – 公司内部规范 – 复杂流程的详细说明

示例结构：

my-api-skill/
├── SKILL.md
└── references/
    ├── api-reference.md      # API 详细文档
    ├── authentication.md     # 认证流程
    ├── error-codes.md        # 错误码对照表
    └── examples/             # 示例代码
        ├── basic-query.py
        └── advanced-filter.py

在 SKILL.md 中引用：

## API 认证

详细认证流程参见 [references/authentication.md](references/authentication.md)。## 错误处理

常见错误码对照表参见 [references/error-codes.md](references/error-codes.md)。

assets/ —— 资源文件

适用场景： – 模板文件（PPT、Word、Excel）– 品牌素材（logo、字体）– 前端项目模板 – 示例数据文件

使用方式：

# 在脚本中使用 assets
import os

SKILL_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
ASSETS_DIR = os.path.join(SKILL_DIR, "assets")

# 加载模板
template_path = os.path.join(ASSETS_DIR, "template.pptx")

05 打包与发布

使用 package_skill.py 打包

# 找到 package_skill.py 脚本路径
PACKAGE_SCRIPT="$HOME/.nvm/versions/node/v22.17.0/lib/node_modules/openclaw/skills/skill-creator/scripts/package_skill.py"

# 打包 Skill
python3 "$PACKAGE_SCRIPT" ~/.nvm/versions/node/v22.17.0/lib/node_modules/openclaw/skills/qr-code-generator

输出：

Packaging skill: /home/east/.openclaw/skills/qr-code-generator

Validating skill...
[OK] Validation passed: Skill structure is valid

  Added: qr-code-generator/SKILL.md
  Added: qr-code-generator/scripts/generate.py
  Added: qr-code-generator/assets/default-logo.png

[OK] Successfully packaged skill to: /home/east/qr-code-generator.skill

分发 Skill

打包后的 .skill 文件是一个 zip 格式的压缩包，可以：

  1. 分享给团队成员

    # 发送给同事
cp qr-code-generator.skill /shared/skills/

# 同事安装（将 .skill 文件复制到对方机器的 ~/.openclaw/skills/ 目录）cp /shared/skills/qr-code-generator.skill ~/.openclaw/skills/

  2. 发布到 Skill 市场（ClawHub）

    clawhub publish qr-code-generator.skill

  3. 版本管理

    # 命名包含版本
mv qr-code-generator.skill qr-code-generator-v1.0.0.skill

06 FAQ

Q1: Skill 和普通的脚本有什么区别？

回答： – 普通脚本：需要手动找到、阅读、理解、修改 – Skill：AI 知道何时使用、如何使用，用户只需说需求

类比：– 脚本 = 工具箱里的工具 – Skill = 知道什么时候用什么工具的助手

Q2: 如何让 Skill 更容易被触发？

回答： 优化 description 字段：

# ❌ 差的 description
description: A tool for QR codes

# ✅ 好的 description  
description: 生成二维码图片。支持自定义尺寸、添加中心 logo、批量生成。Use when: (1) 用户需要生成二维码, (2) 需要批量生成多个二维码, 
  (3) 需要在二维码中添加 logo。触发词：" 生成二维码 "、" 创建 QR code"。

要点： – 明确使用场景（Use when）– 列出触发关键词 – 描述具体功能

Q3: Skill 可以调用其他 Skill 吗？

回答： 不可以直接调用，但可以通过以下方式协作：

  1. 在 SKILL.md 中说明组合使用场景

    ## 与其他 Skill 配合

- 配合 `feishu-doc`：生成二维码后自动插入飞书文档
- 配合 `openai-image-gen`：生成带背景的艺术二维码

  2. 在脚本中调用 OpenClaw CLI

    import subprocess

# 调用其他 Skill 的功能
subprocess.run([
    "openclaw", "feishu-doc", "upload",
    "--doc-token", doc_token,
    "--image", qr_path
])

Q4: 如何调试 Skill？

回答：

  1. 验证 Skill 结构

    python3 package_skill.py /path/to/skill --dry-run

  2. 测试触发词 在 OpenClaw 中输入 Skill 的触发词，看是否正确加载

  3. 检查日志

    # 查看 OpenClaw 日志
tail -f ~/.openclaw/logs/agent.log

  4. 逐步测试脚本

    # 先单独测试脚本
python3 ~/.nvm/versions/node/v22.17.0/lib/node_modules/openclaw/skills/my-skill/scripts/my_script.py --help

Q5: Skill 的命名规范是什么？

回答：

  • 格式：小写字母、数字、连字符（kebab-case）

  • 长度：不超过 64 个字符

  • 风格：动词开头，描述功能

  • 示例：

    • ✅ qr-code-generator

    • ✅ pdf-to-markdown

    • ✅ feishu-doc-exporter

    • ❌ QR_Code_Generator（有大写和下划线）

    • ❌ my-skill-v1.0.0（包含版本号）

Q6: 如何更新已安装的 Skill？

回答：

# 1. 重新打包
python3 ~/.nvm/versions/node/v22.17.0/lib/node_modules/openclaw/skills/skill-creator/scripts/package_skill.py ~/.nvm/versions/node/v22.17.0/lib/node_modules/openclaw/skills/my-skill

# 2. 重新安装（复制到 skills 目录覆盖）cp my-skill.skill ~/.nvm/versions/node/v22.17.0/lib/node_modules/openclaw/skills/

# 3. 重启 Gateway
openclaw gateway restart

07 总结

Skill 开发流程

1. 需求分析 ──→ 明确 Skill 要解决什么问题
      ↓
2. 初始化 ────→ 使用 init_skill.py 创建模板
      ↓
3. 编写脚本 ──→ 实现核心功能（scripts/）↓
4. 编写文档 ──→ 完善 SKILL.md（重点是 description）↓
5. 添加资源 ──→ 根据需要添加 references/、assets/
      ↓
6. 测试验证 ──→ 确保脚本可运行、文档可理解
      ↓
7. 打包发布 ──→ 使用 package_skill.py 生成 .skill 文件

核心原则

下一步

  • 回顾你经常重复解释的任务，尝试封装成 Skill

  • 与团队共享 Skill，建立内部 Skill 库

  • 关注 Skill 的使用情况，持续迭代优化

本文是 OpenClaw 进阶技能系列第 11 篇，下一篇：《ClawHub 技能市场完全指南》

系列回顾： 1. OpenClaw + Codex：让 AI 帮你写代码 2. 用 OpenClaw 搭建自动化代码审查工作流 3. OpenClaw 批量生图实战：从 Prompt 到成品画廊 4. OpenClaw 语音工作流：听写、合成、通话一条龙 5. OpenClaw 浏览器自动化：解放你的重复操作 6. OpenClaw 笔记自动化：一句话记到所有平台 7. 用 OpenClaw 打造语音智能家居中枢 8. OpenClaw + 飞书：企业自动化完全指南 9. OpenClaw 媒体处理：视频、图片、GIF 全搞定 10. OpenClaw 安全运维：自动化巡检与加固 11. 开发你的第一个 OpenClaw Skill �的第一个 OpenClaw

正文完
发表至： 技术
2026-06-02
 

近期文章

近期评论

您尚未收到任何评论。