本文依据2026-11-11核对的官方文档整理,未做本地安装实测;命令与界面以对应版本为准。下面使用官方的 hello-world 最小示例,走完创建目录、编写文件、检查加载和显式调用四步。

Skill 文件里究竟写什么

OpenClaw 的 Skill 是一个包含 SKILL.md 的目录。文件开头使用 YAML frontmatter 提供名称与描述,后面的 Markdown 告诉 agent 在什么情况下执行什么步骤。

这个示例只运行一条问候命令,不接入外部账号,不操作业务文件。开始前先完成 OpenClaw 安装与启动。以下路径使用官方示例中的默认 workspace;若实际使用的是其他工作区,应先核对当前工作区位置。

第一步:创建 Skill 目录

在运行 OpenClaw 的机器上执行:

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

然后在该目录中创建名为 SKILL.md 的文本文件。目录结构应为:

~/.openclaw/workspace/
└── skills/
    └── hello-world/
        └── SKILL.md

目录名、文件名和 frontmatter 中的名称分别检查,不要把文件保存成 SKILL.md.txt。

第二步:写入完整 SKILL.md

将下面完整内容保存到 ~/.openclaw/workspace/skills/hello-world/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 使用小写字母、数字和连字符,并与目录名保持一致;description 是供 agent 及命令发现使用的一行说明。以后换成自己的任务时,先改清楚输入、步骤和输出要求,再逐渐添加依赖。

正文中出现的 exec 是这份示例要求使用的工具。验收时应检查它是否实际被调用并成功执行,不能仅凭目录里存在文件就判断示例成功。

第三步:确认 OpenClaw 识别到了它

执行:

openclaw skills list

预期结果:可以在技能列表中检查到 hello-world。列表检查用于判断“有没有被识别”,不等于里面的命令已经运行。

所参考的文档说明,OpenClaw 默认监视 Skills 根目录下的 SKILL.md 变化。若监视被关闭,或继续使用既有会话,官方建议开启新会话,让 agent 获取更新后的列表。

在聊天中使用:

/new

第四步:显式调用并检查结果

在聊天入口输入:

/hello-world

这里使用按技能名生成的斜杠命令。官方文档在命名说明中将 hello-world 对应到 /hello-world;不同版本的通用调用入口可能不同,本文不把另一个入口写成所有版本的统一命令。如果当前界面未识别它,也可以在新会话里明确要求“使用 hello-world 技能完成问候”,再检查技能与工具执行记录。

预期结果:示例使用 exec 执行问候命令,其标准输出为:

Hello from your custom skill!

这里的输出是示例命令的预期结果,不是本站的实测截图或日志。验收时既要看最终回复,也要核对实际工具执行记录;模型在聊天里直接复述相同句子,不能单独证明命令已执行。

没生效时,按三个阶段检查

现象 先核对什么 修复后再做什么
列表中没有技能 工作区是否正确,目录与文件名是否一致,frontmatter 是否完整 再运行 openclaw skills list
文件修改后仍像旧版本 是否还在既有会话,是否需要刷新列表 新会话中显式调用
能识别但没有运行命令 当前环境是否提供并允许所需工具,实际执行记录是什么 检查工具结果,再核对输出

第一轮只验证这个最小示例。它能帮助区分文件加载、技能调用和工具执行的问题;跑通之后,再将内容替换为自己的任务,避免同时加入多个外部服务导致无法判断哪一步出错。

继续阅读

参考资料与核对日期

资料核对:2026-11-11。以下为对应的官方文档入口;本文为文档整理,未作本地安装实测。