Claw Keyboard

Control keyboard RGB backlight, custom LEDs, macros, key mapping, and profile settings via USB HID. Use when the user asks to control keyboard lighting, mana...

Security Scan

The skill's requirements and instructions align with its stated purpose (controlling USB keyboard lighting, macros, and keymaps), but pay attention to its binary install method (GitHub 'latest' downloads) and the destructive commands it can run.

Purpose & Capability

The skill is an instruction-only wrapper around a native binary named 'claw-keyboard' and claims to control USB HID keyboards (RGB, macros, keymap, profiles). Requiring the 'claw-keyboard' binary is coherent with that purpose; no unrelated credentials, files, or services are requested.

Instruction Scope

SKILL.md lists only commands for discovering and controlling keyboards (rgb, led, keymap, macro, profile, KLE render). It explicitly marks destructive operations (factory reset, overwriting keymaps/macros) as requiring explicit user confirmation and warns not to run them autonomously. The instructions do not request environment variables or access to unrelated system files.

Install Mechanism

The SKILL.md includes download-based install entries pointing to GitHub Releases (good: a well-known host). However the URLs use the 'latest' release path, which is mutable and increases supply-chain risk compared with pinned versioned releases and checksums. Also, registry metadata indicated 'No install spec' while SKILL.md contains install entries — this mismatch should be clarified.

Credentials

No environment variables, credentials, or unrelated config paths are requested. The skill's access needs (direct USB HID interaction via the binary) are proportional to controlling a keyboard.

Persistence & Privilege

The skill is not always-enabled and is user-invocable. Model invocation is allowed (normal platform default), but because the skill can perform destructive hardware actions, you should rely on the SKILL.md requirement for explicit user confirmation. If you do not want any chance of autonomous hardware modification, consider disabling autonomous invocation for this skill at install-time.

Assessment

This skill appears to do what it says (control USB keyboards) and only needs the 'claw-keyboard' binary. Before installing, verify the binary's provenance: prefer a release pinned to a specific version and verify checksums if available rather than using the 'latest' download links in SKILL.md. Inspect the upstream GitHub repo (https://github.com/clawdevice/claw-keyboard) and release artifacts; avoid running the binary as an administrator/root user if possible. Be cautious about destructive commands (factory reset, write keymap, erase macros) — the skill’s docs say they require explicit confirmation, but you should still only run them yourself. Finally, clarify the mismatch between the registry metadata (which said no install spec) and the SKILL.md install entries; if you want to eliminate autonomous risk, disable model/autonomous invocation so the agent cannot run hardware-modifying commands without your approval.

Use claw-keyboard to discover and control USB keyboards that support the vendor HID protocol (UsagePage 0xFF60, Usage 0x61). Tested with LUXSWH R68pro. Supports RGB backlight, custom per-key LEDs, macros, key remapping, profile tuning, KLE layout rendering, and multi-keyboard management.

Quick start

• claw-keyboard discover — scan for connected keyboards
• claw-keyboard info — show keyboard details (rows, cols, firmware, mode, RGB state)
• claw-keyboard rgb color red — set backlight to red
• claw-keyboard rgb brightness 128 — set brightness (0-255)
• claw-keyboard rgb effect 1 — set lighting effect mode (0-20)
• claw-keyboard rgb save — persist current settings to flash

Device selection

When multiple keyboards are connected, use --device <path> to target a specific one. Run discover to list available paths.

RGB control

• claw-keyboard rgb status — show current brightness, effect, speed, color
• claw-keyboard rgb color <name|hue> — set color by name (red, green, blue, cyan, purple, orange, yellow, white) or hue value (0-255)
• claw-keyboard rgb brightness <0-255> — set LED brightness
• claw-keyboard rgb effect <0-20> — set lighting effect mode (0 = rainbow, 1 = solid, 2-20 = animations)
• claw-keyboard rgb speed <0-5> — set animation speed (0 = slowest, 5 = fastest)
• claw-keyboard rgb save — write current config to flash (avoid frequent calls — flash has limited write cycles)

Custom LED control

• claw-keyboard led on <row> <col> — turn on a single LED at row/col position
• claw-keyboard led off <row> <col> — turn off a single LED
• claw-keyboard led clear — turn off all LEDs
• claw-keyboard led list — list currently lit LED positions
• claw-keyboard led sync-start — start onboard LED effect sync (keyboard reports LED data to PC)
• claw-keyboard led sync-stop — stop onboard LED effect sync

Key mapping

• claw-keyboard keymap read — dump current key layout (all layers)
• claw-keyboard keymap layers — show number of supported layers
• claw-keyboard keymap get <layer> <row> <col> — read the 2-byte HID key value at a position
• claw-keyboard keymap set <layer> <row> <col> <keyvalue> — set a single key (4-digit hex, e.g. 0029 = Escape). Requires user confirmation — this changes a physical key binding on the keyboard.
• claw-keyboard keymap write <file> — write complete keymap from hex file. Requires user confirmation — this overwrites all key bindings.

Macro management

• claw-keyboard macro list — show macro count, storage usage, and parsed macros
• claw-keyboard macro clear — erase all macros. Requires user confirmation — this deletes all macros permanently.
• claw-keyboard macro dump — hex dump of raw macro storage data
• claw-keyboard macro set <actions> [<actions>...] — configure macros from action strings (replaces all existing macros). Requires user confirmation.
  • Action format: tap:<keycode>, press:<keycode>, release:<keycode>, delay:<ms> separated by commas
  • Example: claw-keyboard macro set "press:0xE0,tap:0x06,release:0xE0" (Ctrl+C)

Profile parameters

• claw-keyboard profile get — read profile parameters (debounce, TAP layer, sleep, power-down)
• claw-keyboard profile set — configure profile parameters (use --debounce, --tap, --sleep, --powerdown flags)

KLE layout tools

• claw-keyboard kle info <file.json> — show parsed KLE layout summary
• claw-keyboard kle render <file.json> — render KLE JSON layout to SVG

Other

• claw-keyboard reset — factory reset keyboard. Requires explicit user confirmation — this permanently erases all settings, key mappings, and macros from the keyboard, restoring it to factory defaults. Only run when the user explicitly requests a factory reset.

Safety

The following commands modify keyboard hardware state and should only be run with explicit user confirmation. Never run these autonomously:

• reset — factory reset (irreversible, erases everything)
• macro clear / macro set — erases or replaces all macros
• keymap set / keymap write — changes key bindings
• rgb save — writes to flash (limited write cycles)

Read-only commands (discover, info, rgb status, keymap read, macro list, profile get, kle info) are always safe to run.

Notes

• The tool auto-discovers keyboards by scanning for HID interfaces with UsagePage 0xFF60 and Usage 0x61, then verifying via a challenge-response handshake.
• Not all keyboards expose the vendor HID interface. If discover finds nothing, the keyboard may not support this protocol.
• On macOS, you may need to grant HID access permission to the terminal application in System Settings > Privacy & Security > Input Monitoring.
• On Linux, you may need udev rules to access USB HID devices without root. Create /etc/udev/rules.d/99-claw-keyboard.rules with SUBSYSTEM=="hidraw", ATTRS{idVendor}=="1a86", MODE="0666" and run sudo udevadm control --reload-rules.
• SHA256 checksums for all binaries are available in the SHA256SUMS file on the GitHub Releases page. Verify after downloading: shasum -a 256 -c SHA256SUMS.
• Use --json flag for machine-readable output.