OpenClaw Skill 扩展机制解析与自定义技能开发实践

摘要

本文分析 OpenClaw 框架中 Skill 扩展机制的设计原理与实现方式，通过开发一个"每日技术日报"自定义技能的完整过程，展示从 SKILL.md 编写、目录结构组织、安装调试到发布的全流程。Skill 采用 Markdown 格式定义，无需代码编译，通过语义匹配触发，渐进式加载管理上下文。

一、问题背景

在使用 OpenClaw 进行日常工作自动化的过程中，我遇到了一个需求：每天早上自动搜集技术领域的热点新闻，整理成中文摘要日报，推送到 Slack 工作频道。

OpenClaw 本身提供了天气查询、网页摘要等内置能力，但没有直接满足这个需求的功能。框架提供了一套名为 Skill 的能力扩展机制，允许用户通过编写 Markdown 格式的定义文件来为 AI Agent 添加新能力。

本文记录我从零开发这个 Skill 的完整过程，包括对 Skill 机制的理解、SKILL.md 的编写规范、实际代码以及调试经验。

二、Skill 机制概述

2.1 基本概念

Skill 是 OpenClaw 框架中 AI Agent 的能力扩展单元。与传统软件插件不同，Skill 不是可执行代码，而是一份结构化的 Markdown 文档。AI Agent 读取文档中的指令后，自行调用底层工具完成任务。

这种设计的逻辑是：既然 AI Agent 已经具备理解自然语言、调用工具的能力，那么给它一份写清楚"做什么、怎么做"的操作文档，就等于给了它一个新技能。

2.2 执行流程

扫描阶段：Agent 启动后，扫描所有已安装 Skill 的 name 和 description 字段
匹配阶段：收到用户请求时，Agent 根据 description 语义判断是否有 Skill 适配
加载阶段：匹配成功后，读取 SKILL.md 的正文内容
执行阶段：按正文中的指令步骤执行任务，按需读取附属资源

2.3 上下文管理

Skill 采用三层渐进加载模型：

层级	内容	加载时机	规模
元数据层	name + description	常驻内存	~100 词
指令层	SKILL.md 正文	触发时加载	<500 行
资源层	scripts/references/assets	按需加载	不限

这种设计解决的核心问题是上下文窗口的容量管理——Agent 的上下文空间有限，不可能同时加载所有 Skill 的完整内容。

三、Skill 目录结构

标准的 Skill 目录结构：

skill-name/
├── SKILL.md          # 必需：技能定义文件
├── scripts/          # 可选：可执行脚本（Bash/Python 等）
├── references/       # 可选：参考文档
└── assets/           # 可选：输出用资源

SKILL.md 是仅有的必需文件，其余目录按需创建。

各目录的设计意图：

scripts/：存放需要确定性执行的脚本。适用于逻辑固定、每次执行结果应一致的操作。脚本可以被 Agent 直接执行而无需加载到上下文中。
references/：供 Agent 按需查阅的参考文档。典型场景包括 API 文档、数据源列表、领域知识说明。只在 Agent 判断需要时才读取。
assets/：用于输出的资源文件，如报告模板、图标等。Agent 在输出中直接引用这些文件，而不读取其内容到上下文。

设计原则：SKILL.md 保持精简，将大段参考内容拆分到 references/ 目录，通过引用方式关联。

四、SKILL.md 编写规范

4.1 YAML Frontmatter

---
name: daily-tech-digest
description: |
  每日技术日报生成与推送。自动搜索当天技术热点新闻，
  生成中文摘要日报，推送到 Slack 频道。
  触发条件：用户要求生成技术日报、每日新闻摘要、技术热点汇总，
  或定时任务触发每日日报生成。
  关键词：日报、技术新闻、热点、每日摘要、tech digest。
---

name 字段：

格式要求：小写字母 + 数字 + 连字符
长度限制：64 字符以内
命名风格：推荐使用动词前导的描述性名称

description 字段：

这是 Skill 的触发机制，Agent 通过读取此字段判断是否激活 Skill
需要同时描述"做什么"和"什么时候用"
建议覆盖用户可能使用的多种表述方式
注意：触发条件必须写在 description 中，不要写在正文里（正文只在触发后才被读取）

YAML 语法注意事项：

description 中包含冒号时需要引号或多行语法
推荐使用 | 多行块标量语法

4.2 Markdown 正文

正文是写给 Agent 的操作指令，建议使用祈使句风格。

推荐包含以下部分：

使用场景（适用 / 不适用）
执行流程（具体步骤）
输出格式规范
注意事项和边界条件

五、实战开发：每日技术日报

5.1 需求定义

每天早上自动搜索技术热点，生成中文摘要日报，推送到 Slack 频道，同时本地归档。

5.2 目录规划

