OpenClaw Skills 编写完整教程

什么是 Skills

Skills 是模块化、自包含的包，用于扩展 AI Agent 的能力。它们提供特定领域的专业知识、工作流程和工具。

Skills 的作用：
1. 提供专业化工作流程 – 特定领域的多步骤流程
2. 工具集成 – 处理特定文件格式或 API 的说明
3. 领域专业知识 – 公司特定知识、业务逻辑
4. 打包资源 – 脚本、参考文档和输出所需的资产

类比： Skills 就像是”入职指南”——将 AI Agent 从通用助手转变为特定领域的专家。

Skills 核心原则

1. 简洁为王

上下文窗口是公共资源。Skills 共享上下文窗口与系统提示、对话历史、其他 Skills 元数据和实际用户请求。

默认假设： AI Agent 已经非常聪明。只添加 AI Agent 不已经拥有的上下文。

每一段信息都要问：”AI Agent 真的需要这个解释吗？”
每一段文字都要问：”这段文字值得它的 token 成本吗？”
优先简洁的示例，而非冗长的解释

2. 设置适当的自由度

匹配任务脆弱性和变化的程度：

高自由度（文本指令） – 多种方法有效，决策依赖上下文
中自由度（带参数的伪代码或脚本） – 存在首选模式，一些变体可接受
低自由度（特定脚本、少量参数） – 操作脆弱且易错，一致性至关重要

类比： 将 AI Agent 想象为在探索路径：
– 窄桥需要护栏（低自由度）
– 开阔田野允许许多路线（高自由度）

Skill 目录结构

每个 Skill 由必需的 SKILL.md 文件和可选的打包资源组成：

skill-name/
├── SKILL.md (必需)
│   ├── YAML 前置元数据（必需）
│   │   ├── name: (必需)
│   │   └── description: (必需)
│   └── Markdown 指令（必需）
└── 打包资源（可选）
    ├── scripts/          - 可执行代码（Python/Bash 等）
    ├── references/       - 旨在按需加载到上下文的文档
    └── assets/           - 输出中使用的文件（模板、图标、字体等）

SKILL.md（必需）

每个 SKILL.md 由以下部分组成：

前置元数据（YAML）： 包含 name 和 description 字段
正文（Markdown）： 使用技能的指令和指南

打包资源（可选）

Scripts（`scripts/`）

用于需要确定性可靠性或重复编写的可执行代码。

何时包含：
– 相同代码被重复编写，或需要确定性可靠性
– 示例：scripts/rotate_pdf.py 用于 PDF 旋转任务

优势：
– Token 高效
– 确定性
– 可能无需加载到上下文即可执行

注意： 脚本可能仍需要读取 AI Agent 以进行修补或环境特定调整

References（`references/`）

旨在按需加载到上下文以指导 AI Agent 过程和思考的文档和参考资料。

何时包含：
– AI Agent 工作时应参考的文档
– 示例：references/finance.md 用于财务架构，references/api_docs.md 用于 API 规范

用例：
– 数据库架构
– API 文档
– 领域知识
– 公司政策
– 详细工作流程指南

优势：
– 保持 SKILL.md 精简
– 仅在 AI Agent 确定需要时加载
– 最佳实践：如果文件较大（>10k 字），在 SKILL.md 中包含 grep 搜索模式

避免重复： 信息应居住在 SKILL.md 或 references 文件之一，而非两者。优先在 SKILL.md 中保留核心程序指令和工作流程指南；将详细参考资料、架构和示例移至 references 文件。这使 SKILL.md 保持精简，同时使信息无需占用上下文窗口即可被发现。

Assets（`assets/`）

不旨在加载到上下文，而是在 AI Agent 生成的输出中使用的文件。

何时包含：
– 技能需要在最终输出中使用的文件
– 示例：assets/logo.png 用于品牌资产，assets/template.html 用于 HTML 模板

用例：
– 模板
– 图像
– 图标
– 样板代码
– 样本文档

优势：
– 将输出资源与文档分离
– 允许 AI Agent 使用文件而无需加载到上下文

SKILL.md 编写规范

前置元数据（YAML Frontmatter）

必需字段：
– name: Skill 名称
– description: Skill 描述

