refactor qmk-rgb skill: delegate to tool, no hardcoded effect catalog

.claude/skills/qmk-rgb/SKILL.md

@@ -1,165 +1,76 @@
 ---
 name: qmk-rgb
-description: "Explains how to control RGB lighting on QMK+VIA-compatible keyboards using qmk-rgb-tool. Covers zones, effects, colors, brightness, speed, and profiles."
+description: "Explains how to control RGB lighting on QMK+VIA-compatible keyboards. Delegates to qmk-rgb-tool for live command output and help."
 ---
 
 # /qmk-rgb
 
-Explains how to set up and control RGB lighting on QMK-compatible keyboards. Covers the `qmk-rgb-tool` CLI and what each command does.
+Explains how to control RGB lighting on QMK-compatible keyboards using `qmk-rgb-tool`.
 
 ## What this skill is for
 
-When a user asks about RGB lighting, effects, colors, brightness, zones, or profiles on a QMK keyboard — this skill provides the reference. It is the single source of truth for RGB commands, their parameters, effect catalogs, and expected behavior.
+When a user asks about RGB lighting, effects, colors, brightness, zones, profiles, or keyboard lighting in general — use this skill. Always delegate to the tool for live data and up-to-date help.
 
 ## Trigger
 
-When a user asks about RGB settings, effect names, color changes, brightness, zones, or keyboard lighting in general — use this skill. If `qmk-rgb-tool` is built and a keyboard is connected, run the command to verify. If not, explain what the command would do.
+Any RGB-related question about QMK keyboards, effects, colors, zones, brightness, profiles, or keyboard lighting.
 
-## Zone System
+## How to answer
 
-Every command targets one or more zones. The `--zone` flag selects which zone.
+### 1. First, get the tool's own help
 
-| Zone | CLI name | VIA channel | Effect IDs |
-|---|---|---:|---|
-| Logo | `logo` | 2 | 0–6 |
-| Backlight | `backlight` | 3 | 0–45 |
-| Side | `side` | 4 | 0–6 |
-
-**Default behavior** (no `--zone`): targets Logo, Backlight, and Side in that order.
-**With `--zone`**: targets exactly one zone. Unsupported zone effects or unknown zone names fail before the device opens. Default targets skip unsupported zones with a stderr warning.
-
-## Effect Families
-
-Logo and Side share this catalog:
-
-| ID | Name |
-|---:|---|
-| 0 | `none` |
-| 1 | `wave` |
-| 2 | `fixed_wave` |
-| 3 | `spectrum` |
-| 4 | `breathing` |
-| 5 | `light` |
-| 6 | `shutdown` |
-
-Backlight has the full catalog (46 effects, IDs 0–45):
-
-```
-none, solid_color, alphas_mods, gradient_up_down, gradient_left_right,
-breathing, band_sat, band_val, band_pinwheel_sat, band_pinwheel_val,
-band_spiral_sat, band_spiral_val, cycle_all, cycle_left_right,
-cycle_up_down, cycle_out_in, cycle_out_in_dual, rainbow_moving_chevron,
-cycle_pinwheel, cycle_spiral, dual_beacon, rainbow_beacon,
-rainbow_pinwheels, flower_blooming, raindrops, jellybean_raindrops,
-hue_breathing, hue_pendulum, hue_wave, pixel_flow, digital_rain,
-solid_reactive, solid_reactive_wide, solid_reactive_multiwide,
-solid_reactive_cross, solid_reactive_multicross, solid_reactive_nexus,
-solid_reactive_multinexus, splash, multisplash, solid_splash,
-solid_multisplash, starlight, starlight_dual_hue, starlight_dual_sat,
-riverflow
-```
-
-ID 39 = `multisplash`, ID 41 = `solid_multisplash`.
-
-## Effect Behavior
-
-| Category | Examples | Honors `color`? | Honors `speed`? |
-|---|---|---|---|
-| **Static** | `solid_color`, `none` | Yes (set color) | No |
-| **Reactive** | `solid_reactive*` | Yes | Yes (illumination duration) |
-| **Breathing** | `breathing`, `hue_breathing` | No (cycles hue) | Yes |
-| **Dynamic** | `band_*`, `cycle_*`, `rainbow_*`, `starlight*`, `raindrops`, `jellybean_raindrops`, `flower_blooming`, `pixel_flow`, `riverflow` | No (own palettes) | Yes |
-| **Splash** | `splash`, `multisplash`, `solid_splash`, `solid_multisplash` | `solid_*` yes | Yes |
-| **Gradient** | `gradient_up_down`, `gradient_left_right` | No | No |
-| **Alphas mods** | `alphas_mods` | No | No |
-
-## Aliases
-
-| Alias | Resolves to |
-|---|---|
-| `off` | `none` (any zone) |
-| `breathe` | `breathing` |
-| `rainbow` | `spectrum` (Logo/Side), `rainbow_moving_chevron` (Backlight) |
-| `rainbow_wave` | `wave` (Logo/Side) |
-| `solid` | `light` (Logo/Side), `solid_color` (Backlight) |
-| `static` | `solid` (legacy alias) |
-
-Aliases are resolved per-zone. `rainbow` means different effects on Logo vs Backlight.
-
-## Commands
-
-### Effect Control
-
-```bash
-qmk-rgb-tool effect <name>                    # Set effect on all zones
-qmk-rgb-tool effect <name> --zone backlight   # Set effect on one zone
-qmk-rgb-tool effect --list                    # List all effects (JSON)
-qmk-rgb-tool mode <id> --zone backlight       # Set by raw ID (zone-specific)
-```
-
-### Appearance
-
-```bash
-qmk-rgb-tool brightness <val>       # 0–255, default target: all zones
-qmk-rgb-tool speed <val>            # 0–255, effect animation speed
-qmk-rgb-tool color <hex>            # Six hex digits, e.g. ff0000
-```
-
-### Enable / Disable
+The tool is the single source of truth. Always start by fetching its output:
 
 ```bash
-qmk-rgb-tool enable                 # Enable selected zones
-qmk-rgb-tool disable                # Disable selected zones (all LEDs off)
+qmk-rgb-tool --help                           # Command structure
+qmk-rgb-tool effect --list                    # All available effects (JSON)
+qmk-rgb-tool keyboard info                    # Connected keyboards
+qmk-rgb-tool info                             # Current RGB state
 ```
 
