home-assistant - SKILL.md Agent Skill

name: home-assistant

description: Control Home Assistant smart home devices, run automations, and receive webhook events. Use when controlling lights, switches, climate, scenes, scripts, or any HA entity. Supports bidirectional communication via REST API (outbound) and webhooks (inbound triggers from HA automations).

metadata: {"clawdbot":{"emoji":"🏠","requires":{"bins":["jq","curl"]}}}

Home Assistant

Control your smart home via Home Assistant's REST API and webhooks.

Setup

Option 1: Config File (Recommended)

Create ~/.config/home-assistant/config.json:


{

  "url": "https://your-ha-instance.duckdns.org",

  "token": "your-long-lived-access-token"

}

Option 2: Environment Variables


export HA_URL="http://homeassistant.local:8123"

export HA_TOKEN="your-long-lived-access-token"

Getting a Long-Lived Access Token

Open Home Assistant → Profile (bottom left)
Scroll to "Long-Lived Access Tokens"
Click "Create Token", name it (e.g., "Clawdbot")
Copy the token immediately (shown only once)

Quick Reference

List Entities


curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states" | jq '.[].entity_id'

Get Entity State


curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states/light.living_room"

Control Devices


# Turn on

curl -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \

  "$HA_URL/api/services/light/turn_on" -d '{"entity_id": "light.living_room"}'



# Turn off

curl -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \

  "$HA_URL/api/services/light/turn_off" -d '{"entity_id": "light.living_room"}'



# Set brightness (0-255)

curl -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \

  "$HA_URL/api/services/light/turn_on" -d '{"entity_id": "light.living_room", "brightness": 128}'

Run Scripts & Automations


# Trigger script

curl -X POST -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/services/script/turn_on" \

  -H "Content-Type: application/json" -d '{"entity_id": "script.goodnight"}'



# Trigger automation

curl -X POST -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/services/automation/trigger" \

  -H "Content-Type: application/json" -d '{"entity_id": "automation.motion_lights"}'

Activate Scenes


curl -X POST -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/services/scene/turn_on" \

  -H "Content-Type: application/json" -d '{"entity_id": "scene.movie_night"}'

Common Services

| Domain | Service | Example entity_id |

|--------|---------|-------------------|

| light | turn_on, turn_off, toggle | light.kitchen |

| switch | turn_on, turn_off, toggle | switch.fan |

| climate | set_temperature, set_hvac_mode | climate.thermostat |

| cover | open_cover, close_cover, stop_cover | cover.garage |

| media_player | play_media, media_pause, volume_set | media_player.tv |

| scene | turn_on | scene.relax |

| script | turn_on | script.welcome_home |

| automation | trigger, turn_on, turn_off | automation.sunrise |

Inbound Webhooks (HA → Clawdbot)

To receive events from Home Assistant automations:

1. Create HA Automation with Webhook Action


# In HA automation

action:

  - service: rest_command.notify_clawdbot

    data:

      event: motion_detected

      area: living_room

2. Define REST Command in HA


# configuration.yaml

rest_command:

  notify_clawdbot:

    url: "https://your-clawdbot-url/webhook/home-assistant"

    method: POST

    headers:

      Authorization: "Bearer {{ webhook_secret }}"

      Content-Type: "application/json"

    payload: '{"event": "{{ event }}", "area": "{{ area }}"}'

3. Handle in Clawdbot

Clawdbot receives the webhook and can notify you or take action based on the event.

CLI Wrapper

The scripts/ha.sh CLI provides easy access to all HA functions:


# Test connection

ha.sh info



# List entities

ha.sh list all          # all entities

ha.sh list lights       # just lights

ha.sh list switch       # just switches



# Search entities

ha.sh search kitchen    # find entities by name



# Get/set state

ha.sh state light.living_room

ha.sh states light.living_room   # full details with attributes

ha.sh on light.living_room

ha.sh on light.living_room 200   # with brightness (0-255)

ha.sh off light.living_room

ha.sh toggle switch.fan



# Scenes & scripts

ha.sh scene movie_night

ha.sh script goodnight



# Climate

ha.sh climate climate.thermostat 22



# Call any service

ha.sh call light turn_on '{"entity_id":"light.room","brightness":200}'

Troubleshooting

401 Unauthorized: Token expired or invalid. Generate a new one.
Connection refused: Check HA_URL, ensure HA is running and accessible.
Entity not found: List entities to find the correct entity_id.

API Reference

For advanced usage, see references/api.md.