hue

Files (2)

• SKILL.md
• hue.cjs

SKILL.md (first lines)

# 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`.
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 `<env:HUE_BRIDGE_HOST>` 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 <id>
node skills/hue/hue.cjs --format json light off --id <id>
node skills/hue/hue.cjs --format json light brightness --id <id> --pct 60

From HybridAIOne/hybridclaw, MIT.

More from HybridAIOne/hybridclaw