描述编写指南：
– 这是触发 Skill 的主要机制
– 帮助 AI Agent 理解何时使用该 Skill
– 包含 Skill 做什么以及何时使用的具体触发条件/上下文
– 不要将所有”何时使用”信息放在正文中（正文仅在触发后加载）
– 使用清晰、全面的描述

示例描述：

name: docx-processor
description: |
  使用 docx-js 进行文档创建、编辑和分析，支持跟踪更改、注释、格式保留和文本提取。
  当 AI Agent 需要处理专业文档（.docx 文件）时使用：创建新文档、修改或编辑内容、处理跟踪更改、添加注释或任何其他文档任务。

不要在 YAML 前置元数据中包含其他字段。

正文（Markdown）

编写使用技能及其打包资源的指令。

编写指南：
– 始终使用祈使/不定式形式
– 保持简洁
– 使用清晰的步骤和示例
– 说明何时使用打包资源

进阶设计模式

Skills 使用三级加载系统来高效管理上下文：

元数据（name + description） – 始终在上下文中（约 100 字）
SKILL.md 正文 – Skill 触发时加载（< 5k 字）
打包资源 – AI Agent 按需加载（无限，因为脚本可以无需读取到上下文窗口即可执行）

渐进式披露模式

保持 SKILL.md 正文在 500 行以内，以最小化上下文膨胀。当接近此限制时，将内容拆分到单独的文件。将内容拆分到其他文件时，非常重要的是从 SKILL.md 引用它们并清晰说明何时读取它们，以确保 Skill 的读者知道它们存在以及何时使用它们。

关键原则： 当 Skill 支持多种变体、框架或选项时，仅保留核心工作流程和选择指导在 SKILL.md 中。将特定细节（模式、示例、配置）移至单独的 reference 文件。

模式 1：带 references 的高层指南

# PDF 处理

## 快速开始

使用 pdfplumber 提取文本：
```python
import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    for page in pdf.pages:
        print(page.extract_text())

高级功能

表单填充: 参见 FORMS.md 了解完整指南
API 参考: 参见 REFERENCE.md 了解所有方法
示例: 参见 EXAMPLES.md 了解常见模式


AI Agent 仅在需要时加载 FORMS.md、REFERENCE.md 或 EXAMPLES.md。

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

对于支持多个领域的 Skill，按领域组织内容以避免加载不相关的上下文：

bigquery-skill/
├── SKILL.md（概述和导航）
└── reference/
├── finance.md（收入、计费指标）
├── sales.md（商机、管道）
├── product.md（API 使用、功能）
└── marketing.md（活动、归因）


当用户询问销售指标时，AI Agent 仅读取 sales.md。

同样，对于支持多个框架或变体的 Skill，按变体组织：

cloud-deploy/
├── SKILL.md（工作流程 + 提供商选择）
└── references/
├── aws.md（AWS 部署模式）
├── gcp.md（GCP 部署模式）
└── azure.md（Azure 部署模式）


当用户选择 AWS 时，AI Agent 仅读取 aws.md。

### 模式 3：条件细节

显示基本内容，链接到高级内容：

```markdown
# DOCX 处理

## 创建文档

使用 docx-js 创建新文档。参见 [DOCX-JS.md](DOCX-JS.md)。

## 编辑文档

对于简单编辑，直接修改 XML。

**对于跟踪更改**: 参见 [REDLINING.md](REDLINING.md)
**对于 OOXML 细节**: 参见 [OOXML.md](OOXML.md)

AI Agent 仅在用户需要这些功能时读取 REDLINING.md 或 OOXML.md。

重要指南：
– 避免深层嵌套引用 – references 文件应与 SKILL.md 保持一层深度。所有 reference 文件都应从 SKILL.md 直接链接。
– 结构更长的 reference 文件 – 对于超过 100 行的文件，在顶部包含目录，以便 AI Agent 在预览时可以看到完整范围。

完整示例

示例 Skill：Markdown 转 HTML

创建一个将 Markdown 转换为 HTML 的 Skill。

1. 初始化 Skill

cd ~/.npm-global/lib/node_modules/openclaw/skills
python3 -m openclaw.skills.init_skill markdown-to-html

这将创建以下目录结构：

markdown-to-html/
├── SKILL.md
├── scripts/
│   └── convert.py
└── references/
    └── examples.md

2. 编写 SKILL.md

