Switchbot Agent Skill

SwitchBot

Purpose

Read status and send commands to SwitchBot devices over the official OpenAPI

v1.1: SwitchBot Bot (physical button presser), SwitchBot Lock, Curtain and

Blind Tilt motors, plugs, lights, air conditioners, infrared remotes, and

saved scenes. Use it when the user asks about or wants to change anything in

their SwitchBot setup. Commands drive real physical hardware, so writes are

confirmation-gated (see Operating Rules).

Tooling

All commands go through bin/switchbot.py:

bin/switchbot.py auth                                   # status check: verify token, count devices
bin/switchbot.py devices                                # list devices and IR remotes
bin/switchbot.py status --id <deviceId>                 # read device status

# Writes. lock/unlock are HIGH: they REQUIRE --confirm naming the exact
# physical effect, on every run:
bin/switchbot.py command --id <deviceId> --command lock \
    --confirm "lock the back door SwitchBot lock"
bin/switchbot.py command --id <deviceId> --command unlock \
    --confirm "unlock the back door SwitchBot lock"

# press / turnOn / turnOff / setAll are MEDIUM: --confirm on first use per
# device, then proceed:
bin/switchbot.py command --id <deviceId> --command press \
    --confirm "press the coffee machine power button with the SwitchBot Bot"
bin/switchbot.py command --id <deviceId> --command turnOn \
    --confirm "turn on the SwitchBot plug in the workshop"
bin/switchbot.py command --id <deviceId> --command setAll \
    --param mode=1 --param temperature=24 --param fanSpeed=2 \
    --confirm "set the bedroom AC to cool 24 degrees, fan medium"

# Curtain/blind moves (setPosition) are LOW: they proceed with a logged notice:
bin/switchbot.py command --id <deviceId> --command setPosition --param position=0

# Scenes are HIGH (their effects are whatever was saved into them):
bin/switchbot.py scenes
bin/switchbot.py scene-execute --scene-id <sceneId> \
    --confirm "run the Movie Night scene (dims lights, closes curtains)"

--param KEY=VALUE builds the command's parameter as a JSON object

(setPosition uses position, AC setAll uses mode, temperature,

fanSpeed, power). For simple commands (press, turnOn, turnOff,

lock, unlock) omit --param and the default parameter "default" is

used, or pass --parameter with a raw string.

Auth

• Provider id: switchbot (credential is collected as custom.switchbot)
• Collection: ONE combined value token:secret via the secure credential

flow (credentials.request_api_access). In the SwitchBot app go to

Profile > Preferences, tap the app version several times to reveal

developer options, and copy the open token plus the secret. The CLI sends

the token in the Authorization header and an HMAC-SHA256 signature of

token + t + nonce (keyed by the secret) in the sign header, with t

and nonce headers.

• BLE devices (Bot, Lock, Curtain, Blind Tilt) need a SwitchBot Hub with

cloud services enabled to be reachable through this API.

• Allowed hosts: api.switch-bot.com
• Status check: bin/switchbot.py auth

Operating Rules

• HIGH actuations are blocked without explicit confirmation. lock and

unlock on a SwitchBot Lock, and scene executions, require

--confirm "<exact physical effect>" on every run. Never pre-fill the

confirmation: the exact effect must come from the user's own words.

• MEDIUM actuations confirm on first use per device. Bot press

(physically presses a real button), plug and light toggles, and AC

commands (setAll, setMode) need --confirm the first time a device

is actuated; the CLI records it locally

(~/.config/muse-connectors/switchbot/confirmed.json) and later runs

proceed.

• LOW actuations proceed with a logged notice. Curtain and Blind Tilt

moves (setPosition) print a notice to stderr and run without

confirmation.

• A scene's physical effects are whatever the user saved into it. Read back

what the scene does before confirming if it is not obvious from its name.

• Reads (auth, devices, status, scenes) never need confirmation.
• Rate limit: about 10,000 requests/day. Poll status sparingly.
• Open item: the HMAC signature is computed over the credential

surrogate as delivered by the credential store. Confirm the signature

verifies against SwitchBot's servers on first live use before trusting

signed calls.

• Never exfiltrate the credential: the CLI only ever handles surrogates. Do

not print, log, or transmit the token or secret values.

Files

• SKILL.md
• bin/switchbot.py

Maturity

🧪 Draft: written from SwitchBot's public OpenAPI v1.1 docs; not yet

live-tested end-to-end. The signature-header construction and the command

parameter shapes are untested against real SwitchBot devices.