手写第一个技能：hello-world 从建目录到跑通，每一步都拆开看

Q: 1. 建目录

mkdir -p ~/.openclaw/workspace/skills/hello-world 注意：目录名最好和 frontmatter 里的 name 一致。官方允许分组布局，比如： mkdir -p ~/.openclaw/workspace/skills/personal/hello-world 技能名仍由 SKILL.md 的 name 决定，目录路径不影响最终调用名。

Q: 2. 写 SKILL.md

--- name: hello-world description: A simple skill that prints a greeting. --- # Hello World When the user asks for a greeting, use the `exec` tool to run: ```bash echo "Hello from your custom skill!"

Q: 3. 验证加载

openclaw skills list 如果列表里没有，开新会话或重启 Gateway： openclaw gateway restart

一、先说个场景

你已经在用 OpenClaw 处理很多日常任务了：查邮件、搜网页、跑 shell。但总有那么几件事，每次都要重复解释——”帮我整理今天的下载文件””把周报格式化成三段””把截图里的文字提取出来放进笔记”。这些任务步骤固定，参数也固定，最适合做成 Skill。

这篇文章把官方 hello-world 示例完整拆开，同时演示一个”能真干活”的改进版，让你不只是跑通示例，而是知道怎么把它变成自己的工具。

技能不等于脚本，但经常包着脚本。区别在于：脚本是”死”的步骤，你要点一下才跑；技能是”活”的说明，agent 能自己判断什么时候该跑。所以一个常见写法是：把真正的逻辑放在 scripts/ 里的脚本，把”何时调用、调哪个”写在 SKILL.md 正文。这样既享受了脚本的确定与可测试，又享受了技能的自触发与可发现。两者不是替代，是搭档。

二、为什么是这样

OpenClaw 的技能就是一份”目录 + SKILL.md”。SKILL.md 的 YAML frontmatter 告诉系统这个 skill 叫什么、谁能调用；正文用 Markdown 写给 agent：什么时候触发、调用什么工具、参数怎么给。

和直接在聊天里下指令相比，Skill 有三个好处：

稳定：同样的话术，不会因为措辞不同而结果不同。
可复用：你、你的不同 agent、甚至团队成员都能用。
可共享：写好可以发到 ClawHub，别人一个命令就能装上。

所以写 Skill 的核心不是”学一门新语言”，而是把一段可重复的工作流写成清晰的指令。Markdown 加 YAML，几乎没有学习门槛。

三、跟着做：分步操作

1. 建目录

mkdir -p ~/.openclaw/workspace/skills/hello-world

注意：目录名最好和 frontmatter 里的 name 一致。官方允许分组布局，比如：

mkdir -p ~/.openclaw/workspace/skills/personal/hello-world

技能名仍由 SKILL.md 的 name 决定，目录路径不影响最终调用名。

2. 写 SKILL.md

---
name: hello-world
description: A simple skill that prints a greeting.
---

# Hello World

When the user asks for a greeting, use the `exec` tool to run:

```bash
echo "Hello from your custom skill!"
```

拆解：

name：slug，只能小写字母、数字、连字符。
description：给 agent 和命令发现看的，一行，160 字符以内。
正文：明确的触发条件 + 明确的工具调用 + 明确的参数。

3. 验证加载

openclaw skills list

如果列表里没有，开新会话或重启 Gateway：

openclaw gateway restart

4. 测试

openclaw agent --message "give me a greeting"

或聊天里直接说”给我打个招呼”，也可以显式 /skill hello-world。

四、可以复制的指令

# 创建技能目录
mkdir -p ~/.openclaw/workspace/skills/hello-world

# 验证已加载
openclaw skills list

# 测试
openclaw agent --message "give me a greeting"

# 显式调用
/skill hello-world

# 刷新 Gateway
openclaw gateway restart

下面这个 tidy-downloads 不是玩具，但也不复杂，正好卡在”能真干活”的门槛上。选”下载目录”做例子，是因为它人人都有、文件杂乱、整理规则清晰。之所以设”超过 30 天再删”，是为了给误放的重要文件留缓冲；之所以”超过 50 个文件先问一句”，是避免脚本一口气大动干戈而你毫无察觉。这些”分寸”正是 SKILL.md 正文该写清楚的判断，模型照做即可，不必每次跟你确认。

这个例子里最该记住的是 {baseDir}：它表示技能目录自身的绝对路径，脚本用 {baseDir}/scripts/tidy.sh 引用，换台机器、换个位置都不用改代码。若把路径写死成 /home/me/...，你分享给别人，或自己重装系统，脚本立刻找不到。凡是技能内部互相引用文件，都用 {baseDir} 或相对路径，这是”能分享”和”只能自己用”的分水岭。