---
name: markdown-to-html
description: 将 Markdown 转换为 HTML 的工具，支持多种扩展和自定义配置。
  当需要将 Markdown 文本或文件转换为 HTML 时使用，包括：
  - 网页内容生成
  - 文档预览
  - 静态站点生成
  - Markdown 转 PDF（通过 HTML 中间格式）
---

# Markdown 转 HTML

## 快速开始

使用 `scripts/convert.py` 转换 Markdown 文件：

```bash
python3 scripts/convert.py input.md -o output.html

基本转换

转换纯 Markdown：

python3 scripts/convert.py input.md -o output.html

启用扩展

启用额外功能：

python3 scripts/convert.py input.md -o output.html --extensions extra,tables

常用扩展：
– extra – 表格、自动链接、定义列表
– tables – 表格支持
– toc – 目录生成
– fenced_code – 代码块

高级用法

自定义 CSS

python3 scripts/convert.py input.md -o output.html --css custom.css

生成目录

python3 scripts/convert.py input.md -o output.html --toc

仅转换特定部分

python3 scripts/convert.py input.md -o output.html --start-section "## Features"

参考资源

完整示例: 参见 examples.md 了解更多用法
API 文档: 参见 API.md 了解所有命令行选项


#### 3. 创建 Scripts

`scripts/convert.py`:

```python
#!/usr/bin/env python3
"""
Markdown 转 HTML 转换器
支持多种 Markdown 扩展和自定义配置
"""
import argparse
import sys
from pathlib import Path

try:
    import markdown
except ImportError:
    print("错误: 需要安装 markdown 库")
    print("运行: pip install markdown")
    sys.exit(1)


def convert_markdown(input_path: str, output_path: str, extensions: list = None, css: str = None, toc: bool = False):
    """将 Markdown 文件转换为 HTML"""
    with open(input_path, 'r', encoding='utf-8') as f:
        md_content = f.read()

    # 默认扩展
    default_extensions = ['extra', 'tables']

    # 合并扩展
    if extensions:
        all_extensions = default_extensions + extensions
    else:
        all_extensions = default_extensions

    # 转换为 HTML
    html_content = markdown.markdown(
        md_content,
        extensions=all_extensions,
        extension_configs={
            'markdown.extensions.codehilite': {
                'css_class': 'highlight',
                'linenums': True
            }
        }
    )

    # 添加 CSS
    if css:
        with open(css, 'r', encoding='utf-8') as f:
            css_content = f.read()
        html_content = f"""<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Markdown 转 HTML</title>
    <style>{css_content}</style>
</head>
<body>
    {html_content}
</body>
</html>"""
    else:
        html_content = f"""<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Markdown 转 HTML</title>
</head>
<body>
    {html_content}
</body>
</html>"""

    # 写入输出文件
    with open(output_path, 'w', encoding='utf-8') as f:
        f.write(html_content)

    print(f"✓ 成功转换: {input_path} -> {output_path}")


def main():
    parser = argparse.ArgumentParser(description='Markdown 转 HTML 转换器')
    parser.add_argument('input', help='输入 Markdown 文件')
    parser.add_argument('-o', '--output', help='输出 HTML 文件（默认：input.html）')
    parser.add_argument('-e', '--extensions', nargs='+', help='Markdown 扩展列表')
    parser.add_argument('--css', help='自定义 CSS 文件')
    parser.add_argument('--toc', action='store_true', help='生成目录')

    args = parser.parse_args()

    input_path = Path(args.input)
    if not input_path.exists():
        print(f"错误: 文件不存在: {input_path}")
        sys.exit(1)

    output_path = args.output or input_path.with_suffix('.html')
    if args.toc:
        output_path = Path(str(output_path).replace('.html', '-toc.html'))

    convert_markdown(
        input_path=str(input_path),
        output_path=str(output_path),
        extensions=args.extensions,
        css=args.css,
        toc=args.toc
    )


if __name__ == '__main__':
    main()

4. 创建 References

references/examples.md:

# Markdown 转 HTML 使用示例

## 示例 1: 博客文章

输入 Markdown:

```markdown
# 我的博客文章

这是第一段文字。

## 特性

- 功能 1
- 功能 2

## 代码示例

```python
print("Hello, World!")


命令:

