OpenClaw Skills 入门与实战：从简单到复杂的工作流设计

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

skill-name/
├── SKILL.md (必需)
│   ├── YAML frontmatter (必需)
│   │   ├── name: (必需)
│   │   └── description: (必需)
│   └── Markdown 指令 (必需)
└── 可选资源
    ├── scripts/    - 可执行脚本 (Python/Bash/等)
    ├── references/ - 详细文档 (按需加载)
    └── assets/     - 输出资源 (模板/图片/等)

1
2

mkdir -p ~/.openclaw/skills/weather
cd ~/.openclaw/skills/weather

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

---
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. NOT for: historical weather data, severe weather alerts, or detailed meteorological analysis. No API key needed."
homepage: https://wttr.in/:help
metadata: { "openclaw": { "emoji": "🌤️", "requires": { "bins": ["curl"] } } }
---

# Weather Skill

Get current weather conditions and forecasts.

## When to Use

✅ **USE this skill when:**

- "What's the weather?"
- "Will it rain today/tomorrow?"
- "Temperature in [city]"
- "Weather forecast for the week"
- Travel planning weather checks

## When NOT to Use

❌ **DON'T use this skill when:**

- Historical weather data → use weather archives/APIs
- Climate analysis or trends → use specialized data sources
- Hyper-local microclimate data → use local sensors
- Severe weather alerts → check official NWS sources
- Aviation/marine weather → use specialized services (METAR, etc.)

## Location

Always include a city, region, or airport code in weather queries.

## Commands

### Current Weather

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

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

# Specific city
curl "wttr.in/New+York?format=3"

1
2
3
4
5
6
7
8

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

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

# Specific day (0=today, 1=tomorrow, 2=day after)
curl "wttr.in/London?1"

1
2
3
4
5
6
7
8

# One-liner
curl "wttr.in/London?format=%l:+%c+%t+%w"

# JSON output
curl "wttr.in/London?format=j1"

# PNG image
curl "wttr.in/London.png"

1

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

1

curl -s "wttr.in/London?format=%l:+%c+%p"

1

curl "wttr.in/London?format=v2"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

### 1.3 关键设计点

**为什么这样设计？**

1. **`description` 覆盖全面**：
   - ✅ 说明功能："Get current weather and forecasts"
   - ✅ 说明触发场景："user asks about weather, temperature..."
   - ✅ 说明边界："NOT for historical weather data..."
   - ✅ 说明依赖："No API key needed"

2. **提供可执行的命令**：
   - Agent 不需要"理解"天气 API，只需要执行命令
   - 提供多种格式选项（简单输出、JSON、图片）

3. **明确边界**：
   - 告诉 Agent **何时不用** 这个 Skill
   - 避免在不合适的场景触发

4. **零依赖**：
   - 只需要 `curl`（Linux/macOS 默认安装）
   - 不需要 API key

### 1.4 测试 Skill

**用户问**：
> "深圳今天天气怎么样？"

**Agent 行为**：
1. 匹配 `description` 中的触发条件
2. 加载 SKILL.md 主体
3. 执行命令：
   ```bash
   curl "wttr.in/Shenzhen?format=3"

1
2

mkdir -p ~/.openclaw/skills/tmux
cd ~/.openclaw/skills/tmux

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

---
name: tmux
description: Remote-control tmux sessions for interactive CLIs by sending keystrokes and scraping pane output.
metadata:
  { "openclaw": { "emoji": "🧵", "os": ["darwin", "linux"], "requires": { "bins": ["tmux"] } } }
---

# tmux Session Control

Control tmux sessions by sending keystrokes and reading output. Essential for managing Claude Code sessions.

## When to Use

✅ **USE this skill when:**

- Monitoring Claude/Codex sessions in tmux
- Sending input to interactive terminal applications
- Scraping output from long-running processes in tmux
- Navigating tmux panes/windows programmatically
- Checking on background work in existing sessions

## When NOT to Use

❌ **DON'T use this skill when:**

- Running one-off shell commands → use `exec` tool directly
- Starting new background processes → use `exec` with `background:true`
- Non-interactive scripts → use `exec` tool
- The process isn't in tmux
- You need to create a new tmux session → use `exec` with `tmux new-session`

## Example Sessions

| Session                 | Purpose                     |
| ----------------------- | --------------------------- |
| `shared`                | Primary interactive session |
| `worker-2` - `worker-8` | Parallel worker sessions    |

## Common Commands

### List Sessions

```bash
tmux list-sessions
tmux ls

1
2
3
4
5
6
7
8

# Last 20 lines of pane
tmux capture-pane -t shared -p | tail -20

# Entire scrollback
tmux capture-pane -t shared -p -S -

# Specific pane in window
tmux capture-pane -t shared:0.0 -p

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# Send text (doesn't press Enter)
tmux send-keys -t shared "hello"

# Send text + Enter
tmux send-keys -t shared "y" Enter

# Send special keys
tmux send-keys -t shared Enter
tmux send-keys -t shared Escape
tmux send-keys -t shared C-c          # Ctrl+C
tmux send-keys -t shared C-d          # Ctrl+D (EOF)
tmux send-keys -t shared C-z          # Ctrl+Z (suspend)

