OpenClaw 3.13 Skill编写初探（Docker）

基于"say hello" skill尝试开发总结

🎯 核心理解

OpenClaw 技能的本质

1. SKILL.md 是纯文档- 只描述技能，不执行代码
2. 技能激活是提示- 告诉助手这个技能相关
3. 助手手动执行- 看到技能激活后，助手调用实际脚本
4. 返回脚本输出- 把脚本执行结果返回给用户

错误理解 vs 正确理解

• ❌ 错误：SKILL.md 包含可执行逻辑
• ✅ 正确：SKILL.md 只是说明书，代码在 scripts/ 目录
• ❌ 错误：技能自动运行脚本
• ✅ 正确：助手看到技能后手动运行脚本

📁 最简技能结构

必需文件

my-skill/ ├── SKILL.md # 技能描述（必需） └── scripts/ # 脚本目录（推荐） └── main.py # 主脚本

可选文件

my-skill/ ├── skill.json # 配置（可选） └── references/ # 参考文档（可选）

📝 SKILL.md 编写

最简模板

# 技能名称 ## 描述 一句话说明技能功能。 ## 使用场景 用户说什么话时激活。 ## 执行指令 ```bash cd /path/to/skill/scripts && python3 main.py

示例输出

这里是脚本执行后的输出示例。

### 小东技能示例 ```markdown # 小东 - 简洁打招呼 ## 描述 当用户说"小东"时回复问候和当前时间。 ## 使用场景 用户说 "小东" ## 执行指令 ```bash cd /home/node/.openclaw/workspace/skills/xiaodong/scripts && python3 simple_hello.py

示例输出

在呢！晚上好啊，现在是 2026-03-22 23:56 (北京时间)。需要我干点啥不？

--- ## 🐍 Python 脚本编写 ### 最简模板 ```python #!/usr/bin/env python3 # scripts/main.py def main(): # 你的业务逻辑 result = "处理结果" print(result) # 重要：使用 print 输出结果 if __name__ == '__main__': main()

小东脚本示例

#!/usr/bin/env python3# scripts/simple_hello.pyimportdatetimedefget_beijing_time():"""获取北京时间 (UTC+8)"""utc_now=datetime.datetime.now(datetime.timezone.utc)returnutc_now+datetime.timedelta(hours=8)defget_greeting(hour):"""根据小时返回问候语"""if5<=hour<12:return"早上好"elif12<=hour<14:return"中午好"elif14<=hour<18:return"下午好"else:return"晚上好"defmain():beijing_time=get_beijing_time()hour=beijing_time.hour greeting=get_greeting(hour)time_str=beijing_time.strftime("%Y-%m-%d %H:%M")# 输出结果，助手会把这个返回给用户print(f"在呢！{greeting}啊，现在是{time_str}(北京时间)。需要我干点啥不？")if__name__=='__main__':main()

🚀 开发流程

1. 创建目录

mkdirmy-skillcdmy-skillmkdirscripts

2. 编写脚本

cat>scripts/main.py<<'EOF' #!/usr/bin/env python3 print("这是我的技能输出") EOFchmod+x scripts/main.py

3. 编写 SKILL.md

cat>SKILL.md<<'EOF'# 我的技能## 描述测试技能## 使用场景用户说"测试"## 执行指令```bashcd/path/to/my-skill/scripts&&python3 main.py

示例输出

这是我的技能输出

EOF

### 4. 部署技能 ```bash # 复制到工作区技能目录 cp -r my-skill /home/node/.openclaw/workspace/skills/

5. 测试技能

1. 用户说技能关键词（如"测试"）
2. 助手看到技能激活
3. 助手手动执行：cd /path/to/skill/scripts && python3 main.py
4. 助手返回脚本输出

📍 部署位置

正确位置（推荐）

/home/node/.openclaw/workspace/skills/my-skill/

权限要求

• 目录所有者必须是node用户
• OpenClaw 以node用户运行

🔧 调试技巧

1. 手动测试脚本

cd/path/to/skill/scripts python3 main.py

2. 检查权限

ls-la/home/node/.openclaw/workspace/skills/my-skill/# 应该显示所有者是 node

3. 检查技能激活

• 用户说定义的关键词
• 助手应该看到技能提示
• 助手手动执行脚本

4. 查看脚本输出

# 直接运行看输出python3 scripts/main.py

❌ 常见误区

误区1：SKILL.md 包含可执行代码

• ❌ 错误：在 SKILL.md 中写 Python 代码
• ✅ 正确：SKILL.md 只写描述，代码在 scripts/

误区2：技能自动运行

• ❌ 错误：认为技能关键词会自动触发脚本
• ✅ 正确：助手看到关键词后手动运行脚本

误区3：需要 .sh 包装脚本

• ❌ 错误：创建 run.sh 包装 Python 脚本
• ✅ 正确：直接执行 Python 脚本更简洁

误区4：复杂目录结构

• ❌ 错误：创建复杂的 references/ assets/ 等目录
• ✅ 正确：从最简结构开始，需要时再添加

🎯 最佳实践

1. 保持简洁

• 一个技能解决一个问题
• 最简文件结构：SKILL.md + scripts/main.py
• 避免不必要的配置文件

2. 明确输出

• 脚本使用print()输出结果
• 输出格式友好，适合直接显示
• 包含必要的上下文信息

3. 完整文档

• SKILL.md 包含清晰的执行指令
• 提供示例输入和输出
• 说明技能的使用场景

4. 易于测试

• 脚本可以独立运行测试
• 提供简单的测试方法
• 输出结果可预测

📚 小东技能完整代码

文件结构

xiaodong/ ├── SKILL.md └── scripts/ └── simple_hello.py

SKILL.md

# 小东 - 简洁打招呼 ## 描述 当用户说"小东"时回复问候和当前时间。 ## 使用场景 用户说 "小东" ## 执行指令 ```bash cd /home/node/.openclaw/workspace/skills/xiaodong/scripts && python3 simple_hello.py

示例输出

在呢！晚上好啊，现在是 2026-03-22 23:56 (北京时间)。需要我干点啥不？

### scripts/simple_hello.py ```python #!/usr/bin/env python3 import datetime def get_beijing_time(): utc_now = datetime.datetime.now(datetime.timezone.utc) return utc_now + datetime.timedelta(hours=8) def get_greeting(hour): if 5 <= hour < 12: return "早上好" elif 12 <= hour < 14: return "中午好" elif 14 <= hour < 18: return "下午好" else: return "晚上好" def main(): beijing_time = get_beijing_time() hour = beijing_time.hour greeting = get_greeting(hour) time_str = beijing_time.strftime("%Y-%m-%d %H:%M") print(f"在呢！{greeting}啊，现在是 {time_str} (北京时间)。需要我干点啥不？") if __name__ == '__main__': main()