-### Status
+Present the raw output to the user. Never duplicate documentation — the tool output is authoritative.
 
-```bash
-qmk-rgb-tool info                   # Show per-zone state (JSON)
-qmk-rgb-tool keyboard info          # Discover connected keyboards
-```
+### 2. If the tool is not built or no keyboard is connected
 
-### Profiles
+Explain what the command would do, then offer to build and run it:
+> The tool is not currently built. Would you like me to build it and run `qmk-rgb-tool effect --list` to see all available effects?
 
-```bash
-qmk-rgb-tool save <name>            # Save current state to profiles/<name>.json
-qmk-rgb-tool load <name>            # Load and apply a profile
-qmk-rgb-tool list                   # List saved profiles (JSON)
-qmk-rgb-tool delete <name>          # Delete a profile
-```
+### 3. When a user wants to change something
 
-## Profiles
+- Identify the zone: `logo`, `backlight`, or `side`
+- Ask for confirmation if the action will affect all zones
+- Run the command: `qmk-rgb-tool effect breathing --zone backlight`
+- Return the output
 
-Profiles store effect, brightness, speed, and color per zone as JSON files in `profiles/`. They are the only way to persist RGB settings across reboots (the keyboard's VIA protocol does not expose a command to save RGB state to internal EEPROM).
+### 4. Profiles
 
-## Device Flags
+Profiles are stored as JSON in `profiles/`. They persist RGB state across reboots.
 
 ```bash
-qmk-rgb-tool --device /dev/hidrawX enable   # Target specific HID device
+qmk-rgb-tool list       # List saved profiles
+qmk-rgb-tool save name  # Save current state
+qmk-rgb-tool load name  # Apply a profile
+qmk-rgb-tool delete name # Remove a profile
 ```
 
-Useful when multiple QMK keyboards are connected.
+## Zone behavior
 
-## How to Answer RGB Questions
+Without `--zone`, commands target Logo, Backlight, and Side in that order.
+With `--zone`, commands target exactly one zone.
 
-1. **Identify the zone** — ask or infer (logo, backlight, side). If ambiguous, explain per-zone behavior.
-2. **Identify the effect** — check if it's valid for that zone. Logo/Side only support 0–6. Backlight supports 0–45.
-3. **Check behavior** — static effects honor color, reactive effects honor both color and speed, breathing effects cycle hue, dynamic effects use their own palettes.
-4. **Run the command** if a keyboard is connected. Return the output.
-5. **Suggest a profile** if the user makes a complex configuration — saving it avoids losing it on reboot.
+Logo and Side support fewer effects (0–6). Backlight supports the full catalog (0–45). Always check `qmk-rgb-tool effect --list` to see what's available per zone.
 
-## Known Keyboards
+## Compatibility aliases
 
-| Keyboard | VID | PID | Notes |
-|---|---|---|---|
-| Wobkey Rainy 75 | 0x6666 | 0x0001 | Supported |
-| Wobkey Impact 80 | 0x36B0 | 0x309F | Supported |
+- `off` → `none`
+- `breathe` → `breathing`
+- `rainbow` → varies by zone (resolves automatically)
+- `solid` → varies by zone (resolves automatically)
 
-New keyboards can be added to `keyboards.json`.
+Aliases are zone-aware. `qmk-rgb-tool effect rainbow` means different effects on Logo vs Backlight.
 
-## Troubleshooting
+## Known limitations
 
-- **Command fails with "device not found"**: keyboard not connected, wrong VID/PID in `keyboards.json`, or needs udev permissions (Linux).
-- **Effect not applied on a zone**: effect ID valid only on Backlight (0–45), not Logo/Side (0–6). Use `--zone` to target the right zone.
-- **Profile load does nothing**: keyboard not connected at load time, or wrong device.
-- **Static effects not showing color**: use `solid_color` (Backlight) or `light` (Logo/Side), then set color. Static effects `none` and `solid_color`/`light` are the only ones that display a steady color.
+- Profiles save to files on disk, not to the keyboard's internal memory. Rebooting without a loaded profile reverts to the last saved RGB state.
+- Some effects are Backlight-only (IDs 7–45). Trying them on Logo/Side will fail before the device is opened.
+- On Linux, hidraw device permissions may be required (see `qmk-rgb-tool --help` for details).