diff --git a/AGENTS.md b/AGENTS.md
index cc2ca0a..f8f7447 100644
--- a/AGENTS.md
+++ b/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
 
diff --git a/skills/ha-assist/SKILL.md b/skills/ha-assist/SKILL.md
index f75c156..69b2665 100644
--- a/skills/ha-assist/SKILL.md
+++ b/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
diff --git a/skills/ha-automation/SKILL.md b/skills/ha-automation/SKILL.md
index 2a05957..bbb7ae9 100644
--- a/skills/ha-automation/SKILL.md
+++ b/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
diff --git a/skills/ha-backup/SKILL.md b/skills/ha-backup/SKILL.md
index f7f8724..99607db 100644
--- a/skills/ha-backup/SKILL.md
+++ b/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
 
diff --git a/skills/ha-climate/SKILL.md b/skills/ha-climate/SKILL.md
index d763b64..b3b8c29 100644
--- a/skills/ha-climate/SKILL.md
+++ b/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.*`)
 
diff --git a/skills/ha-energy/SKILL.md b/skills/ha-energy/SKILL.md
index 4f6ebba..3712a9c 100644
--- a/skills/ha-energy/SKILL.md
+++ b/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
 
diff --git a/skills/ha-entities/SKILL.md b/skills/ha-entities/SKILL.md
index 7522a26..3dbe0b3 100644
--- a/skills/ha-entities/SKILL.md
+++ b/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>`.
diff --git a/skills/ha-gateway/SKILL.md b/skills/ha-gateway/SKILL.md
index 6a97499..b12f6e9 100644
--- a/skills/ha-gateway/SKILL.md
+++ b/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:
diff --git a/skills/ha-helpers/SKILL.md b/skills/ha-helpers/SKILL.md
index 3d3d5df..a9d15eb 100644
--- a/skills/ha-helpers/SKILL.md
+++ b/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).
diff --git a/skills/ha-integrations/SKILL.md b/skills/ha-integrations/SKILL.md
index b25729a..577c24e 100644
--- a/skills/ha-integrations/SKILL.md
+++ b/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.
diff --git a/skills/ha-lighting/SKILL.md b/skills/ha-lighting/SKILL.md
index 92c82d8..8b87b74 100644
--- a/skills/ha-lighting/SKILL.md
+++ b/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.*`)
 
diff --git a/skills/ha-lovelace/SKILL.md b/skills/ha-lovelace/SKILL.md
index 9321b91..34ee946 100644
--- a/skills/ha-lovelace/SKILL.md
+++ b/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
 
diff --git a/skills/ha-media/SKILL.md b/skills/ha-media/SKILL.md
index c8a4a22..88a1ca6 100644
--- a/skills/ha-media/SKILL.md
+++ b/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
 
diff --git a/skills/ha-notify/SKILL.md b/skills/ha-notify/SKILL.md
index d96049e..d10198f 100644
--- a/skills/ha-notify/SKILL.md
+++ b/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
 
diff --git a/skills/ha-openings/SKILL.md b/skills/ha-openings/SKILL.md
index 6313d11..da1f346 100644
--- a/skills/ha-openings/SKILL.md
+++ b/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.*`)
 
diff --git a/skills/ha-presence/SKILL.md b/skills/ha-presence/SKILL.md
index 2406413..44f6258 100644
--- a/skills/ha-presence/SKILL.md
+++ b/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
 
diff --git a/skills/ha-registry/SKILL.md b/skills/ha-registry/SKILL.md
index 0da7972..dc5786b 100644
--- a/skills/ha-registry/SKILL.md
+++ b/skills/ha-registry/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: ha-registry
-version: 0.1.0
-description: "Manage Home Assistant areas, devices, entities, floors, and labels with hass-cli. Use to list/create/rename/delete areas, assign devices or entities to areas, organize with floors and labels, rename entity_ids, or audit the registry. These are WebSocket-only operations (config/*_registry/*)."
+version: 0.2.0
+description: "Organise areas, floors, labels, devices and entities: list, create, rename, assign and delete."
 metadata:
   requires:
     bins: ["hass-cli"]
@@ -10,8 +10,7 @@ metadata:
 
 # ha-registry
 
