OpenClaw Skill开发实战：Markdown协议全解析

2026-06-11阅读 0热度 0

人工智能

背景：从“能否实现”到“如何落地”

在探索OpenClaw自动化方案的过程中，我遇到一个典型场景：每天早上需要自动抓取多个技术社区的当日热点信息，整理成一份中文摘要日报，最后推送到Slack频道。 OpenClaw自身并未预置这项功能。查阅官方文档后，我发现它提供了一套名为 **Skill** 的能力扩展框架。这套机制的设计思路值得关注——无需编写代码编译、无需发布到插件市场、甚至无需重启服务。只需一个`SKILL.md`文件，即可完成扩展。本文将从协议设计的角度，深入解析Skill的底层逻辑，并通过一个完整的实战案例（每日技术日报）演示完整流程。如果你对AI Agent的扩展方式感兴趣，或者想理解“一个Markdown文件如何成为插件”，这篇文章值得一读。 --- ## 一、Skill 的协议设计 ### 1.1 什么是 Skill 简单来说，Skill是OpenClaw为AI Agent提供的“能力增强包”。形式上，它是一个包含`SKILL.md`文件的目录。功能上，它是一份面向Agent的**结构化操作指南**。与传统代码插件对比，差异如下： | 维度 | 传统插件 | OpenClaw Skill | | :--- | :--- | :--- | | 格式 | 代码文件（JS/Python等） | Markdown 文档 | | 安装方式 | 编译、安装依赖 | 复制文件到指定目录 | | 加载机制 | 启动时全量加载 | 按需分层加载 | | 执行主体 | 运行时环境/解释器 | AI Agent | | 更新方式 | 重新编译、部署 | 修改文件即时生效 | 最核心的区别在于：传统插件告诉计算机“具体执行步骤”，而Skill则告诉AI Agent“需要达成的目标”。Agent收到指令后，自主调用底层工具（如搜索、消息发送）完成任务。 ### 1.2 三层加载模型：高效管理Agent的“工作记忆” Skill采用分层加载机制，类似于洋葱的逐层结构： **第一层：元数据（常驻内存）** ```yaml name: daily-tech-digest description: "每日技术日报生成与推送..." ``` 元数据约100个词，始终位于Agent的“短期记忆”（上下文窗口）中。Agent通过快速扫描所有Skill的元数据，判断当前用户需求对应哪个Skill。 **第二层：SKILL.md 正文（触发时加载）** 只有当Agent确认需要某个Skill时，才会加载对应的`SKILL.md`文件全文。建议正文控制在500行以内。这种设计有效避免了将所有Skill的冗余信息一次性注入Agent，防止上下文窗口被撑满。 **第三层：附属资源（按需加载）** `scripts/`、`references/`、`assets/`等目录中的文件，Agent在执行任务过程中按需读取。例如，它可能需要查阅API文档，才会读取`references/`下的文件。该设计的核心目的是**保护上下文窗口**——Agent的“工作记忆”是稀缺资源，必须精打细算。 ### 1.3 目录结构规范：合理规划项目布局一个标准的Skill项目目录结构如下： ``` skill-name/ ├── SKILL.md # 必需：技能定义文件 ├── scripts/ # 可选：确定性执行脚本（Bash/Python等） ├── references/ # 可选：参考文档（Agent按需读取） └── assets/ # 可选：输出资源（模板、图标等） ``` 各目录职责清晰： - **`scripts/`**：存放需要100%确定性执行的脚本，如数据抓取、格式转换等逻辑固定的操作。脚本可直接由Agent调用，无需加载到Agent上下文中。 - **`references/`**：存放参考文档，如API文档、配置文件详细说明。Agent仅在需要时读取，避免一次性占用上下文。若文件超过100行，建议在开头添加目录，便于Agent快速定位。 - **`assets/`**：存放输出资源，如报告模板、品牌图标。Agent不读取这些文件内容，仅在最终输出中引用。特别注意：**不要在Skill目录下放置`README.md`、`CHANGELOG.md`等面向人类开发者的文件**。记住，你的读者是AI Agent，任何多余文件只会增加其处理负担。 --- ## 二、SKILL.md 写法详解：如何让Agent精准执行 ### 2.1 Frontmatter：Agent的“第一印象” `SKILL.md`以YAML格式的Frontmatter开头，需包含两个必填字段： ```yaml --- name: daily-tech-digest description: | 每日技术日报生成与推送。自动搜索当天技术热点新闻，生成中文摘要日报，推送到 Slack 频道。触发条件：用户要求生成技术日报、每日新闻摘要、技术热点汇总，或定时任务触发每日日报生成。关键词：日报、技术新闻、热点、每日摘要、tech digest。 --- ``` **`name`** 命名规范：使用小写字母、数字和连字符，长度不超过64个字符。推荐以动词开头，如`generate-report`、`daily-tech-digest`。 **`description`** 是Agent决定是否调用该Skill的核心依据。必须同时明确说明两件事： 1. **功能**：该Skill完成什么任务。 2. **触发场景**：用户什么样的请求会触发该Skill。常见误区：将“触发场景”写在正文中。这毫无意义，因为正文在触发后才加载。因此，所有触发的“钩子”必须全部放在`description`中。尽量覆盖用户可能使用的各种表述。 ### 2.2 正文：面向Agent的操作手册正文为标准的Markdown格式，是写给Agent的操作指令。建议采用祈使句风格，直接明确。推荐结构： ```markdown # Skill 名称简要说明。 ## 使用场景 ✅ 适用的场景 ❌ 不适用的场景 ## 执行流程 ### 步骤 1 ... ### 步骤 2 ... ## 注意事项 ``` 正文目标纯粹：Agent读完该文档后，即可独立完成任务。无需背景介绍，无需解释原因，直接提供“如何执行”的指令。 --- ## 三、实战：每日技术日报 Skill ### 需求每天早上自动搜索技术热点，生成一份中文日报，并推送到Slack频道。 ### 目录结构 ``` daily-tech-digest/ ├── SKILL.md └── scripts/ └── generate_digest.sh ``` ### 完整的 SKILL.md ```yaml --- 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. 生成日报按以下格式生成中文日报： ``` ? 技术日报 | 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 条，避免信息过载 - 如搜索结果不足，如实告知，不要编造内容 ``` ### 辅助脚本 `scripts/generate_digest.sh` 这个脚本扮演“辅助”角色，帮助Agent完成机械性工作： ```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 '(?<=).*?(?=)' | 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}" ``` --- ## 四、安装和测试：将Skill“喂”给Agent ### 安装安装过程简单，只需将文件复制到指定目录： ```bash 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在下次会话中会自动加载，无需重启。 ### 验证最直接的验证方式，是向Agent发出指令： ``` 生成今天的技术日报 ``` 然后观察其是否： 1. 准确识别出`daily-tech-digest`这个Skill。 2. 严格按照`SKILL.md`中的流程进行搜索、筛选、内容生成。 3. 最终生成的日报格式正确，并成功推送到Slack。 --- ## 五、调试指南：常见问题与解决方案开发过程中难免遇到问题，以下是对常见情况的排查思路： ### 5.1 确认加载状态直接询问Agent：“你现在有哪些 skills？” 若你的Skill不在列表中，排查方向： - **文件路径**：确认文件是否位于 `~/.openclaw/workspace/skills/daily-tech-digest/SKILL.md` 路径下。 - **Frontmatter**：检查开头的`---`分隔符是否完整。 - **字段语法**：确保`name`和`description`字段存在且YAML语法正确。 ### 5.2 触发失败若Skill已加载，但用户请求未触发该Skill，原因通常是`description`中的关键词未覆盖用户的表述。解决办法：扩充`description`中的关键词和场景描述，尽可能覆盖用户可能使用的各种说法。 ### 5.3 YAML语法问题 `description`中包含冒号、引号等特殊字符时，容易导致YAML解析失败。 ```yaml # ❌ 冒号会导致解析失败 description: 功能：生成日报 # ✅ 使用引号包裹 description: "功能：生成日报" # ✅ 使用多行语法 description: | 功能：生成日报触发：用户要求日报 ``` ### 5.4 脚本问题 - **执行权限**：检查 `chmod +x scripts/generate_digest.sh` 是否已执行。 - **依赖命令**：确认脚本中使用的`curl`、`grep`等工具已安装。 - **网络连通性**：`web_search`和脚本均需联网，检查网络连接。 --- ## 六、进阶：渐进式内容组织当Skill功能趋于复杂，`SKILL.md`正文膨胀至数百行时，应利用第三层加载机制——将详细内容拆分至`references/`目录。 ### 示例：按领域拆分数据源 ``` daily-tech-digest/ ├── SKILL.md ├── scripts/ │ └── generate_digest.sh └── references/ ├── ai-sources.md # AI 领域的搜索策略和数据源 ├── cloud-sources.md # 云计算领域 └── frontend-sources.md # 前端领域 ``` 在`SKILL.md`中仅需引用： ```markdown ## 数据源根据用户关注的领域，读取对应的参考文件： - AI 方向：参见 [references/ai-sources.md](references/ai-sources.md) - 云计算方向：参见 [references/cloud-sources.md](references/cloud-sources.md) - 前端方向：参见 [references/frontend-sources.md](references/frontend-sources.md) ``` 这样，Agent仅加载当前所需的文件，避免一次性读取三个文件，智能且高效。 ### 模板化输出若日报需要固定排版，可将模板放至`assets/`目录： ``` daily-tech-digest/ └── assets/ └── digest_template.md ``` Agent直接使用模板填充内容，确保每次输出格式一致。 ### 配合 Heartbeat 机制 OpenClaw具备Heartbeat机制——Agent会定期被唤醒执行检查任务。在`HEARTBEAT.md`中添加日报提醒： ```markdown - [ ] 工作日早上 9:00 左右，执行每日技术日报 Skill ``` 这样无需配置cron，Agent在心跳周期中也会触发日报生成。 --- ## 七、发布到 ClawHub ClawHub是OpenClaw的技能共享平台。若你的Skill经过验证，可考虑发布，让更多人受益： 1. 确保`SKILL.md`的Frontmatter完整规范。 2. 使用打包工具生成`.skill`文件。 3. 提交至ClawHub。其他用户即可直接安装使用。 --- ## 总结 OpenClaw的Skill机制，本质上是一种**面向AI Agent的声明式扩展协议**。它用Markdown替代了代码，用自然语言指令替代了API调用，将能力扩展的门槛降低至“会写文档”的级别。以下几个设计亮点值得关注： - **三层渐进加载**：精打细算地使用Agent的上下文窗口。 - **Description驱动触发**：Skill的匹配完全语义化，Agent能自主判断何时使用哪个Skill。 - **目录结构约定**：在灵活性与规范性之间取得了良好平衡。在实际工作中，我已使用这套机制自动化了多个重复性流程，效果符合预期。如果你也在探索AI Agent的能力扩展方案，OpenClaw是一个值得研究的参考对象。

OpenClaw Skill开发实战：Markdown协议全解析

背景：从“能否实现”到“如何落地”

相关阅读

最新教程

最新资讯