用户请求 → 智能体分析 → 匹配相关技能 → 参考 SKILL.md → 执行工具调用 → 返回结果
                              ↓
                        提供指导而非控制

天气技能 SKILL.md:
  - 告诉智能体：当用户问天气时，可以使用 curl 查询 wttr.in
  - 提供具体的 curl 命令格式
  - 智能体参考这些信息，决定执行相应命令

~/.npm-global/lib/node_modules/openclaw/skills/
├── skill-name/
│   └── SKILL.md      # 核心技能文档
└── other-skill/
    └── SKILL.md

---
name: skill-name
description: "技能简要描述"
metadata:
  {
    "openclaw":
      {
        "emoji": "🎯",
        "requires": { "bins": ["required-command"] },
      },
  }
---

# 技能标题

## When to Use
✅ **使用场景：**
- 场景1描述
- 场景2描述

## When NOT to Use
❌ **避免使用场景：**
- 不适用场景1
- 不适用场景2

## 具体实现
提供具体的命令示例、工具调用方式等。

## 示例
展示典型的使用案例。

## 注意事项
安全限制、性能考虑等。

---
name: weather
description: "Get current weather and forecasts via wttr.in or Open-Meteo. Use when: user asks about weather, temperature, or forecasts for any location."
metadata:
  {
    "openclaw":
      {
        "emoji": "☔",
        "requires": { "bins": ["curl"] },
      },
  }
---

# Weather Skill

## When to Use
✅ **USE this skill when:**
- "What's the weather?"
- "Will it rain today/tomorrow?"
- "Temperature in [city]"
- "Weather forecast for the week"

## When NOT to Use
❌ **DON'T use this skill when:**
- Historical weather data
- Climate analysis or trends
- Severe weather alerts

## Commands

### Current Weather
```bash
# One-line summary
curl "wttr.in/London?format=3"

# Detailed current conditions
curl "wttr.in/London?0"

# 3-day forecast
curl "wttr.in/London"

# Week forecast
curl "wttr.in/London?format=v2"

curl -s "wttr.in/London?format=%l:+%c+%t+(feels+like+%f),+%w+wind,+%h+humidity"

### 3.3 设计要点

1. **清晰的边界定义**：明确说明何时使用和何时不使用
2. **具体的命令示例**：提供可直接运行的 curl 命令
3. **格式选项丰富**：展示不同的输出格式
4. **实用注意事项**：包含速率限制等实际考虑

## 4. 高级技能设计：GitHub 信息查询

### 4.1 技能设计思路

虽然 OpenClaw 技能本身不包含自动化监控逻辑，但可以设计一个 GitHub 信息查询技能，提供获取仓库状态的指导。这样的技能应该：
- 提供查询 GitHub 仓库信息的命令示例
- 说明如何检查最新提交、问题或发布
- 给出处理 API 限制的建议
- 提供常见查询场景的解决方案

### 4.2 技能设计示例

```markdown
---
name: github-info
description: "Get information about GitHub repositories, including commits, issues, and releases."
metadata:
  {
    "openclaw":
      {
        "emoji": "🐙",
        "requires": { "bins": ["curl", "jq"] },
      },
  }
---

# GitHub Repository Information

## When to Use
✅ **USE this skill when:**
- "Check latest commits for [repo]"
- "What's new in [project]"
- "GitHub repository status"
- "Recent releases of [library]"

## When NOT to Use
❌ **DON'T use this skill when:**
- Real-time monitoring needed → use GitHub Actions or webhooks
- Automated notifications → use GitHub Watch feature
- Bulk data analysis → use GitHub API directly with scripts

## Basic Queries

### Latest Commits
```bash
# Get latest 5 commits
curl -s -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/openclaw/openclaw/commits?per_page=5 | \
  jq '.[] | {sha: .sha[:7], author: .commit.author.name, message: .commit.message[:50]}'

# Get latest release
curl -s -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/openclaw/openclaw/releases/latest | \
  jq '{name: .name, tag: .tag_name, published: .published_at, url: .html_url}'

# Get open issues
curl -s -H "Accept: application/vnd.github.v3+json" \
  "https://api.github.com/repos/openclaw/openclaw/issues?state=open&per_page=5" | \
  jq '.[] | {number: .number, title: .title, user: .user.login}'

# Check rate limit status
curl -s -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/rate_limit | \
  jq '.resources.core'

# With authentication
curl -s -H "Authorization: token YOUR_TOKEN" \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/openclaw/openclaw/commits

## 5. 技能开发最佳实践

### 5.1 设计原则

1. **单一职责原则**：每个技能只负责一个明确的功能领域
2. **明确边界**：清晰定义技能的输入、输出和副作用
3. **可配置性**：提供必要的配置选项，适应不同使用场景
4. **向后兼容**：技能更新时保持接口兼容性

### 5.2 文档规范

完整的技能文档应包括：

```markdown
## 版本历史
- v1.0.0 (2026-04-09): 初始版本，基础天气查询
- v1.1.0 (2026-04-16): 添加多日预报和缓存支持

