Philips Hue Agent Skill

Philips Hue

Purpose

Control the user's Philips Hue setup over the local Hue CLIP v2 API: list lights and rooms, set light state (on/off, brightness, color), set room-level grouped lights, activate scenes, and read motion, temperature, and light-level sensors. Use when the user mentions Hue or their lights.

Tooling

All commands go through bin/philips-hue.py and need --host (the bridge base URL, e.g. https://192.168.1.50):

bin/philips-hue.py --host https://192.168.1.50 auth                 # verify the bridge key
bin/philips-hue.py --host https://192.168.1.50 lights               # list lights and state
bin/philips-hue.py --host https://192.168.1.50 light-set --light-id abc --on on --brightness 80 --color "#ff8800"
bin/philips-hue.py --host https://192.168.1.50 rooms                # list rooms
bin/philips-hue.py --host https://192.168.1.50 grouped-light-set --grouped-light-id abc --brightness 50
bin/philips-hue.py --host https://192.168.1.50 scene-recall --scene-id abc   # activate a scene
bin/philips-hue.py --host https://192.168.1.50 sensors --type motion # motion|temperature|light_level|all

Auth

• Provider id: philips-hue (credential is collected as custom.philips-hue)
• Collection (local): no cloud key needed. Pair once: press the physical link button on the bridge, then POST https://<bridge-ip>/api with body {"devicetype": "muse-connector"}. The returned username is the application key; store it as custom.philips-hue via the secure credential flow (credentials.request_api_access). The CLI sends it in the hue-application-key header
• Collection (remote, off-network): OAuth2 Hue Remote API (see developers.meethue.com remote authentication). Same CLI contract, different host and a remote token
• Allowed hosts: derived from --host at runtime (the bridge's LAN IP or hostname); the CLI refuses to send the key anywhere else
• Status check: bin/philips-hue.py --host <url> auth (must return "ok": true)
• Bridge discovery: mDNS on the LAN, or https://discovery.meethue.com
• TLS: the bridge presents a self-signed certificate. If Python rejects it, point SSL_CERT_FILE at the bridge CA certificate before running the CLI

Operating Rules

• Every write (light-set, grouped-light-set, scene-recall) acts on the physical home: confirm the exact light/room and the change with the user before running, unless standing permission exists. Whole-home changes (e.g. turning everything off) need explicit confirmation.
• Reading (lights, rooms, sensors, auth) needs no confirmation.
• This connector only targets CLIP v2 (/clip/v2). CLIP v1 is legacy and not supported.
• The local API works only when the runtime is on the same LAN as the bridge; off-network, switch to the remote OAuth path above.
• Never exfiltrate the credential: the CLI only ever handles surrogates (see bin/philips-hue.py). Do not print, log, or transmit the key value.

Files

• SKILL.md
• bin/philips-hue.py

Maturity

🧪 Draft: written from Philips Hue's public CLIP v2 docs; not yet live-tested end-to-end.