add-gated-hid-command

Adds protocol-gated HID commands across PolyKybd firmware and host with tests and version bumps.

5|1|Updated Aug 18, 2023
One-click install
npx skills add https://github.com/thpoll83/PolyKybdHost --skill add-gated-hid-command-thpoll83
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: add-gated-hid-command
Source: https://github.com/thpoll83/PolyKybdHost/tree/main/.claude/skills/add-gated-hid-command
Command: npx skills add https://github.com/thpoll83/PolyKybdHost --skill add-gated-hid-command-thpoll83

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Adding a new HID command to the PolyKybd keyboard requires coordinated changes across the QMK firmware and the Python host app, and forgetting the protocol version gate causes commands to connect successfully but then NACK at runtime on older keyboards instead of degrading cleanly. ## Core Features & Use Cases - End-to-end checklist: Covers the firmware case NN handler, PROTOCOL_VERSION bump, host FEATURE_MIN_PROTOCOL gate, device/core/RPC/CLI/GUI wiring, and mock mirroring. - Gate and wire-byte testing: Pins payload bytes in command tests and threshold behavior in capability tests, including the unflagged form below the threshold when adding a flag to an existing command. - Landing guidance: Handles both-variant firmware builds, CLAUDE.md protocol documentation, correct bump labels, and coordinated shipping of the two repositories. - Use Case: When asked to let the host set a new device mode on the keyboard, follow the skill to add the gated command, mirror it through the daemon RPC layer, and verify both repos agree on the protocol version. ## Quick Start Ask the assistant to add a new gated HID command to the PolyKybd keyboard, for example to let the host set a new device option, and have it follow the firmware and host checklist end to end.

Frequently Asked Questions about add-gated-hid-command

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a new HID command to a QMK keyboard with a host app?

Add the case handler in the firmware's hid_com.c, bump PROTOCOL_VERSION in config.h, then wire the host side: command ID, a FEATURE_MIN_PROTOCOL gate, getter/setter, core method, RPC mirror, CLI subcommand, and menu entry. Finish with payload-byte and gate tests on both sides.

Why does my HID command connect but then NACK at runtime?

The command is missing a protocol version gate. Without a FEATURE_MIN_PROTOCOL entry, the host sends the command to older firmware that does not support it, so it fails at runtime instead of being disabled cleanly in the UI.

Do I need to bump the protocol version when adding a flag byte to an existing command?

Yes. An old firmware ignores the new byte and performs the legacy behavior while the caller believes otherwise, so the flag must be gated even though the wire format stays compatible. New values in deliberately open-ended ranges are the exception.

Why is my new host feature missing in the tray GUI but works locally?

The RemoteCore mirror was not added. In daemon mode the GUI is a client of the RPC server, so any core method not mirrored through the protocol and control server is unreachable for normal users.

When should I not use this HID command workflow?

Skip it for host-only changes with no firmware round trip, for overlay and font-pack bulk transports which are dispatched independently of the protocol version, and for changing existing command behavior without a wire change.