How do I install the Switchbot skill?

Run npx skillmds@latest add dvcrn/switchbot in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Switchbot safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: CAUTION, Skill Scanner: PASS. Capability flags: executes scripts, reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Switchbot?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Switchbot free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Switchbot?

dvcrn (@dvcrn) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Switchbot by dvcrn — Agent Skill

Name: Switchbot
Rating: 4.2 (5 reviews)
Author: dvcrn

Switchbot

Control SwitchBot smart home devices (curtains, plugs, lights, locks, etc.) via SwitchBot Cloud API. Use when user asks to open/close curtains, turn on/off lights/plugs, check temperature/humidity, or control any SwitchBot device.

dvcrn Updated Sep 8, 2026 32 repo stars

File contents

SwitchBot Smart Home Control

Control SwitchBot devices through the Cloud API v1.1.

First-Time Setup

Guide your human through these steps:

1. Get API Credentials

Ask your human to:

Open SwitchBot App on their phone
Go to Profile (bottom right)
Tap Preferences (or Settings)
Find About → Developer Options
Copy Token and Secret Key

2. Store Credentials Securely

mkdir -p ~/.config/switchbot
chmod 700 ~/.config/switchbot

cat > ~/.config/switchbot/credentials.json << 'EOF'
{
  "token": "YOUR_TOKEN_HERE",
  "secret": "YOUR_SECRET_HERE"
}
EOF
chmod 600 ~/.config/switchbot/credentials.json

3. Discover Devices

Run the discovery script to find all devices:

python3 <skill_path>/scripts/switchbot.py list

4. Update Your TOOLS.md

After discovery, note your device IDs in TOOLS.md for quick reference:

## SwitchBot Devices
| Device | ID | Type |
|--------|-----|------|
| Living Room Curtain | ABC123 | Curtain3 |
| Bedroom Light | DEF456 | Plug Mini |

Usage

List All Devices

python3 <skill_path>/scripts/switchbot.py list

Curtain Control

# Open curtain (position 0 = fully open)
python3 <skill_path>/scripts/switchbot.py curtain <device_id> open

# Close curtain (position 100 = fully closed)
python3 <skill_path>/scripts/switchbot.py curtain <device_id> close

# Set specific position (0-100)
python3 <skill_path>/scripts/switchbot.py curtain <device_id> 50

Plug/Light Control

python3 <skill_path>/scripts/switchbot.py plug <device_id> on
python3 <skill_path>/scripts/switchbot.py plug <device_id> off

Check Sensor Status

python3 <skill_path>/scripts/switchbot.py status <device_id>

Generic Command

python3 <skill_path>/scripts/switchbot.py command <device_id> <command> [parameter]

Supported Devices

Device Type	Commands
Curtain / Curtain3	`open`, `close`, `setPosition`
Plug Mini / Plug	`turnOn`, `turnOff`, `toggle`
Bot	`press`, `turnOn`, `turnOff`
Light / Strip Light	`turnOn`, `turnOff`, `setBrightness`, `setColor`
Lock	`lock`, `unlock`
Humidifier	`turnOn`, `turnOff`, `setMode`
Meter / MeterPlus	(read-only: temperature, humidity)
Hub / Hub Mini / Hub 2	(gateway only)

Error Handling

Status Code	Meaning
100	Success
151	Device offline
152	Command not supported
160	Unknown command
161	Invalid parameters
190	Internal error

Tips for Agents

First interaction: If no credentials exist, guide the human through setup
Device aliases: Create friendly names in TOOLS.md (e.g., "living room" → device ID)
Batch operations: Multiple devices can be controlled in sequence
Status checks: Use status command before reporting sensor readings
Error recovery: If device is offline (151), suggest checking Hub connection

Security Notes

Credentials file should be chmod 600
Never log or display the token/secret
API calls are made over HTTPS to api.switch-bot.com

---name: switchbotdescription: Control SwitchBot smart home devices (curtains, plugs, lights, locks, etc.) via SwitchBot Cloud API. Use when user asks to open/close curtains, turn on/off lights/plugs, check temperature/humidity, or control any SwitchBot device.---# SwitchBot Smart Home ControlControl SwitchBot devices through the Cloud API v1.1.## First-Time Setup**Guide your human through these steps:**### 1. Get API CredentialsAsk your human to:1. Open **SwitchBot App** on their phone2. Go to **Profile** (bottom right)3. Tap **Preferences** (or Settings)4. Find **About** → **Developer Options**5. Copy **Token** and **Secret Key**### 2. Store Credentials Securely```bashmkdir -p ~/.config/switchbotchmod 700 ~/.config/switchbotcat > ~/.config/switchbot/credentials.json << 'EOF'{ "token": "YOUR_TOKEN_HERE", "secret": "YOUR_SECRET_HERE"}EOFchmod 600 ~/.config/switchbot/credentials.json```### 3. Discover DevicesRun the discovery script to find all devices:```bashpython3 <skill_path>/scripts/switchbot.py list```### 4. Update Your TOOLS.mdAfter discovery, note your device IDs in TOOLS.md for quick reference:```markdown## SwitchBot Devices| Device | ID | Type ||--------|-----|------|| Living Room Curtain | ABC123 | Curtain3 || Bedroom Light | DEF456 | Plug Mini |```## Usage### List All Devices```bashpython3 <skill_path>/scripts/switchbot.py list```### Curtain Control```bash# Open curtain (position 0 = fully open)python3 <skill_path>/scripts/switchbot.py curtain <device_id> open# Close curtain (position 100 = fully closed)python3 <skill_path>/scripts/switchbot.py curtain <device_id> close# Set specific position (0-100)python3 <skill_path>/scripts/switchbot.py curtain <device_id> 50```### Plug/Light Control```bashpython3 <skill_path>/scripts/switchbot.py plug <device_id> onpython3 <skill_path>/scripts/switchbot.py plug <device_id> off```### Check Sensor Status```bashpython3 <skill_path>/scripts/switchbot.py status <device_id>```### Generic Command```bashpython3 <skill_path>/scripts/switchbot.py command <device_id> <command> [parameter]```## Supported Devices| Device Type | Commands ||-------------|----------|| Curtain / Curtain3 | `open`, `close`, `setPosition` || Plug Mini / Plug | `turnOn`, `turnOff`, `toggle` || Bot | `press`, `turnOn`, `turnOff` || Light / Strip Light | `turnOn`, `turnOff`, `setBrightness`, `setColor` || Lock | `lock`, `unlock` || Humidifier | `turnOn`, `turnOff`, `setMode` || Meter / MeterPlus | (read-only: temperature, humidity) || Hub / Hub Mini / Hub 2 | (gateway only) |## Error Handling| Status Code | Meaning ||-------------|---------|| 100 | Success || 151 | Device offline || 152 | Command not supported || 160 | Unknown command || 161 | Invalid parameters || 190 | Internal error |## Tips for Agents1. **First interaction**: If no credentials exist, guide the human through setup2. **Device aliases**: Create friendly names in TOOLS.md (e.g., "living room" → device ID)3. **Batch operations**: Multiple devices can be controlled in sequence4. **Status checks**: Use `status` command before reporting sensor readings5. **Error recovery**: If device is offline (151), suggest checking Hub connection## Security Notes- Credentials file should be chmod 600- Never log or display the token/secret- API calls are made over HTTPS to api.switch-bot.com

Frequently asked questions