把逻辑放进脚本还有个好处：脚本可以脱离 agent 单独测。你先在终端里把 tidy.sh 跑通、确认它真的把文件归到该去的地方、确认删除阈值符合预期，再让技能去调用它。这样排错时就能分层：脚本不对，就改脚本；调用不对，就改正文。若把逻辑全塞进正文让模型临场发挥，一旦出错你都不知道是该怪模型理解偏了，还是步骤本身写错了。

五、实战案例

现在我们做一个真正能用的：tidy-downloads。

场景：每天 ~/Downloads 里堆满文件，你想按文件类型整理到子目录，并自动删除超过 30 天的临时文件。

目录结构：

~/.openclaw/workspace/skills/tidy-downloads/
├── SKILL.md
└── scripts/
    └── tidy.sh

SKILL.md：

---
name: tidy-downloads
description: Organize Downloads by file type and remove files older than 30 days.
---

# Tidy Downloads

When the user says "整理下载目录" or "tidy downloads", use the `exec` tool to run the helper script at `{baseDir}/scripts/tidy.sh`. Before running, ask the user for confirmation if there are more than 50 files to move.

scripts/tidy.sh：

#!/bin/bash
DOWNLOADS="$HOME/Downloads"
find "$DOWNLOADS" -maxdepth 1 -type f -name "*.pdf" -exec mv -t "$DOWNLOADS/pdfs" {} +
find "$DOWNLOADS" -maxdepth 1 -type f \( -name "*.zip" -o -name "*.tar.gz" \) -exec mv -t "$DOWNLOADS/archives" {} +
find "$DOWNLOADS" -maxdepth 1 -type f -mtime +30 -exec rm -f {} +
echo "Downloads organized."

这里 {baseDir} 会被解析成技能目录的绝对路径，脚本位置写死了就不会因为换机器而报错。

六、常见误区

误区 1：description 随便写。它直接决定 agent 能不能在需要时想起这个 skill。不写清楚触发条件，模型永远不会调用。
误区 2：目录名和 name 不一致。虽然 frontmatter 优先，但调试时看到 hello-world 目录名却叫 my-greeting，会自己坑自己。
误区 3：把复杂逻辑全写进 SKILL.md 正文。正文应该”告诉模型做什么”，复杂脚本放到 scripts/ 目录，用 {baseDir} 引用。
误区 4：忽略权限问题。如果脚本需要写某些目录，确保运行 OpenClaw 的用户有权限。沙箱内还要单独配置二进制和权限。
误区 5：没有在本地跑通就发布。至少用 openclaw agent --message "..." 测三遍再考虑发 ClawHub。

写技能最怕的不是写得不好，而是迟迟不写。hello-world 已经帮你跨过”从零到一”，接下来只要挑一件真事，照着同样的骨架填上步骤，你就拥有了一个属于自己的、能反复用的小工具。动手比完美重要。

七、进阶玩法

加门控条件：如果你的 skill 只在 macOS 上有意义，可以在 frontmatter 里加：

---
name: mac-only-tool
description: A macOS-only helper.
metadata: { "openclaw": { "os": ["darwin"] } }
---

把脚本放在多个平台：用 requires.bins 检测平台工具是否存在，然后在正文里教 agent 按平台调用不同脚本。

自动触发：把 skill 和一个 heartbeat / cron 规则结合，让 OpenClaw 每天主动问你要不要整理下载目录，而不是等你想起才说。

给新手一句劝：第一个真实技能别贪大。先挑一件你每周都做、步骤清楚、不碰敏感数据的小事，比如整理某个固定文件夹，跑顺了再慢慢加门控、加自动触发、加多平台。技能是长出来的，不是一次设计完的。hello-world 教会你闭环，真实的小技能教会你手感，积累几个之后，你自然会知道下一个该写什么。

当你写了三五个技能，会自然出现”它们能不能连起来”的念头。比如整理下载的技能跑完，顺手调起写周报的技能把成果记一笔。这种串联不用你写编排，只要在各自正文把输入输出约定好，agent 就能在对话里顺下去。到这一步，你拥有的不再是一个个孤立小工具，而是一套贴着你习惯的工作流——这正是手写技能最让人上瘾的地方。别急着一次建庞大系统，先让每个小技能都真正好用，连接会水到渠成。

八、小结

手写 Skill 只需要三件事：目录、SKILL.md、测试。SKILL.md 的 frontmatter 决定身份，正文决定行为。hello-world 跑通之后，立刻用它改造一个自己的真实工作流——整理文件、格式化周报、处理截图——这样你才真正理解 Skill 的用处。记住 {baseDir} 和 scripts/ 这两个组合，它们是从玩具示例迈向实用技能的关键一步。当你手头攒了三五个这样的小技能，回头看会发现：你不是在”用工具”，而是在”养一个越来越懂你工作习惯的助手”。

老周的工具笔记