# Hue > 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. - Skill: `hybridaione/hue` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add hybridaione/hue` - Raw SKILL.md: https://api.skillmd.com/api/skills/hybridaione/hue/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: HybridAIOne (https://skillmd.com/u/hybridaione) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/hybridaione/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 `` 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`. 11. When linking after the operator presses the bridge button, run `bridge status` first. If the live status result reports `linkbutton: true`, immediately run `bridge link` without `--host`. If it reports `linkbutton: false`, tell the operator that the configured bridge did not report an active button press and ask them to press and release the physical link button once, then retry immediately. If `linkbutton` is absent, do not treat that as proof the button is inactive; modern bridge config responses can omit the field. 12. When running the link request itself, do not pass `--host` unless the operator explicitly provides a new override URL in the same turn. The default link request must use `` so the gateway resolves the env-store value. 13. If the operator shows `/env show HUE_BRIDGE_HOST`, treat that value as the current configured bridge URL. If a failed request used any other host, report that the helper was called with the wrong host and retry the same operation with no `--host` override. 14. If `HUE_BRIDGE_HOST` is missing, first reuse an exact Hue Bridge URL from current context or workspace memory when one is present. Ask the operator to find the bridge IP only when no exact URL is available. 15. If a gateway `http_request` error says `Stored secret HUE_APPLICATION_KEY is not set`, treat `HUE_BRIDGE_HOST` as already resolved for that request. Do not say the bridge host may be missing, do not tell the operator to run `hybridclaw env set`, and do not repeat the same read calls. Switch directly to the link-button setup path in rule 10. 16. If a private-host or gateway policy denial blocks a local bridge request, first inspect the current workspace network policy. Managed read-only LAN access already allows GET reads to RFC1918 hosts, and managed read-write LAN access allows the supported methods. If either managed LAN mode covers the attempted Hue request, report that mismatch as a gateway policy-evaluation bug instead of adding another rule. Do not edit policy by hand, do not add broad bridge rules, and do not tell the operator a gateway restart is required; workspace network policy is read per request. 17. If a local Hue request fails with a certificate verification or self-signed TLS error, do not ask for `HUE_BRIDGE_HOST` again, do not suggest plain HTTP on port 80, and do not invent a URL auth route or workspace policy setting for TLS. Re-run the exact helper-emitted `httpRequest` with `allowSelfSignedTls: true`; if that field is absent, rebuild the request with `skills/hue/hue.cjs`. ## Command Contract The helper is deliberately thin: it only turns clean subject/verb arguments into gateway-ready `httpRequest` payloads. It does not write env values, edit network policy, call the gateway, poll the bridge, or store secrets. Show helper usage: ```bash node skills/hue/hue.cjs --help ``` Build local CLIP v2 read requests, then pass the emitted `httpRequest` object to the gateway `http_request` tool: ```bash node skills/hue/hue.cjs --format json bridge list node skills/hue/hue.cjs --format json device list node skills/hue/hue.cjs --format json light list node skills/hue/hue.cjs --format json grouped-light list node skills/hue/hue.cjs --format json room list node skills/hue/hue.cjs --format json zone list node skills/hue/hue.cjs --format json scene list node skills/hue/hue.cjs --format json motion list node skills/hue/hue.cjs --format json behavior list node skills/hue/hue.cjs --format json entertainment list ``` Read a bounded diagnostic eventstream window: ```bash node skills/hue/hue.cjs --format json eventstream read --duration 30s ``` Prepare guarded write operations: ```bash node skills/hue/hue.cjs --format json light on --id node skills/hue/hue.cjs --format json light off --id node skills/hue/hue.cjs --format json light brightness --id --pct 60 node skills/hue/hue.cjs --format json light color --id --xy 0.4317,0.4147 node skills/hue/hue.cjs --format json light color --id --mirek 366 node skills/hue/hue.cjs --format json grouped-light on --id node skills/hue/hue.cjs --format json grouped-light brightness --id --pct 60 node skills/hue/hue.cjs --format json scene recall --id node skills/hue/hue.cjs --format json behavior disable --id node skills/hue/hue.cjs --format json bridge timezone --id --timezone Europe/Berlin ``` The helper marks amber and red operations with `requiredGrant`. Send the emitted `httpRequest` only after the operator approves the described effect. Link a bridge after pressing the physical link button: ```bash node skills/hue/hue.cjs --format json bridge status node skills/hue/hue.cjs --format json bridge link \ --app-name hybridclaw \ --instance-name lab ``` The status command emits a `/api/config` request shape with `` and no secret header. Use it to confirm the configured bridge reports `linkbutton: true` before sending the link request. The link command emits a single `/api` request shape with `` and only a `devicetype` body. Send that request through the gateway while the button is active, then store the returned Hue credential secret as `HUE_APPLICATION_KEY` through the emitted `captureResponseFields`. Do not pass `--host` for normal chat setup. Use Remote API reads only when off-LAN access is needed: ```bash node skills/hue/hue.cjs --format json remote oauth-token node skills/hue/hue.cjs --format json remote bridge list node skills/hue/hue.cjs --format json remote light list --bridge node skills/hue/hue.cjs --format json remote room list --bridge ``` ## Setup Store the local bridge URL in the env store, then press the bridge link button, build the link request, send the emitted `httpRequest` through the gateway, and let the gateway capture the returned Hue credential secret as the application key. In chat: ```text /env set HUE_BRIDGE_HOST "https://" node skills/hue/hue.cjs --format json bridge status node skills/hue/hue.cjs --format json bridge link --app-name hybridclaw --instance-name lab ``` From a local terminal: ```bash hybridclaw env set HUE_BRIDGE_HOST "https://" node skills/hue/hue.cjs --format json bridge status node skills/hue/hue.cjs --format json bridge link --app-name hybridclaw --instance-name lab ``` Managed LAN HTTP access covers local RFC1918 bridge reads according to the workspace policy setting. The helper does not create or modify that setting. For the Hue Remote API, create a developer app, complete the OAuth flow, then set the resulting values in this order: 1. Browser admin: open the active HybridClaw admin URL ending in `/admin/secrets` and set the `HUE_REMOTE_*` secrets. 2. Browser `/chat` or TUI fallback: ```text /secret set HUE_REMOTE_CLIENT_ID "" /secret set HUE_REMOTE_CLIENT_SECRET "" /secret set HUE_REMOTE_REFRESH_TOKEN "" node skills/hue/hue.cjs --format json remote oauth-token /secret set HUE_REMOTE_BRIDGE_ID "" ``` 3. Local console fallback: ```bash hybridclaw secret set HUE_REMOTE_CLIENT_ID "" hybridclaw secret set HUE_REMOTE_CLIENT_SECRET "" hybridclaw secret set HUE_REMOTE_REFRESH_TOKEN "" node skills/hue/hue.cjs --format json remote oauth-token hybridclaw secret set HUE_REMOTE_BRIDGE_ID "" ``` ## Resource Coverage The helper allowlists the initial CLIP v2 resource set from the OpenHue OpenAPI contract and Philips Hue CLIP v2 docs: `bridge`, `device`, `light`, `grouped_light`, `room`, `zone`, `scene`, `motion`, `temperature`, `light_level`, `button`, `behavior_instance`, and `entertainment_configuration`. Arbitrary `/clip/v2/resource/` passthrough is rejected. ## Result Handling - Base answers on successful live Hue API results from the current turn. - For scene recall, expect `recall: { action: "active" }`. - For light/group color, use either XY coordinates or mirek color temperature, not both. - Eventstream output can reveal occupancy. Keep diagnostic reads short and do not create a long-lived subscription from this skill. - On gateway policy denial for a local bridge, inspect the current workspace network policy first. If managed read-only LAN access covers the GET read, or managed read-write LAN access covers the attempted method, report a gateway policy-evaluation bug and do not add a duplicate bridge rule. If LAN access is off, tell the operator which LAN HTTP access setting is missing. Do not tell the operator to restart the gateway. - If policy denial persists despite a matching managed LAN setting, report the helper-emitted host, method, and path. Do not substitute Remote API results unless the operator asks for off-LAN fallback. - On certificate verification or self-signed TLS failures for local Hue HTTPS, explain that the request must include the helper's `allowSelfSignedTls: true` field and retry once with the helper-emitted request. Do not ask whether the bridge supports plain HTTP, do not ask for the bridge host again, and do not claim a gateway TLS route or workspace policy is required. - On missing Hue configuration, report exactly which configured names are present and which are missing. If the gateway says `Stored secret HUE_APPLICATION_KEY is not set`, do not say `HUE_BRIDGE_HOST` is unknown or missing; the `` placeholder already resolved far enough to reach secret-header injection. In chat, give only this slash-command recovery path: ```text Press the Hue bridge link button, then let me run: node skills/hue/hue.cjs --format json bridge status node skills/hue/hue.cjs --format json bridge link --app-name hybridclaw --instance-name lab The emitted `captureResponseFields` rule captures the returned Hue credential secret into `HUE_APPLICATION_KEY`. ``` Do not include `hybridclaw env set` or ask the operator to set `HUE_BRIDGE_HOST` again unless the gateway explicitly reports that `HUE_BRIDGE_HOST` itself is missing. - On a live link response from `/api` with Hue error `type: 101` or description `link button not pressed`, run `bridge status` once in the current button window. If status reports `linkbutton: true`, retry `bridge link` immediately. If status reports `linkbutton: false`, explain that the bridge at the configured env-store host is reachable but does not currently report an active button press; ask the operator to press and release the physical button once, then retry the status and link sequence immediately. If status omits `linkbutton`, explain that the bridge status endpoint did not expose button state and retry the `/api` link request only when the operator confirms the button was just pressed. - On a live link response saying `generateclientkey is not available` or directing the caller to `POST /api/config/connections`, rebuild the request with the current helper and retry the emitted `/api` request. The helper must not send `generateclientkey`; it should send only `devicetype`. - On a live link response from `/api/config/connections` with Hue error `type: 1`, address `/connections`, or description `unauthorized user`, do not claim the button window expired. That endpoint requires an existing authorized user on this bridge. Rebuild with the current helper and use the unauthenticated `/api` link request without `generateclientkey`. - If the operator shows `/env show HUE_BRIDGE_HOST` and it differs from the host used by a failed request, explain that the request used the wrong override and retry with the normal helper command, which emits ``.