hue

name	hue
description	Read and control Philips Hue Bridge lighting installations through local CLIP v2 or the Hue Remote API with SecretRef-backed credentials and guarded lighting changes.
user-invocable	true
requires	{"bins":["node"]}
config_variables	[{"id":"hue-bridge-host","env":"HUE_BRIDGE_HOST","required":true,"scope":"Local Hue Bridge HTTPS base URL used in gateway http_request URLs","how_to_obtain":"Find the bridge IP through the Hue app, router DHCP table, mDNS, or discovery.meethue.com, then store it in chat with `/env set HUE_BRIDGE_HOST \"https://<bridge-ip>\"`."}]
credentials	[{"id":"hue-application-key","kind":"api_key","required":true,"secret_ref":{"source":"store","id":"HUE_APPLICATION_KEY"},"scope":"Philips Hue CLIP v2 hue-application-key header","how_to_obtain":"Press the bridge link button, build the link request with `node skills/hue/hue.cjs --format json bridge link --app-name hybridclaw --instance-name lab`, and send its `httpRequest` through the gateway. Set the returned `HUE_APPLICATION_KEY` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set HUE_APPLICATION_KEY \"<application-key>\"` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set HUE_APPLICATION_KEY \"<application-key>\"`."},{"id":"hue-remote-refresh-token","kind":"bearer","required":false,"secret_ref":{"source":"store","id":"HUE_REMOTE_REFRESH_TOKEN"},"scope":"Hue Remote API OAuth token used for off-LAN API calls","how_to_obtain":"Create a Hue developer app and complete the Hue Remote API OAuth flow. Set `HUE_REMOTE_REFRESH_TOKEN` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set HUE_REMOTE_REFRESH_TOKEN \"<token>\"` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set HUE_REMOTE_REFRESH_TOKEN \"<token>\"`."},{"id":"hue-remote-access-token","kind":"bearer","required":false,"secret_ref":{"source":"store","id":"HUE_REMOTE_ACCESS_TOKEN"},"scope":"Hue Remote API short-lived access token used as Authorization bearer","how_to_obtain":"Run `node skills/hue/hue.cjs --format json remote oauth-token` after configuring the Remote API client id, client secret, and refresh token; the emitted gateway request captures the access token into `HUE_REMOTE_ACCESS_TOKEN`."}]
metadata	{"hybridclaw":{"category":"home-automation","short_description":"Philips Hue local CLIP v2 reads plus approval-gated light, group, scene, and automation control.","tags":["hue","philips-hue","smart-home","lighting","r21"],"related_roadmap":["R21.114","R48"],"issue":1118,"stakes_tiers":{"green":"[Truncated]","amber":"[Truncated]","red":"[Truncated]"},"escalation":{"writes":"confirm-each","route":"f14"},"cost_measurement":{"system":"UsageTotals","sub_limit_key":"hue"}}}

Philips Hue

Use this skill for Philips Hue Bridge lighting inspection and guarded control. The primary path is local HTTPS to the Hue Bridge CLIP v2 API. Use the Hue Remote API only when the operator explicitly needs off-LAN control or local bridge access is unavailable.

Safety Rules

1. Use skills/hue/hue.cjs for every supported Hue request shape. Do not handcraft CLIP v2 URLs or JSON bodies when the helper supports the action.
2. Read current light, room, zone, and scene state before changing lights.
3. Treat local reads as green, local light/group/scene/behavior changes as amber, off-LAN Remote API calls as amber, and bridge configuration writes as red.
4. For amber/red operations, use the helper to build the request shape, explain the target and expected effect, and stop for explicit operator approval before sending the emitted httpRequest through the gateway.
5. Include the target light, grouped light, room, scene, behavior, bridge id, action, and expected physical effect in approval text.
6. Never paste the Hue application key, OAuth client secret, or remote token into chat. The helper emits secretHeaders or <secret:...> placeholders for gateway-side resolution.
7. Hue Bridge certificates are self-signed by default. The helper marks local bridge HTTPS requests with a scoped allowSelfSignedTls flag for the gateway http_request proxy. Do not use a blanket insecure TLS bypass.
8. If a live call returns 401 or unauthorized_user, stop after that first failed call and re-link the bridge with the link-button flow.
9. In chat sessions, do not diagnose Hue runtime config by running hybridclaw env list, hybridclaw secret list, or other local CLI commands from bash; those commands can inspect the wrong runtime or fail because of the host Node version. Use gateway http_request errors and any /env show or /secret list output the operator provides.
10. If HUE_BRIDGE_HOST is configured and HUE_APPLICATION_KEY is missing, say only that the application key is missing. Do not ask the operator to find the bridge IP again. Ask them to press the physical link button, then build node skills/hue/hue.cjs --format json bridge link --app-name hybridclaw --instance-name lab, send the emitted httpRequest, and store the returned Hue credential secret through the helper-emitted captureResponseFields.