-Organize the home: areas, devices, entities, floors, labels. **Prerequisite:**
-[`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
+Organize the home: areas, devices, entities, floors, labels. Connection or auth trouble: [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
 
 > All registry operations are WebSocket-only. hass-cli routes them
 > automatically; you do not pick the transport.
diff --git a/skills/ha-services/SKILL.md b/skills/ha-services/SKILL.md
index c05fab4..9966d22 100644
--- a/skills/ha-services/SKILL.md
+++ b/skills/ha-services/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: ha-services
-version: 0.2.0
-description: "Call Home Assistant services to control devices and trigger actions with hass-cli. Use to turn lights on/off, set climate, open covers, play media, run any domain.service. Covers discovering services (service list/describe) and calling them (service call) with --arguments and --data, including targeting by entity/device/area."
+version: 0.3.0
+description: "List, describe and call any Home Assistant service, and fire events, when no domain skill covers the request."
 metadata:
   requires:
     bins: ["hass-cli"]
@@ -10,11 +10,12 @@ metadata:
 
 # ha-services
 
-Drive devices by calling services. **Prerequisite:** [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
+Drive devices by calling services. Connection or auth trouble: [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
 
-> This is the workhorse for ALL device control. There are no per-domain
-> commands (no `hass-cli light ...`); everything goes through `service call`
-> against the service schema.
+> Lights, covers, climate and media have their usual calls in their domain
+> skills; reach for this one for any other service and to discover a service's
+> fields. There are no per-domain commands (no `hass-cli light ...`): everything
+> goes through `service call` against the service schema.
 
 ## Discover
 
diff --git a/skills/ha-shared/SKILL.md b/skills/ha-shared/SKILL.md
index d607c23..e6a699b 100644
--- a/skills/ha-shared/SKILL.md
+++ b/skills/ha-shared/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: ha-shared
-version: 0.2.0
-description: "Shared foundation for all hass-cli skills. Read this FIRST: its first section turns a device on/off, dims it or sets it in two commands without reading any other skill. Covers connecting to a Home Assistant instance (HASS_SERVER + HASS_TOKEN long-lived token), the unified REST+WebSocket transport facade, output formats (table/json/yaml/ndjson), the raw passthrough escape hatches (raw api / raw ws), and the auth-error recovery table. Use whenever the user mentions Home Assistant, hass-cli, controlling smart-home entities, calling services, automations, or any HA REST/WebSocket API task."
+version: 0.3.0
+description: "Connecting hass-cli to Home Assistant (profile or token), output formats, raw REST and WebSocket access, and auth-error recovery. Load when a command cannot connect or authenticate; device control is in the domain skills."
 metadata:
   requires:
     bins: ["hass-cli"]
@@ -10,7 +10,7 @@ metadata:
 
 # ha-shared (foundation)
 
-**Read this before any other `ha-*` skill.** It defines how to connect and the conventions every command follows.
+How to connect and the conventions every `ha-*` command follows. Load it when a command cannot connect or authenticate; device control is in the domain skills, each of which carries its own quick control.
 
 > Source of truth for flags is always `hass-cli <command> --help`. This file carries the connection model, transport routing, and error recovery that `--help` cannot.
 
diff --git a/skills/ha-states/SKILL.md b/skills/ha-states/SKILL.md
index edac7b6..d0478f8 100644
--- a/skills/ha-states/SKILL.md
+++ b/skills/ha-states/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: ha-states
-version: 0.2.0
-description: "Read Home Assistant entity states and recent history with hass-cli. Use to answer 'is the light on', 'what's the temperature', 'list all sensors', 'what changed recently', or to inspect any entity's current state and attributes. Covers state list/get, table shaping (--columns/--sort-by), and history/logbook reads."
+version: 0.3.0
+description: "Read entity states and recent history: 'is the light on', 'what is the temperature', list the entities of a domain."
 metadata:
   requires:
     bins: ["hass-cli"]
@@ -10,7 +10,7 @@ metadata:
 
 # ha-states
 
-Read entity state. **Prerequisite:** read [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md) for connection/auth.
+Read entity state. Connection or auth trouble: [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
 
 ## Commands
 
diff --git a/skills/ha-statistics/SKILL.md b/skills/ha-statistics/SKILL.md
index cd472f6..647ebf5 100644
--- a/skills/ha-statistics/SKILL.md
+++ b/skills/ha-statistics/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: ha-statistics
-version: 0.1.0
-description: "Query Home Assistant's recorder long-term statistics with hass-cli: list which statistic ids exist, read their metadata (unit, source, has_sum/has_mean), and pull aggregated values (sum/mean/min/max) over a time period and bucket. Use for 'how much energy/water/gas over time', 'trend of this sensor', 'monthly totals', or as the data source for consumption/audit analyses. Distinct from instantaneous state history."
+version: 0.2.0
+description: "Query recorder long-term statistics: list statistic ids, read their metadata and aggregated values."
 metadata:
   requires:
     bins: ["hass-cli"]
@@ -11,8 +11,7 @@ metadata:
 # ha-statistics
 
 Recorder long-term statistics — the aggregated, downsampled history HA keeps
-for `sensor`s with `state_class` (and external stats). **Prerequisite:**
-[`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
+for `sensor`s with `state_class` (and external stats). Connection or auth trouble: [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
 
 ## Statistics vs. history
 
diff --git a/skills/ha-supervisor/SKILL.md b/skills/ha-supervisor/SKILL.md
index 5902b3a..c5e0ca6 100644
--- a/skills/ha-supervisor/SKILL.md
+++ b/skills/ha-supervisor/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: ha-supervisor
-version: 0.1.0
-description: "Manage Home Assistant add-ons and the Supervisor/OS layer with hass-cli. Use to list/install/uninstall/update/start/stop/restart add-ons, browse the add-on store, read add-on logs, or check Core/Supervisor/OS info. Works through Core's supervisor/api WebSocket proxy with a regular admin token (no separate supervisor token needed)."
+version: 0.2.0
+description: "Manage add-ons and the Supervisor/OS layer on Home Assistant OS or Supervised installs."
 metadata:
   requires:
     bins: ["hass-cli"]
@@ -10,8 +10,7 @@ metadata:
 
 # ha-supervisor
 
-Add-ons and the Supervisor/OS layer. **Prerequisite:**
-[`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
+Add-ons and the Supervisor/OS layer. Connection or auth trouble: [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
 
 > Availability: these only work on **Supervised / HA OS** installs. On a Core
 > (Container) install there is no Supervisor and the commands fail fast with
diff --git a/skills/ha-system/SKILL.md b/skills/ha-system/SKILL.md
index a863271..831fbec 100644
--- a/skills/ha-system/SKILL.md
+++ b/skills/ha-system/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: ha-system
-version: 0.1.0
-description: "Inspect Home Assistant system health, repair issues, error logs, logbook, and state history with hass-cli. Use to diagnose problems, check integration health, find open repairs, read recent errors, or gather the raw native data that audits (dead entities, broken automations) are derived from. Complexity scoring/audit are NOT native HA features; compute them here from native data."
+version: 0.2.0
+description: "Diagnose Home Assistant: system health, repairs, error logs, logbook and state history."
 metadata:
   requires:
     bins: ["hass-cli"]
@@ -10,8 +10,7 @@ metadata:
 
 # ha-system
 
-Native system insight and the data sources for audits. **Prerequisite:**
-[`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
+Native system insight and the data sources for audits. Connection or auth trouble: [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
 
 ## Native commands
 
diff --git a/skills/ha-workflow-audit/SKILL.md b/skills/ha-workflow-audit/SKILL.md
index bac95e7..28a8fd7 100644
--- a/skills/ha-workflow-audit/SKILL.md
+++ b/skills/ha-workflow-audit/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: ha-workflow-audit
-version: 0.1.0
-description: "Playbook for auditing a Home Assistant instance for tech debt with hass-cli: dead/unavailable entities, duplicate entities, broken automations referencing missing entities, and unused automations. Use when the user asks to 'clean up', 'find broken/unused automations', 'find dead entities', or 'audit my setup'. These are derived analyses (not native HA features) computed from native data."
+version: 0.2.0
+description: "Playbook for auditing a Home Assistant instance: unavailable or duplicate entities and broken automations."
 metadata:
   requires:
     bins: ["hass-cli"]
@@ -10,9 +10,8 @@ metadata:
 
 # ha-workflow-audit
 
-Derive tech-debt reports from native data. **Prerequisite:**
-[`../ha-shared/SKILL.md`](../ha-shared/SKILL.md); data sources in
-[`../ha-system/SKILL.md`](../ha-system/SKILL.md).
+Derive tech-debt reports from native data; the data sources are in
+[`../ha-system/SKILL.md`](../ha-system/SKILL.md). Connection or auth trouble: [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
 
 > Home Assistant does not ship these audits. Compute them client-side from
 > `state list`, the entity registry, and `logbook`/`history`. Always start with
diff --git a/skills/ha-workflow-automation-builder/SKILL.md b/skills/ha-workflow-automation-builder/SKILL.md
index 40f001a..d6669b2 100644
--- a/skills/ha-workflow-automation-builder/SKILL.md
+++ b/skills/ha-workflow-automation-builder/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: ha-workflow-automation-builder
-version: 0.1.0
-description: "Playbook for generating a Home Assistant automation from a natural-language request with hass-cli. Use when the user says 'create an automation that...', 'when X happens do Y', 'automate my lights', or wants a new automation/script/scene built and installed. Orchestrates: gather context -> generate config -> save -> reload -> verify."
+version: 0.2.0
+description: "Playbook for turning a natural-language request into a working Home Assistant automation."
 metadata:
   requires:
     bins: ["hass-cli"]
@@ -10,9 +10,8 @@ metadata:
 
 # ha-workflow-automation-builder
 
-A repeatable recipe to turn a request into a working automation. **Prerequisite:**
-[`../ha-shared/SKILL.md`](../ha-shared/SKILL.md); see also
-[`../ha-automation/SKILL.md`](../ha-automation/SKILL.md).
+A repeatable recipe to turn a request into a working automation; see also
+[`../ha-automation/SKILL.md`](../ha-automation/SKILL.md). Connection or auth trouble: [`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).
 
 ## Steps