daily-tech-digest/
├── SKILL.md
└── scripts/
    └── generate_digest.sh

5.3 SKILL.md 完整内容

---
name: daily-tech-digest
description: |
  每日技术日报生成与推送。自动搜索当天技术热点新闻，生成中文摘要日报，
  推送到 Slack 频道。
  触发条件：用户要求生成技术日报、每日新闻摘要、技术热点汇总，
  或定时任务触发每日日报生成。
  关键词：日报、技术新闻、热点、每日摘要、tech digest。
---

# 每日技术日报

自动搜索技术热点，生成中文日报并推送到 Slack。

## 使用场景

✅ **适用：**
- 用户说"生成今天的技术日报"
- 定时任务触发每日日报
- 用户要求搜索技术热点并汇总

❌ **不适用：**
- 查询特定技术问题的深度分析
- 非技术类新闻汇总

## 执行流程

### 1. 搜索技术热点

使用 web_search 工具搜索以下关键词（每个取前 5 条）：

- "AI 人工智能 新闻 today"
- "云计算 cloud computing news"
- "开源项目 trending"
- "软件开发 技术趋势"

### 2. 筛选和去重

从搜索结果中筛选：
- 过滤掉超过 48 小时的旧新闻
- 去除重复内容（相同 URL 或标题相似度 > 80%）
- 保留 8-12 条高质量条目

### 3. 生成日报

按以下格式生成中文日报：

```markdown
 技术日报 | YYYY-MM-DD

##  今日热点

### 1. [标题]
摘要（2-3 句话概括核心内容）
 来源：[链接]

### 2. [标题]
...

---
 由 OpenClaw 自动生成

4. 推送到 Slack

使用 message 工具发送到指定 Slack 频道：

默认频道：当前对话所在频道
如果用户指定了频道，发送到指定频道
消息格式使用 Slack 兼容的 Markdown

5. 保存归档

将日报保存到 ~/.openclaw/workspace/digests/YYYY-MM-DD.md 归档。

脚本

如需批量抓取，可执行辅助脚本：

bash scripts/generate_digest.sh

定时任务

建议通过 OpenClaw 的 cron 功能设置每日定时执行：

时间：每天早上 9:00（UTC+8）
任务：生成技术日报并推送到 Slack

注意事项

搜索结果依赖 web_search 工具的可用性
单次生成的日报条目控制在 8-12 条，避免信息过载
如搜索结果不足，如实告知，不要编造内容


### 5.4 辅助脚本

`scripts/generate_digest.sh` 用于在 web_search 不可用时提供 fallback 数据源：

```bash
#!/usr/bin/env bash
# 辅助脚本：从 AWS 官方博客获取最新条目作为日报素材

set -euo pipefail

DATE=$(date +%Y-%m-%d)
OUTPUT_DIR="${HOME}/.openclaw/workspace/digests"
OUTPUT_FILE="${OUTPUT_DIR}/${DATE}.md"

mkdir -p "$OUTPUT_DIR"

echo " 技术日报 | ${DATE}" > "$OUTPUT_FILE"
echo "" >> "$OUTPUT_FILE"
echo "##  今日技术热点" >> "$OUTPUT_FILE"
echo "" >> "$OUTPUT_FILE"

# 从 AWS 官方博客 RSS 拉取最新条目
FEED_URL="https://aws.amazon.com/blogs/china/feed/"
TITLES=$(curl -s "$FEED_URL" | grep -oP '(?<=<title>).*?(?=</title>)' | head -12 | tail -10)

INDEX=1
while IFS= read -r title; do
  if [ -n "$title" ]; then
    echo "### ${INDEX}. ${title}" >> "$OUTPUT_FILE"
    echo "" >> "$OUTPUT_FILE"
    INDEX=$((INDEX + 1))
  fi
done <<< "$TITLES"

echo "---" >> "$OUTPUT_FILE"
echo " 由 OpenClaw 自动生成" >> "$OUTPUT_FILE"

echo "日报已保存到: ${OUTPUT_FILE}"

脚本从亚马逊云科技官方博客的 RSS 源获取内容，作为 Agent 主搜索流程的补充数据源。

六、安装与测试

6.1 安装

将 Skill 目录放置到 OpenClaw 的标准路径下：

mkdir -p ~/.openclaw/workspace/skills/daily-tech-digest/scripts

cp SKILL.md ~/.openclaw/workspace/skills/daily-tech-digest/
cp scripts/generate_digest.sh ~/.openclaw/workspace/skills/daily-tech-digest/scripts/
chmod +x ~/.openclaw/workspace/skills/daily-tech-digest/scripts/generate_digest.sh

OpenClaw 会在下次会话时自动扫描并加载，无需重启服务。

6.2 功能验证

在 Slack 中向 Agent 发送：

生成今天的技术日报

预期行为：

