docs(skills): give each request one skill to load, in one short line

AGENTS.md

@@ -32,7 +32,9 @@ Working rules for this repository (the public release directory for hass-cli).
   `SupervisorToken` is parsed but reserved (not yet wired); the Supervisor
   proxy path uses `HASS_TOKEN`.
 - `internal/output/` — table/json/yaml/ndjson rendering with `--columns`/`--sort-by`.
-- `skills/` — agent skills (`ha-shared` first), embedded into the binary.
+- `skills/` — agent skills, embedded into the binary. Each control skill carries
+  its own two-command quick control; `ha-shared` holds connection and error
+  recovery. Descriptions are one short sentence: every agent request lists them.
 
 ## Conventions
 

skills/ha-assist/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ha-assist
-version: 0.1.0
-description: "Use Home Assistant's Assist voice/conversation layer with hass-cli: send a natural-language command to the conversation agent, list conversation agents and assist pipelines, list STT/TTS engines and voices, and speak text on a media player. Use for 'tell Assist to turn off the lights', 'what voice assistants are configured', 'run a sentence through HA' requests."
+version: 0.2.0
+description: "Manage Home Assistant's own Assist: send text to its conversation agent, list agents, pipelines and STT/TTS engines. Not for direct device control."
 metadata:
   requires:
     bins: ["hass-cli"]
@@ -10,13 +10,13 @@ metadata:
 
 # ha-assist
 
