创建自定义 Skill

概述

Skills 通过 SKILL.md 文件向 Agent 传授工具使用方法。每个 Skill 是一个目录，包含带 YAML frontmatter 的 Markdown 指令文件。本页介绍从零创建自定义 Skill 的完整流程。

核心功能

• 最小结构：一个目录 + 一个 SKILL.md 文件即可构成完整 Skill
• frontmatter 元数据：控制 Skill 名称、描述、OS 过滤、依赖二进制、配置要求
• 自动加载：放入 workspace skills/ 目录后，新 session 或 /new 即可生效
• slash command 暴露：user-invocable: true（默认）时自动注册为 slash command
• 工具集成：可在 frontmatter 定义自定义 tool schema，或指令 Agent 使用现有系统工具

配置/使用

创建步骤

# 1. 创建 Skill 目录
mkdir -p ~/.openclaw/workspace/skills/hello-world
 
# 2. 编写 SKILL.md
cat > ~/.openclaw/workspace/skills/hello-world/SKILL.md << 'EOF'
---
name: hello-world
description: A simple skill that says hello.
---
 
# Hello World Skill
 
When the user asks for a greeting, use the `echo` tool to say
"Hello from your custom skill!".
EOF
 
# 3. 加载 Skill（新建 session 或重启 gateway）
openclaw gateway restart
 
# 4. 验证加载
openclaw skills list
 
# 5. 测试
openclaw agent --message "give me a greeting"

frontmatter 字段参考

字段	必填	说明
name	是	唯一标识符，小写字母+数字+连字符
description	是	展示给 Agent 的单行描述
metadata.openclaw.os	否	OS 过滤（["darwin"]、["linux"] 等）
metadata.openclaw.requires.bins	否	PATH 上必须存在的二进制
metadata.openclaw.requires.config	否	必须为 truthy 的配置键

最佳实践

• 指令要简洁，告诉模型做什么，而非如何成为 AI
• 使用 exec 工具时，确保提示词不允许不可信输入注入任意命令
• 用 openclaw agent --message "..." 本地测试后再分享
• 通过 ClawHub 浏览和贡献 Skills

Skill 存放位置（优先级高→低）

位置	优先级	作用域
<workspace>/skills/	最高	单 Agent
<workspace>/.agents/skills/	高	单 workspace Agent
~/.agents/skills/	中	所有 Agent（本机）
~/.openclaw/skills/	中	所有 Agent（本机）
内置 bundled skills	低	全局
skills.load.extraDirs	最低	自定义共享目录

相关页面

• concepts/tool-skills — Skills 系统完整参考，加载优先级，Gating 规则
• concepts/tool-skills-config — skills.* 配置 schema
• concepts/tool-clawhub — ClawHub 公共 Skill 注册表
• concepts/tool-plugin — 插件可附带 Skills