ha-websocket-command-add

HA WebSocket Command Add

Spec: spec/claude/ha-websocket-command-add/en.md (EN canonical) / spec/claude/ha-websocket-command-add/de.md (DE translation).

Why this is a skill, not an agent

• Human-visible augmentation surface — the user describes the data a card needs and reads back the handler, the schema, and the conformance report; a skill keeps this on the visible command surface, like the sibling augment skills (ha-config-flow-augment, ha-coordinator-add, ha-repairs-add).
• Mid-flow interactivity — the command-vs-service decision and the sync-vs-async choice are per-run dialogues the user approves before generation.
• Bounded, inline generation — one decorated handler plus its schema and the async_register_command call fit inline; no isolated agent context is needed.
• Counter-dimension considered: the draft→validate loop could be an agent, but the command-vs-service and admin-exposure decisions belong in the user's working context; skill wins.

When this skill activates

Use this skill to add one custom WebSocket API command to an existing integration — the backend endpoint a card or panel calls via hass.callWS(...) to load integration-specific data that is not a state attribute.

When NOT to activate

• a user-driven action / backend mutation with its own schema → ha-service-definition-add / ha/services
• the frontend consumer side (TypeScript typing, callWS error handling in the card) → ha/frontend-data-api
• a custom panel that consumes the command → ha-panel-add
• deploying/importing into a running HA instance → out of scope

Hard rules

1. One command, one run. No multi-command batches.
2. Read spec/ha/frontend-websocket-commands/en.md first. Do not generate from memory.
3. Command vs. service. Run the choice first: a data fetch into the frontend is a command; a user-driven action/mutation is a service. On action/mutation, point at ha-service-definition-add and abort.
4. Three-part contract. Declare type and schema via @websocket_api.websocket_command({...}) on a handler with signature (hass, connection, msg); namespace the type as vol.Required("type"): "<domain>/<name>" (docs example: "camera/get_thumbnail"); declare input fields via vol.Required/vol.Optional with a type annotation, kept minimal.
5. Sync vs. async. A pure in-memory handler is a synchronous function with @callback; a handler doing network/device/computation work is async def decorated with @websocket_api.async_response. Never run blocking I/O in a @callback handler.
6. Results and errors. Deliver success via connection.send_result(msg["id"], result) using the incoming msg["id"]; report errors via connection.send_error(msg["id"], "<code>", "<message>") instead of letting an exception propagate, and return after every send_error. Never substitute the msg["id"].
7. Admin restriction. Decorate admin-only commands with @websocket_api.require_admin; consider it for sensitive or integration-internal data. Never hand-roll admin checks in the handler body.
8. Register in setup. Register via websocket_api.async_register_command(hass, ws_handler) inside the integration's setup method (e.g. async_setup), not scattered across platform modules; do not require websocket_api as a manifest dependency.
9. Name per spec/ha/naming-conventions/en.md and verify HA internals against the official docs (see spec/ha/upstream-docs-verification/en.md).