Introduction
Building your own OpenClaw Skill is both fun and rewarding. This tutorial walks you through creating a weather query Skill from the ground up. By completing this hands-on project, you'll master the core concepts and the complete workflow of Skill development.
Skill Fundamentals
An OpenClaw Skill is essentially a SKILL.md file that uses natural language to define how the AI assistant should behave in a specific scenario. Skill files are stored in the ~/.openclaw/skills/ directory.
A Skill consists of the following key components:
| Component | Description | Required |
|---|---|---|
| Name and Description | Identification information for the Skill | Yes |
| Trigger Conditions | When the Skill should be activated | Yes |
| Behavior Definition | What to do once activated | Yes |
| Output Format | Format and style of the response | Recommended |
| MCP Tools | External tools to invoke | As needed |
SKILL.md File Structure
A standard SKILL.md file is structured as follows:
---
name: skill-name
version: 1.0.0
description: Brief description of the skill
triggers:
- keyword1
- keyword2
mcp_tools:
- tool_name
---
# Skill Title
## Description
Detailed description of what this skill does.
## Behavior
Instructions for how the AI should behave when this skill is activated.
## Output Format
How the response should be formatted.
Step 1: Plan the Weather Skill
Before writing any code, plan out the skill's functionality:
- Features: Query weather information for a given city (current conditions + forecast)
- Trigger Words: 天气, weather, 气温, 温度, 下雨
- Data Source: Call the OpenWeatherMap API via an MCP tool
- Output: Formatted weather information card
Step 2: Set Up the MCP Weather Tool
Before using the weather API, configure the MCP tool in the OpenClaw settings. Edit ~/.config/openclaw/openclaw.json5:
{
mcp: {
servers: {
"weather-api": {
// Use an HTTP-type MCP service
command: "npx",
args: ["-y", "@openclaw-mcp/http-fetch"],
env: {
// OpenWeatherMap API key
OPENWEATHER_API_KEY: "your-api-key-here"
}
}
}
}
}
If you don't have an OpenWeatherMap API key yet, sign up for a free one at https://openweathermap.org/api.
Step 3: Write the SKILL.md
Create a weather.SKILL.md file in the ~/.openclaw/skills/ directory:
---
name: weather
version: 1.0.0
description: 查询全球城市天气信息，支持当前天气和未来预报
triggers:
- 天气
- weather
- 气温
- 温度
- 下雨
- 下雪
- 预报
- forecast
mcp_tools:
- http_fetch
---
# 天气查询技能
## Description
这是一个天气查询技能，当用户询问任何与天气相关的问题时激活。
支持查询全球任意城市的当前天气和未来天气预报。
## Behavior
当用户询问天气信息时，按以下步骤执行：
1. **提取城市名称**：从用户消息中识别出目标城市。如果用户没有指定城市，
询问用户想查询哪个城市的天气。
2. **调用天气 API**：使用 http_fetch 工具调用 OpenWeatherMap API：
- 当前天气：`https://api.openweathermap.org/data/2.5/weather?q={city}&appid={OPENWEATHER_API_KEY}&units=metric&lang=zh_cn`
- 未来预报：`https://api.openweathermap.org/data/2.5/forecast?q={city}&appid={OPENWEATHER_API_KEY}&units=metric&lang=zh_cn&cnt=24`
3. **解析数据**：从 API 返回的 JSON 中提取关键信息。
4. **格式化输出**：按照下方输出格式模板返回结果。
## Data Parsing
从 API 响应中提取以下字段：
- `main.temp` - 当前温度（摄氏度）
- `main.feels_like` - 体感温度
- `main.humidity` - 湿度百分比
- `weather[0].description` - 天气描述
- `wind.speed` - 风速（m/s）
- `main.temp_min` - 最低温度
- `main.temp_max` - 最高温度
- `sys.sunrise` - 日出时间（Unix时间戳，转换为当地时间）
- `sys.sunset` - 日落时间
## Output Format
使用以下格式回复用户：
### 当前天气查询
🌤️ {城市名} 天气
📍 当前天气：{天气描述} 🌡️ 温度：{当前温度}°C（体感 {体感温度}°C） 📊 温度范围：{最低温}°C ~ {最高温}°C 💧 湿度：{湿度}% 💨 风速：{风速} m/s 🌅 日出：{日出时间} 🌇 日落：{日落时间}
### 未来预报查询
📅 {城市名} 未来天气预报
| 时间 | 天气 | 温度 | 湿度 |
|---|---|---|---|
| {时间1} | {天气1} | {温度1}°C | {湿度1}% |
| {时间2} | {天气2} | {温度2}°C | {湿度2}% |
| ... |
## Additional Instructions
- 如果城市名称不明确（如"长安"可能指西安），列出可能的选项让用户选择
- 如果 API 返回错误或城市不存在，友好地告知用户并建议检查城市名称
- 温度使用摄氏度，风速使用 m/s
- 根据天气情况给出简短的生活建议（如带伞、防晒、添衣等）
- 时间显示使用 24 小时制
Step 4: Test the Skill
Method 1: Local Testing
Restart OpenClaw and test:
# Restart to load the new skill
openclaw restart
# Confirm the skill is loaded
openclaw skill list
Then send a test message in any connected chat channel:
北京今天天气怎么样？
Method 2: Using Debug Mode
OpenClaw provides a debug mode to help with skill development:
# Enable verbose logging
openclaw logs --level debug
The debug logs will show the skill's trigger and execution process:
[DEBUG] Message received: "北京今天天气怎么样？"
[DEBUG] Skill matching: checking triggers...
[DEBUG] Skill 'weather' matched by trigger: "天气"
[DEBUG] Activating skill: weather
[DEBUG] MCP tool call: http_fetch -> openweathermap API
[DEBUG] API response: 200 OK
[DEBUG] Skill 'weather' execution complete
Method 3: Testing via the Gateway API Directly
Bypass the chat channels and call the Gateway API directly:
curl -X POST http://localhost:18789/api/chat \
-H "Content-Type: application/json" \
-d '{
"message": "上海明天会下雨吗？",
"context": []
}'
Step 5: Refine the Output
Adding Lifestyle Advice Logic
Add weather-based advice rules to the Behavior section of SKILL.md:
## Weather Advice Rules
根据天气数据给出对应建议：
- 温度 > 35°C：提醒防暑降温，多饮水
- 温度 < 0°C：提醒注意保暖，路面可能结冰
- 湿度 > 80%：可能会感觉闷热
- 天气描述包含"雨"：建议携带雨具
- 天气描述包含"雪"：注意出行安全
- 风速 > 10 m/s：注意防风
- UV 指数 > 6：建议涂防晒霜
Supporting Fuzzy Queries
Add more natural language patterns to the trigger conditions:
triggers:
- 天气
- 要不要带伞
- 穿什么衣服
- 会不会下雨
- 冷不冷
- 热不热
Step 6: Add Multilingual Support
Enable the skill to automatically switch output language based on the user's language.
Add the following to SKILL.md:
## Multilingual Support
- 检测用户消息的语言
- 如果用户使用中文提问，用中文回复
- 如果用户使用英文提问，用英文回复
- API 调用时使用对应的 `lang` 参数：
- 中文：`lang=zh_cn`
- 英文：`lang=en`
- 日文：`lang=ja`
Final File Checklist
After development is complete, your project structure should look like this:
~/.openclaw/skills/
└── weather.SKILL.md # Skill definition file
~/.config/openclaw/
└── openclaw.json5 # Contains the MCP weather tool configuration
Publishing to ClawHub
If you're happy with the skill, you can publish it to the ClawHub marketplace:
# Create a publishing directory
mkdir ~/weather-skill && cd ~/weather-skill
# Copy the skill file
cp ~/.openclaw/skills/weather.SKILL.md ./SKILL.md
# Create metadata
cat > clawhub.json << 'EOF'
{
"name": "weather-forecast-cn",
"version": "1.0.0",
"description": "中英文天气查询技能，支持全球城市",
"author": "your-username",
"license": "MIT",
"keywords": ["weather", "forecast", "天气"],
"category": "信息查询"
}
EOF
# Validate and publish
npx clawhub@latest validate
npx clawhub@latest publish
FAQ
API Calls Fail
Check that the API key is correctly configured:
# Test the API key
curl "https://api.openweathermap.org/data/2.5/weather?q=Beijing&appid=YOUR_KEY"
Skill Doesn't Get Triggered
- Confirm that the trigger word list includes keywords found in the user's message
- Check whether another skill's trigger words are conflicting
- Review debug logs for matching details
Output Format Isn't Ideal
The output format in SKILL.md serves as instructions to the AI rather than a rigid template — the AI will understand the intent but may not follow it exactly. Try being more specific in the format description, or add example outputs.
Summary
Through this tutorial, you've completed a fully functional weather query Skill. The key takeaways include structured SKILL.md authoring, MCP tool configuration and invocation, trigger condition design, and output format optimization. These skills are transferable to any other type of Skill development.