-Conversation, pipelines, STT/TTS. **Prerequisite:**
-[`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
+Conversation, pipelines, STT/TTS. Connection or auth trouble: [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
 
 ## Send a natural-language command
 
-The conversation agent maps a sentence to actions — a quick way to control HA
-by intent instead of crafting a `service call`:
+Home Assistant's own conversation agent maps a sentence to actions. Use it when
+the user asks for Assist itself; for direct device control the domain skills'
+`service call` is faster and reports what changed:
 
 ```bash
 hass-cli raw ws conversation/process --data '{"text":"turn off the kitchen lights"}' -o json

skills/ha-automation/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ha-automation
-version: 0.1.0
-description: "Create, edit, and run Home Assistant automations, scripts, and scenes with hass-cli. Use to list/get/save/delete automations, reload them, trigger them manually, or build a new automation from triggers/conditions/actions. Config writes go through the REST config editor; reload/trigger go through services."
+version: 0.2.0
+description: "List, create, edit, run and delete automations, scripts and scenes."
 metadata:
   requires:
     bins: ["hass-cli"]
@@ -10,8 +10,7 @@ metadata:
 
 # ha-automation
 
-Manage automations, scripts, and scenes. **Prerequisite:**
-[`../ha-shared/SKILL.md`](../ha-shared/SKILL.md). To author a NEW automation from
+Manage automations, scripts, and scenes. Connection or auth trouble: [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md). To author a NEW automation from
 a request, follow [`../ha-workflow-automation-builder/SKILL.md`](../ha-workflow-automation-builder/SKILL.md).
 
 ## Commands

skills/ha-backup/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ha-backup
-version: 0.1.0
-description: "Create, list, inspect, delete, and restore Home Assistant backups with hass-cli. Use for 'make a backup', 'list my backups', 'back up before I change something', 'delete old backups', 'restore this backup' requests. Backups go to configured agents (local and/or cloud/network)."
+version: 0.2.0
+description: "Create, list, inspect, delete and restore Home Assistant backups."
 metadata:
   requires:
     bins: ["hass-cli"]
@@ -11,7 +11,7 @@ metadata:
 # ha-backup
 
 Native Home Assistant backups (the Settings > System > Backups feature).
-**Prerequisite:** [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
+Connection or auth trouble: [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
 
 ## List & inspect
 

skills/ha-climate/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ha-climate
-version: 0.1.0
-description: "Control Home Assistant climate, HVAC, thermostats, humidifiers, and water heaters with hass-cli: set target temperature, HVAC mode (heat/cool/auto/off), fan mode, preset, humidity, and water-heater operation. Use for 'set the thermostat to 21', 'turn on the AC', 'set to eco', 'set humidity to 45%' requests. All control goes through service call."
+version: 0.2.0
+description: "Set temperature, HVAC, fan and preset modes on thermostats, humidifiers and water heaters."
 metadata:
   requires:
     bins: ["hass-cli"]
@@ -10,8 +10,25 @@ metadata:
 
 # ha-climate
 
-Thermostats, HVAC, humidifiers, water heaters. **Prerequisites:**
-[`../ha-shared/SKILL.md`](../ha-shared/SKILL.md), [`../ha-services/SKILL.md`](../ha-services/SKILL.md).
+Thermostats, HVAC, humidifiers, water heaters. Connection or auth trouble: [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
+
+## Quick control (most requests)
+
+Two commands turn an existing device on or off or set it. Do not load other
+skills, run `service describe`, or check the state afterwards.
+
+```bash
+# 1. Find it by name: a few rows, not the whole house
+hass-cli state list --domain climate --search living
+
+# 2. Call the service on the entity_id from step 1
+hass-cli service call climate.set_temperature --data '{"entity_id":"climate.living","temperature":21}'
+hass-cli service call climate.set_hvac_mode --data '{"entity_id":"climate.living","hvac_mode":"cool"}'
+```
+
+The call prints the entities it changed: that is the confirmation. `No entity
+changed state` means it was already that way. No row: search one word, another
+language, or the domain alone. Several equally likely rows: ask which one.
 
 ## Climate (`climate.*`)
 

skills/ha-energy/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ha-energy
-version: 0.1.0
-description: "Inspect and configure Home Assistant's Energy dashboard with hass-cli: read energy preferences (grid/solar/battery/gas/water sources and devices), validate the energy config, and pull consumption statistics. Use for 'show my energy setup', 'how much solar did I produce', 'what's using the most power' questions. Energy data is WebSocket + statistics-based."
+version: 0.2.0
+description: "Read and configure the Energy dashboard and pull energy statistics."
 metadata:
   requires:
     bins: ["hass-cli"]
@@ -10,8 +10,7 @@ metadata:
 
 # ha-energy
 
-The Energy dashboard config and statistics. **Prerequisite:**
-[`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
+The Energy dashboard config and statistics. Connection or auth trouble: [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
 
 ## Read the energy setup
 

skills/ha-entities/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ha-entities
-version: 0.2.0
-description: "Read and control the general Home Assistant entity domains with hass-cli that don't have a dedicated skill: sensor, binary_sensor, number, select, text, button, update, weather, vacuum, alarm_control_panel, siren, camera, todo lists, and calendars. Use for 'read this sensor', 'set this number/select/text helper-style entity', 'start the vacuum', 'arm the alarm', 'what's on my to-do list', 'next calendar event' requests."
+version: 0.3.0
+description: "Read or control entity domains without their own skill: sensors, buttons, numbers, selects, text, vacuums, weather, updates and the like."
 metadata:
   requires:
     bins: ["hass-cli"]
@@ -10,8 +10,7 @@ metadata:
 
 # ha-entities
 
-The long tail of entity domains. **Prerequisites:**
-[`../ha-shared/SKILL.md`](../ha-shared/SKILL.md), [`../ha-services/SKILL.md`](../ha-services/SKILL.md).
+The long tail of entity domains. Connection or auth trouble: [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
 
 > Read with `state get`; control with `service call`. Find candidates with
 > `hass-cli state list --domain <domain>`.

skills/ha-gateway/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ha-gateway
-version: 0.1.0
-description: "Manage Home Assistant radio gateways and their networks with hass-cli: Zigbee (ZHA), Z-Wave JS, Matter, and Thread/OTBR. Use to pair/remove a Zigbee device, permit join, add/exclude a Z-Wave node, read network status/topology, back up a Zigbee/Z-Wave coordinator, commission a Matter device, or inspect Thread datasets. The gateway integration's own lifecycle (add/reload/delete) lives in ha-integrations; the devices it exposes live in ha-registry."
+version: 0.2.0
+description: "Manage Zigbee (ZHA), Z-Wave JS, Matter and Thread networks: pair, remove and inspect devices."
 metadata:
   requires:
     bins: ["hass-cli"]
@@ -11,7 +11,7 @@ metadata:
 # ha-gateway
 
 Radio gateways (a.k.a. coordinators / hubs / bridges) and their device networks.
-**Prerequisite:** [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
+Connection or auth trouble: [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
 
 A gateway in Home Assistant is an **integration (config entry)** that owns a set
 of **devices**. So split the work:

skills/ha-helpers/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ha-helpers
-version: 0.1.0
-description: "Create and manage Home Assistant helper entities with hass-cli: input_boolean, input_button, input_number, input_select, input_text, input_datetime, counter, timer, and schedule. Use to add a toggle/number/dropdown/text helper, a counter or timer, or a weekly schedule, and to list/rename/delete them. Creating a helper is a config operation (WebSocket), distinct from operating it (service call)."
+version: 0.2.0
+description: "Create and manage helper entities: input_boolean, input_number, input_select, input_text, input_datetime, counters, timers and schedules."
 metadata:
   requires:
     bins: ["hass-cli"]
@@ -11,7 +11,7 @@ metadata:
 # ha-helpers
 
 Manage helper entities — the user-defined inputs automations read and write.
-**Prerequisite:** [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
+Connection or auth trouble: [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
 
 > Two different things, do not confuse them:
 > - **Manage the helper** (create/rename/delete the entity itself) → `hass-cli helper ...` (this skill, WebSocket-only).

skills/ha-integrations/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ha-integrations
-version: 0.1.0
-description: "Manage Home Assistant integrations (config entries) and device discovery with hass-cli: list integrations and their state, reload, enable/disable, delete, update entry options, and inspect discovered/in-progress config flows. Use for 'list my integrations', 'reload the X integration', 'why is this integration failing', 'disable this entry', 'what was discovered on my network' requests."
+version: 0.2.0
+description: "List, reload, enable, disable and delete integrations, change their options, and handle device discovery."
 metadata:
   requires:
     bins: ["hass-cli"]
@@ -10,8 +10,7 @@ metadata:
 
 # ha-integrations
 
-Config entries are the runtime instances of integrations. **Prerequisite:**
-[`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
+Config entries are the runtime instances of integrations. Connection or auth trouble: [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
 
 > List/get/update/enable/disable go over WebSocket; reload and delete are
 > REST-only config endpoints. The CLI routes both for you.

skills/ha-lighting/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ha-lighting
-version: 0.2.0
-description: "Control Home Assistant lights, switches, and fans with hass-cli: turn on/off, dim, set color or color temperature, set fan speed/oscillation. Use for any 'turn on the lights', 'dim to 30%', 'make it warm white', 'set fan to medium' style request. All control goes through service call."
+version: 0.3.0
+description: "Turn lights, switches and fans on or off, dim them, set colour or colour temperature, set fan speed. The skill for 'turn on the light' or 'turn off the fan'."
 metadata:
   requires:
     bins: ["hass-cli"]
@@ -10,13 +10,29 @@ metadata:
 
 # ha-lighting
 
-Lights, switches, fans. Turning one on or off needs only the quick-control
-section of [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md); this skill adds
-brightness, colour, fans and group targets.
+Lights, switches, fans. Connection or auth trouble: [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
 
-> No `hass-cli light` command — drive everything with `service call`. Find
-> targets with `hass-cli state list --domain light --search <name>`. The call
-> prints what it changed, so there is nothing to check afterwards.
+## Quick control (most requests)
+
+Two commands turn an existing device on or off or set it. Do not load other
+skills, run `service describe`, or check the state afterwards.
+
+```bash
+# 1. Find it by name: a few rows, not the whole house
+hass-cli state list --domain light --search kitchen
+
+# 2. Call the service on the entity_id from step 1
+hass-cli service call light.turn_on --arguments entity_id=light.kitchen
+hass-cli service call light.turn_off --arguments entity_id=light.kitchen
+hass-cli service call switch.turn_off --arguments entity_id=switch.porch
+hass-cli service call fan.turn_on --arguments entity_id=fan.bedroom
+```
+
+The call prints the entities it changed: that is the confirmation. `No entity
+changed state` means it was already that way. No row: search one word, another
+language, or the domain alone. Several equally likely rows: ask which one.
+
+> No `hass-cli light` command — drive everything with `service call`.
 
 ## Lights (`light.*`)
 

skills/ha-lovelace/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ha-lovelace
-version: 0.1.0
-description: "Read and write Home Assistant Lovelace dashboards with hass-cli: list dashboards, create/update/delete storage-mode dashboards, get and save a dashboard's full view/card config (YAML or JSON), and manage custom JS/CSS resources. Use for 'show my dashboards', 'edit the dashboard config', 'add a card', 'create a new dashboard', 'export/import a dashboard' requests."
+version: 0.2.0
+description: "List, create and edit Lovelace dashboards and their view and card configuration."
 metadata:
   requires:
     bins: ["hass-cli"]
@@ -11,7 +11,7 @@ metadata:
 # ha-lovelace
 
 Dashboards, their stored view/card config, and custom resources. All WebSocket.
-**Prerequisite:** [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
+Connection or auth trouble: [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
 
 ## Mental model
 

skills/ha-media/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ha-media
-version: 0.1.0
-description: "Control Home Assistant media players with hass-cli: play/pause/stop, next/previous track, set volume, mute, select source, and play media. Use for 'pause the TV', 'set volume to 30%', 'play music in the kitchen', 'switch input to HDMI2' requests. All control goes through service call."
+version: 0.2.0
+description: "Play, pause, skip, set volume, mute or switch source on media players such as speakers and TVs."
 metadata:
   requires:
     bins: ["hass-cli"]
@@ -10,8 +10,25 @@ metadata:
 
 # ha-media
 
-Media players (speakers, TVs, receivers). **Prerequisites:**
-[`../ha-shared/SKILL.md`](../ha-shared/SKILL.md), [`../ha-services/SKILL.md`](../ha-services/SKILL.md).
+Media players (speakers, TVs, receivers). Connection or auth trouble: [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
+
+## Quick control (most requests)
+
+Two commands turn an existing device on or off or set it. Do not load other
+skills, run `service describe`, or check the state afterwards.
+
+```bash
+# 1. Find it by name: a few rows, not the whole house
+hass-cli state list --domain media_player --search tv
+
+# 2. Call the service on the entity_id from step 1
+hass-cli service call media_player.media_play_pause --arguments entity_id=media_player.tv
+hass-cli service call media_player.volume_set --data '{"entity_id":"media_player.tv","volume_level":0.3}'
+```
+
+The call prints the entities it changed: that is the confirmation. `No entity
+changed state` means it was already that way. No row: search one word, another
+language, or the domain alone. Several equally likely rows: ask which one.
 
 ## Transport
 

skills/ha-notify/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ha-notify
-version: 0.1.0
-description: "Send notifications and manage persistent notifications in Home Assistant with hass-cli: push messages to phones/devices via notify services, send TTS to speakers, and create/dismiss the dashboard's persistent notifications. Use for 'notify my phone', 'announce on the kitchen speaker', 'show a dashboard alert' requests."
+version: 0.2.0
+description: "Send notifications to phones and devices, speak TTS on speakers, and manage persistent notifications."
 metadata:
   requires:
     bins: ["hass-cli"]
@@ -10,8 +10,7 @@ metadata:
 
 # ha-notify
 
-Notifications and announcements. **Prerequisites:**
-[`../ha-shared/SKILL.md`](../ha-shared/SKILL.md), [`../ha-services/SKILL.md`](../ha-services/SKILL.md).
+Notifications and announcements. Connection or auth trouble: [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
 
 ## Discover notify targets
 

skills/ha-openings/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ha-openings
-version: 0.1.0
-description: "Control Home Assistant covers, locks, valves, garage doors, and gates with hass-cli: open/close/stop covers, set position and tilt, lock/unlock, open/close valves. Use for 'open the blinds', 'close the garage', 'set shades to 50%', 'lock the front door' requests. All control goes through service call."
+version: 0.2.0
+description: "Open, close or position covers, blinds, garage doors and gates; lock and unlock locks; open and close valves."
 metadata:
   requires:
     bins: ["hass-cli"]
@@ -10,8 +10,26 @@ metadata:
 
 # ha-openings
 
-Covers (blinds/shades/garage/gate), locks, valves. **Prerequisites:**
-[`../ha-shared/SKILL.md`](../ha-shared/SKILL.md), [`../ha-services/SKILL.md`](../ha-services/SKILL.md).
+Covers (blinds/shades/garage/gate), locks, valves. Connection or auth trouble: [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
+
+## Quick control (most requests)
+
+Two commands turn an existing device on or off or set it. Do not load other
+skills, run `service describe`, or check the state afterwards.
+
+```bash
+# 1. Find it by name: a few rows, not the whole house
+hass-cli state list --domain cover --search bedroom
+
+# 2. Call the service on the entity_id from step 1
+hass-cli service call cover.close_cover --arguments entity_id=cover.bedroom
+hass-cli service call cover.open_cover --arguments entity_id=cover.bedroom
+hass-cli service call lock.lock --arguments entity_id=lock.front_door
+```
+
+The call prints the entities it changed: that is the confirmation. `No entity
+changed state` means it was already that way. No row: search one word, another
+language, or the domain alone. Several equally likely rows: ask which one.
 
 ## Covers (`cover.*`)
 

skills/ha-presence/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ha-presence
-version: 0.2.0
-description: "Work with Home Assistant presence and organization: people, zones, device trackers, and groups with hass-cli. Use to see who is home, check a person's location/zone, list zones, set a device_tracker's location, and read group membership for presence-based automations."
+version: 0.3.0
+description: "See who is home and where: people, zones, device trackers and groups."
 metadata:
   requires:
     bins: ["hass-cli"]
@@ -11,8 +11,7 @@ metadata:
 # ha-presence
 
 People, zones, trackers, groups — the inputs for presence automations.
-**Prerequisites:** [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md),
-[`../ha-services/SKILL.md`](../ha-services/SKILL.md).
+Connection or auth trouble: [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
 
 ## Who is home