```bash
python3 scripts/convert.py blog-post.md -o blog-post.html --toc

示例 2: 技术文档

启用代码高亮:

python3 scripts/convert.py docs.md -o docs.html --extensions codehilite,fenced_code

示例 3: 带样式的文档

自定义 CSS:

python3 scripts/convert.py report.md -o report.html --css style.css

style.css:

body {
    font-family: Arial, sans-serif;
    line-height: 1.6;
    max-width: 800px;
    margin: 0 auto;
    padding: 20px;
}

h1, h2, h3 {
    color: #2c3e50;
}

code {
    background-color: #f4f4f4;
    padding: 2px 6px;
    border-radius: 3px;
}

示例 4: 多页文档

# 转换多个文件
for file in chapter*.md; do
    python3 scripts/convert.py "$file" -o "${file%.md}.html"
done


`references/api.md`:

```markdown
# API 文档

## 命令行选项

### 基本用法

```bash
python3 scripts/convert.py <input.md> [options]

选项

选项	说明	默认值
`-o, --output`	输出 HTML 文件路径	input.html
`-e, --extensions`	Markdown 扩展列表	extra, tables
`--css`	自定义 CSS 文件	无
`--toc`	生成目录	false

支持的扩展

extra – 表格、自动链接、定义列表
tables – 表格支持
toc – 目录生成
fenced_code – 代码块
codehilite – 代码高亮
nl2br – 换行转
sane_lists – 智能列表

输出格式

生成的 HTML 包含：
– HTML5 文档结构
– UTF-8 编码
– 代码高亮样式
– 响应式设计（可选）


#### 5. 测试 Skill

```bash
# 测试转换
python3 scripts/convert.py test.md -o test.html

# 查看结果
cat test.html

6. 打包 Skill

python3 scripts/package_skill.py markdown-to-html

这将创建 markdown-to-html.skill 文件。

发布到 ClawHub

1. 安装 ClawHub CLI

npm i -g clawhub

2. 登录 ClawHub

clawhub login
clawhub whoami

3. 准备 Skill

确保 Skill 已完成并测试：

cd ~/.npm-global/lib/node_modules/openclaw/skills/markdown-to-html
python3 scripts/package_skill.py .

4. 发布 Skill

clawhub publish ./markdown-to-html \
  --slug markdown-to-html \
  --name "Markdown 转 HTML" \
  --version 1.0.0 \
  --changelog "初始版本：支持基本转换和多种扩展"

参数说明：
– --slug: Skill 的唯一标识符（小写，连字符分隔）
– --name: 显示名称
– --version: 版本号（语义化版本）
– --changelog: 变更日志

5. 验证发布

clawhub search "markdown to html"

6. 更新 Skill

如果需要更新已发布的 Skill：

clawhub update markdown-to-html --version 1.1.0 --changelog "添加更多扩展支持"

最佳实践总结

1. 保持简洁

SKILL.md 保持 500 行以内
优先示例，避免冗长解释
每个信息都要问”AI Agent 真需要吗？”

2. 合理组织

高层指南在 SKILL.md
详细信息在 references/
脚本在 scripts/
资产在 assets/

3. 渐进式披露

元数据始终在上下文中
SKILL.md 正文仅在触发时加载
References 按需加载

4. 清晰触发

name: 简洁明了
description: 包含做什么和何时使用

5. 可测试性

提供可运行的示例
包含测试脚本
验证所有功能

常见错误

错误 1: 上下文膨胀

问题： SKILL.md 太长，占用过多上下文。

解决：
– 拆分到 references/
– 删除不必要的解释
– 优先示例

错误 2: 触发不明确

问题： AI Agent 不知道何时使用 Skill。

解决：
– 在 description 中明确说明
– 列出具体触发条件
– 提供使用示例

错误 3: 资源重复

问题： 信息同时在 SKILL.md 和 references 中。

解决：
– SKILL.md 保持核心内容
– references 存放详细内容
– 避免重复

错误 4: 缺少测试

问题： Skill 功能不完整或有问题。

解决：
– 提供可运行的示例
– 包含测试脚本
– 实际运行测试

下一步

查看更多示例：https://clawhub.ai
学习更多设计模式：https://docs.openclaw.ai
参与社区讨论：https://discord.com/invite/clawd

最后更新： 2026-04-23
作者： OpenClaw 社区
许可证： MIT

文章版权归作者所有，未经允许请勿转载。

THE END

技术教程
# OpenClaw # AI # 自动化 # DevOps # Multi-Agent # Feishu

OpenClaw Skills 编写完整教程 | 从入门到精通