1
2
3
4
5
6
7
8

# Select window
tmux select-window -t shared:0

# Select pane
tmux select-pane -t shared:0.1

# List windows
tmux list-windows -t shared

1
2
3
4
5
6
7
8

# Create new session
tmux new-session -d -s newsession

# Kill session
tmux kill-session -t sessionname

# Rename session
tmux rename-session -t old new

1
2
3

tmux send-keys -t shared -l -- "Please apply the patch in src/foo.ts"
sleep 0.1
tmux send-keys -t shared Enter

1
2

# Look for prompts
tmux capture-pane -t worker-3 -p | tail -10 | grep -E "❯|Yes.*No|proceed|permission"

1
2
3
4
5

# Send 'y' and Enter
tmux send-keys -t worker-3 'y' Enter

# Or select numbered option
tmux send-keys -t worker-3 '2' Enter

1
2
3
4

for s in shared worker-2 worker-3 worker-4 worker-5 worker-6 worker-7 worker-8; do
  echo "=== $s ==="
  tmux capture-pane -t $s -p 2>/dev/null | tail -5
done

1

tmux send-keys -t worker-4 "Fix the bug in auth.js" Enter

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

### 2.3 关键设计点

**为什么这样设计？**

1. **明确的使用边界**：
   - ✅ 用于 **交互式 CLI**（Claude Code、Codex）
   - ❌ 不用于一次性命令（用 `exec`）
   - ❌ 不用于启动新会话（用 `exec` + `tmux new-session`）

2. **提供常用模式**：
   - 检查会话状态（`capture-pane`）
   - 发送输入（`send-keys`）
   - 管理会话（`list-sessions`, `kill-session`）

3. **特殊场景处理**：
   - 交互式 TUI 的输入安全处理（`-l` 标志）
   - 避免粘贴/多行边缘情况

4. **实际工作流示例**：
   - 检查多个 worker 会话的状态
   - 批准 Claude Code 的提示
   - 发送任务到特定会话

### 2.4 测试 Skill

**用户问**：
> "检查所有 worker 会话的状态"

**Agent 行为**：
1. 匹配 `description` 中的触发条件
2. 加载 SKILL.md 主体
3. 找到 "Check All Sessions Status" 模式
4. 执行命令：
   ```bash
   for s in shared worker-2 worker-3 worker-4 worker-5 worker-6 worker-7 worker-8; do
     echo "=== $s ==="
     tmux capture-pane -t $s -p 2>/dev/null | tail -5
   done

1
2

mkdir -p ~/.openclaw/skills/pdf-editor/{scripts,references,assets}
cd ~/.openclaw/skills/pdf-editor

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

---
name: pdf-editor
description: "Comprehensive PDF manipulation with support for merging, splitting, rotating, and text extraction. Use when working with PDF files for: (1) Merging multiple PDFs into one, (2) Splitting PDFs into separate files, (3) Rotating pages, (4) Extracting text content, (5) Reordering pages. Supports password-protected PDFs and preserves formatting."
---

# PDF Editor Skill

Complete PDF manipulation toolkit with scripts, references, and best practices.

## Quick Start

### Merge PDFs

```bash
scripts/merge_pdfs.py output.pdf input1.pdf input2.pdf input3.pdf

1
2
3
4
5

# Split into single pages
scripts/split_pdf.py input.pdf output_dir/

# Extract pages 5-10
scripts/split_pdf.py input.pdf output.pdf --pages 5-10

1
2
3
4
5

# Rotate all pages 90 degrees clockwise
scripts/rotate_pdf.py input.pdf output.pdf 90

# Rotate specific pages
scripts/rotate_pdf.py input.pdf output.pdf 180 --pages 1,3,5

1
2
3
4
5

# Extract text from PDF
scripts/extract_text.py input.pdf output.txt

# Extract with layout preservation
scripts/extract_text.py input.pdf output.txt --layout

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

需要处理 PDF？
├─ 合并多个 PDF？
│  └─ 使用 scripts/merge_pdfs.py
│
├─ 拆分 PDF？
│  ├─ 拆成单页 → scripts/split_pdf.py (无 --pages)
│  └─ 提取特定页 → scripts/split_pdf.py --pages
│
├─ 旋转页面？
│  ├─ 旋转所有页面 → scripts/rotate_pdf.py (无 --pages)
│  └─ 旋转特定页面 → scripts/rotate_pdf.py --pages
│
└─ 提取文本？
   ├─ 简单提取 → scripts/extract_text.py (无 --layout)
   └─ 保留布局 → scripts/extract_text.py --layout

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

### 3.3 创建脚本

**scripts/merge_pdfs.py**:

```python
#!/usr/bin/env python3
"""
Merge multiple PDF files into one.

Usage:
    merge_pdfs.py output.pdf input1.pdf input2.pdf [input3.pdf ...]
"""

import sys
from pathlib import Path
from pypdf import PdfWriter

def merge_pdfs(output_path: str, input_paths: list[str]) -> None:
    """Merge multiple PDFs into one."""
    writer = PdfWriter()
    
    for input_path in input_paths:
        if not Path(input_path).exists():
            print(f"Error: File not found: {input_path}", file=sys.stderr)
            sys.exit(1)
        
        print(f"Adding: {input_path}")
        writer.append(input_path)
    
    with open(output_path, 'wb') as f:
        writer.write(f)
    
    print(f"✅ Merged {len(input_paths)} PDFs into {output_path}")

if __name__ == "__main__":
    if len(sys.argv) < 3:
        print("Usage: merge_pdfs.py output.pdf input1.pdf input2.pdf [...]", file=sys.stderr)
        sys.exit(1)
    
    output = sys.argv[1]
    inputs = sys.argv[2:]
    
    merge_pdfs(output, inputs)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

#!/usr/bin/env python3
"""
Rotate pages in a PDF.

Usage:
    rotate_pdf.py input.pdf output.pdf degrees [--pages 1,3,5]
    
Examples:
    rotate_pdf.py input.pdf output.pdf 90
    rotate_pdf.py input.pdf output.pdf 180 --pages 1,3,5
"""

import argparse
from pypdf import PdfReader, PdfWriter

def rotate_pdf(input_path: str, output_path: str, degrees: int, pages: list[int] = None) -> None:
    """Rotate PDF pages."""
    reader = PdfReader(input_path)
    writer = PdfWriter()
    
    for i, page in enumerate(reader.pages):
        new_page = page
        
        # Rotate if: (1) no specific pages specified, or (2) this page is in the list
        if pages is None or i + 1 in pages:
            new_page = page.rotate(degrees)
            print(f"Rotating page {i + 1} by {degrees}°")
        
        writer.add_page(new_page)
    
    with open(output_path, 'wb') as f:
        writer.write(f)
    
    print(f"✅ Rotated PDF saved to {output_path}")

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="Rotate PDF pages")
    parser.add_argument("input", help="Input PDF file")
    parser.add_argument("output", help="Output PDF file")
    parser.add_argument("degrees", type=int, choices=[90, 180, 270], help="Rotation degrees")
    parser.add_argument("--pages", help="Page numbers to rotate (comma-separated)")
    
    args = parser.parse_args()
    
    pages = None
    if args.pages:
        pages = [int(p.strip()) for p in args.pages.split(",")]
    
    rotate_pdf(args.input, args.output, args.degrees, pages)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Advanced PDF Operations

## Password-Protected PDFs

### Open Password-Protected PDF

```python
from pypdf import PdfReader

reader = PdfReader("protected.pdf", password="secret123")

1
2
3
4
5
6

from pypdf import PdfWriter

writer = PdfWriter()
writer.append("document.pdf")
writer.encrypt("mypassword")
writer.write("protected.pdf")

1
2

reader = PdfReader("document.pdf")
print(reader.metadata)

1
2
3
4
5
6
7
8

writer = PdfWriter()
writer.append("document.pdf")
writer.add_metadata({
    "/Title": "My Document",
    "/Author": "OpenClaw Agent",
    "/Subject": "PDF Manipulation"
})
writer.write("output.pdf")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

**references/troubleshooting.md**:

```markdown
# PDF Troubleshooting

## Common Errors

### "File not found"

**Cause**: Input file path is incorrect
**Solution**: Check file path with `ls -la`

### "PdfReadError: EOF marker not found"

**Cause**: PDF file is corrupted
**Solution**: 
1. Try re-downloading the PDF
2. Use `pdf_fix.py` to repair (if available)

### "Permission denied"

**Cause**: No write permission to output directory
**Solution**: 
1. Check directory permissions: `ls -la dirname`
2. Choose different output location

### "Password required"

**Cause**: PDF is password-protected
**Solution**: Use password parameter in scripts (see advanced.md)

1
2
3
4
5

# PDF Skill

## 所有 PDF 操作的详细说明

（这里写了 2000 行内容...）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# PDF Skill

## Quick Start

merge: `scripts/merge_pdfs.py output.pdf input1.pdf input2.pdf`
split: `scripts/split_pdf.py input.pdf output_dir/`

## Advanced Features

See [references/advanced.md](references/advanced.md)

1

description: "Work with PDF files"

1

description: "Comprehensive PDF manipulation. Use when working with PDF files for: (1) Merging PDFs, (2) Splitting PDFs, (3) Rotating pages, (4) Extracting text"

1
2
3

## Merging PDFs

You can use pypdf library to merge PDFs by creating a PdfWriter object and appending pages...

1
2
3
4

## Merge PDFs

```bash
scripts/merge_pdfs.py output.pdf input1.pdf input2.pdf

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

### 4. 明确边界（何时不用）

**每个 Skill 都应该有 "When NOT to Use" 部分**：

```markdown
## When NOT to Use

❌ **DON'T use this skill when:**

- Running one-off shell commands → use `exec` tool
- Starting new background processes → use `exec` with `background:true`
- The process isn't in tmux

1

## Workflow Decision Tree

1
2
3
4

## Advanced Features

- **Password-protected PDFs**: See [references/advanced.md](references/advanced.md)
- **Batch processing**: See [references/batch.md](references/batch.md)