home-services/.claude/skills/switchbot-control/SKILL.md

name, description

name	description
switchbot-control	Gated SwitchBot Cloud device control via the local reference CLI (tmp/reference/switchbot-control-reference) — turn-on/off, fan/AC/lock commands, and custom IR buttons. Always resolves and inspects the target first, always dry-runs before a real send, always requires explicit user approval before executing.

SwitchBot Control (gated)

This wraps tmp/reference/switchbot-control-reference/scripts/switchbotctl, the full control CLI. Every real control call fires a real signal at real hardware (an actual IR blast, an actual lock toggle) — treat every non-dry-run invocation as something you are asking permission to do, not something you just do.

Required sequence, every time

1. Resolve the device. Use the switchbot-read skill (list all / list remotes / list switches / list locks) to find the exact deviceId for the device the user named. Never guess an ID or reuse one from memory without re-confirming it still matches — if more than one device could match the name, ask which one; never pick one silently.
2. Inspect the interface. Run switchbot-read interface DEVICE_ID and confirm the command you're about to send is actually in its documented commands list (or, for a custom button, that the device is an infrared remote where customize-type commands apply).
3. Dry-run first. Always construct and check the exact call with --dry-run before ever running it for real:

   cd tmp/reference/switchbot-control-reference
   GOWORK=off ./scripts/switchbotctl ac DEVICE_ID 24 cool medium on --dry-run
   

   Confirm the echoed command/parameter/commandType in the dry-run output is exactly what you intend.
4. Ask for explicit approval before running the same command without --dry-run. State the exact device (name + ID) and the exact action in plain language. Do not treat a general "go ahead with the plan" from earlier in the conversation as approval for a specific real control call — ask again, per command, right before running it.
5. Execute once. Run the approved command exactly once. Do not retry automatically on failure or on an ambiguous result — a repeated lock, toggle, Bot press, or custom IR command can produce a real second action (e.g. re-toggling something back off). If it needs retrying, ask first.
6. Treat success as API acceptance, not physical confirmation. SwitchBot Cloud's infrared control is fire-and-forget — a 200/statusCode: 100 response means the cloud accepted the command, not that the appliance actually received or acted on the IR signal.

Custom IR buttons (button) need the user, not a guess

GOWORK=off ./scripts/switchbotctl button DEVICE_ID "Exact Button Name" --dry-run

SwitchBot's API cannot enumerate a device's learned custom button names — they only exist as case-sensitive labels in the SwitchBot app. Never approximate, guess, or case-fold a button name. If you don't have the exact label from the user, stop and ask for it rather than trying a plausible guess.

Command reference (see tmp/reference/switchbot-control-reference/README.md for the full list)

switchbotctl turn-on DEVICE_ID [--dry-run]
switchbotctl turn-off DEVICE_ID [--dry-run]
switchbotctl press DEVICE_ID [--dry-run]
switchbotctl lock DEVICE_ID [--dry-run]
switchbotctl unlock DEVICE_ID [--dry-run]
switchbotctl fan DEVICE_ID swing|timer|lowSpeed|middleSpeed|highSpeed [--dry-run]
switchbotctl ac DEVICE_ID TEMPERATURE MODE FAN_SPEED POWER [--dry-run]
switchbotctl button DEVICE_ID "Exact Button Name" [--dry-run]
switchbotctl send DEVICE_ID COMMAND PARAMETER COMMAND_TYPE [--dry-run]   # generic escape hatch

Always run from tmp/reference/switchbot-control-reference/ with GOWORK=off prefixed (this repo's root go.work doesn't include this nested module — see the switchbot-read skill for why not to fix that by editing go.work).

Hard rules

• Never read, print, edit, source, or expose .env in this directory.
• Never add an automatic hook, cron, or script that calls switchbotctl without a human in the loop for that specific invocation.
• This CLI is a development/testing aid only — it is not a dependency of ha-gateway. The actual RemoteService implementation in ha-gateway has its own hand-rolled SwitchBot HTTP client (see plan.md); use this CLI to discover device IDs and verify command behavior during development, not as something the running services call at runtime.