## 依赖说明
- 需要网络连接
- 依赖 wttr.in 或 OpenWeatherMap API

## 性能考虑
- API 调用频率限制
- 响应时间优化
- 内存使用监控

## 安全注意事项
- 输入验证和清理
- API 密钥管理（如使用付费 API）
- 数据隐私保护

# 检查技能文件位置
ls -la ~/.npm-global/lib/node_modules/openclaw/skills/

# 查看可用技能列表
openclaw skills list

# 检查技能文件格式
grep -n "^---" ~/.npm-global/lib/node_modules/openclaw/skills/weather/SKILL.md

# 系统技能目录（npm 全局安装）
~/.npm-global/lib/node_modules/openclaw/skills/

# 自定义技能目录
~/.openclaw/skills/  # 用户自定义技能位置

# 创建自定义技能目录
mkdir -p ~/.openclaw/skills/my-custom-skill

# 创建 SKILL.md 文件
cat > ~/.openclaw/skills/my-custom-skill/SKILL.md << 'EOF'
---
name: my-custom-skill
description: "My custom skill description"
---

# My Custom Skill

## When to Use
- When user needs specific functionality

## Implementation
Provide guidance and examples here.
EOF

## 版本历史

### v1.2.0 (2026-04-23)
- 新增：支持多语言城市名称
- 优化：缓存策略改进
- 修复：时区处理问题

### v1.1.0 (2026-04-16)
- 新增：多日天气预报支持
- 优化：错误处理机制
- 文档：添加详细使用示例

### v1.0.0 (2026-04-09)
- 初始版本发布
- 基础天气查询功能
- 支持中文城市名称

---
name: file-organizer
description: "Guidance for organizing files by type, date, or project."
---

# File Organization Guidance

## When to Use
- "Organize my downloads folder"
- "Sort files by type"
- "Clean up old files"

## Command Examples

### Organize by File Type
```bash
# Create directories for different file types
mkdir -p ~/Downloads/{images,docs,archives,code}

# Move files to appropriate directories
mv ~/Downloads/*.jpg ~/Downloads/*.png ~/Downloads/*.gif ~/Downloads/images/ 2>/dev/null || true
mv ~/Downloads/*.pdf ~/Downloads/*.doc ~/Downloads/*.docx ~/Downloads/docs/ 2>/dev/null || true
mv ~/Downloads/*.zip ~/Downloads/*.tar ~/Downloads/*.gz ~/Downloads/archives/ 2>/dev/null || true

# Find files older than 30 days
find ~/Downloads -type f -mtime +30 -exec ls -la {} \;

# Remove files older than 90 days (with confirmation)
find ~/Downloads -type f -mtime +90 -exec rm -i {} \;

### 8.2 笔记整理指导技能

**技能目的**：提供从各种来源整理笔记的方法

**技能内容示例**：
```markdown
---
name: note-organizer
description: "Guidance for collecting and organizing notes from various sources."
---

# Note Organization Guidance

## When to Use
- "Organize my reading notes"
- "Combine notes from different sources"
- "Create a summary from meeting notes"

## Source-Specific Guidance

### From Kindle Highlights
```bash
# Kindle highlights are usually in My Clippings.txt
# Extract and format highlights
grep -A1 -B1 "Your Highlight" ~/Documents/My\ Clippings.txt | \
  sed 's/==========/---/g' > ~/Documents/kindle_highlights.md

# Use readability tools to extract main content
# Install readability-cli if needed
# npm install -g readability-cli
readable https://example.com/article > ~/Documents/article_summary.md

# Combine markdown files with headers
for file in ~/Documents/notes/*.md; do
  echo "# $(basename "$file" .md)" >> combined_notes.md
  echo "" >> combined_notes.md
  cat "$file" >> combined_notes.md
  echo -e "\n---\n" >> combined_notes.md
done