add qmk-rgb skill: reference for QMK keyboard RGB control

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

@@ -0,0 +1,165 @@
+---
+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."
+---
+
+# /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.
+
+## 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.
+
+## 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.
+
+## Zone System
+
+Every command targets one or more zones. The `--zone` flag selects which zone.
+
+| 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
+
+```bash
+qmk-rgb-tool enable                 # Enable selected zones
+qmk-rgb-tool disable                # Disable selected zones (all LEDs off)
+```
+
+### Status
+
+```bash
+qmk-rgb-tool info                   # Show per-zone state (JSON)
+qmk-rgb-tool keyboard info          # Discover connected keyboards
+```
+
+### Profiles
+
+```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
+```
+
+## Profiles
+
+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).
+
+## Device Flags
+
+```bash
+qmk-rgb-tool --device /dev/hidrawX enable   # Target specific HID device
+```
+
+Useful when multiple QMK keyboards are connected.
+
+## How to Answer RGB Questions
+
+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.
+
+## Known Keyboards
+
+| Keyboard | VID | PID | Notes |
+|---|---|---|---|
+| Wobkey Rainy 75 | 0x6666 | 0x0001 | Supported |
+| Wobkey Impact 80 | 0x36B0 | 0x309F | Supported |
+
+New keyboards can be added to `keyboards.json`.
+
+## Troubleshooting
+
+- **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.