Agent 识别请求匹配 daily-tech-digest Skill
读取 SKILL.md 指令
执行 web_search 搜索热点
按模板生成日报
推送到 Slack 并本地归档

也可以尝试其他表述以验证触发覆盖面："帮我整理今天的技术热点"、"来一份技术日报"。

七、调试经验

7.1 确认加载状态

询问 Agent："你有哪些 skills？"

如果 Skill 未出现在列表中，检查：

文件路径是否正确
YAML frontmatter 的 --- 分隔符是否完整
name 和 description 字段是否存在

7.2 触发匹配问题

Skill 已加载但未被触发，通常是 description 覆盖不足。扩充关键词和场景描述即可。

7.3 YAML 解析错误

常见问题——description 中的特殊字符：

# ❌ 冒号导致解析失败
description: 功能：生成日报

# ✅ 使用引号
description: "功能：生成日报"

# ✅ 使用多行块标量
description: |
  功能：生成日报

7.4 脚本执行异常

排查清单：

执行权限：chmod +x
依赖工具：curl 等是否已安装
网络连通：确认可以访问外部服务

7.5 description 优化建议

description 的质量直接决定 Skill 的触发准确率。我的做法是先写一个基本版本上线，在实际使用中观察哪些表述没有命中，迭代补充。

一个好的 description 应该覆盖：

功能描述（做什么）
触发场景（什么时候用）
关键词变体（用户可能的不同说法）

description: |
  每日技术日报生成与推送...
  关键词：日报、技术新闻、热点、每日摘要、tech digest、
  今日资讯、新闻早报、技术快讯。

八、进阶话题

8.1 渐进式内容组织

当 Skill 功能复杂时，利用 references/ 目录按领域拆分：

daily-tech-digest/
├── SKILL.md
├── scripts/
│   └── generate_digest.sh
└── references/
    ├── ai-sources.md
    ├── cloud-sources.md
    └── frontend-sources.md

SKILL.md 中按需引用：

根据用户关注的领域，读取对应参考文件：
- AI：参见 [references/ai-sources.md](references/ai-sources.md)
- 云计算：参见 [references/cloud-sources.md](references/cloud-sources.md)

Agent 只加载实际需要的文件，避免上下文浪费。

8.2 配合定时机制

除了 cron 定时任务，OpenClaw 的 heartbeat 机制也可以触发 Skill——在 HEARTBEAT.md 中添加检查项，Agent 在心跳周期中主动执行。

8.3 发布到 ClawHub

ClawHub 是 OpenClaw 的技能共享平台。发布流程：

确保 frontmatter 完整
使用打包工具生成 .skill 文件
提交到 ClawHub

九、总结

OpenClaw 的 Skill 机制提供了一种基于 Markdown 的 AI Agent 能力扩展方案。其核心设计特点：

Markdown 协议：以文档形式定义能力，降低开发门槛
语义触发：通过 description 字段实现基于语义的匹配
三层渐进加载：元数据常驻、正文按需、资源延迟加载，保护上下文窗口
约定式目录结构：scripts/references/assets 各司其职

我在亚马逊云科技的实际工作中使用这套机制自动化了多个重复性流程。从实践来看，Skill 的开发成本较低（本质是写一份 Markdown 文档），而 Agent 的执行效果主要取决于 SKILL.md 指令的清晰度和 description 的覆盖面。

如果你对 AI Agent 的能力扩展机制有兴趣，建议从一个小 Skill 开始实践，逐步积累经验。

欢迎分享你的 Skill 开发经验

posted @ 2026-03-12 18:31 亚马逊云开发者阅读(19) 评论(0) 收藏举报

刷新页面返回顶部

亚马逊云开发者

进入亚马逊云科技开发者网站，请锁定 https://dev.amazoncloud.cn 帮助开发者学习成长、交流，链接全球资源，助力开发者成功。

OpenClaw Skill 扩展机制解析与自定义技能开发实践

OpenClaw Skill 扩展机制解析与自定义技能开发实践

摘要

一、问题背景

二、Skill 机制概述

2.1 基本概念

2.2 执行流程

2.3 上下文管理

三、Skill 目录结构

四、SKILL.md 编写规范

4.1 YAML Frontmatter

4.2 Markdown 正文

五、实战开发：每日技术日报

5.1 需求定义

5.2 目录规划

5.3 SKILL.md 完整内容

4. 推送到 Slack

5. 保存归档

脚本

定时任务

注意事项

六、安装与测试

6.1 安装

6.2 功能验证

七、调试经验

7.1 确认加载状态

7.2 触发匹配问题

7.3 YAML 解析错误

7.4 脚本执行异常

7.5 description 优化建议

八、进阶话题

8.1 渐进式内容组织

8.2 配合定时机制

8.3 发布到 ClawHub

九、总结

公告