homeassistant-skill

# Home Assistant Skill

Control smart home devices via the Home Assistant REST API.

## Setup

Set environment variables:
- `HA_URL` — Your Home Assistant URL (e.g., `http://10.0.0.10:8123`)
- `HA_TOKEN` — Long-lived access token (create in HA → Profile → Long-Lived Access Tokens)

## Safety Rules

**Always confirm with the user before performing these actions:**
- **Locks** — locking or unlocking any lock
- **Alarm panels** — arming or disarming
- **Garage doors** — opening or closing (`cover.*` with `device_class: garage`)
- **Security automations** — disabling automations related to security or safety
- **Covers** — opening or closing covers that control physical access (gates, barriers)

Never act on security-sensitive devices without explicit user confirmation.

## Entity Discovery

### List all entities

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

### List entities by domain

```bash
# Switches
curl -s "$HA_URL/api/states" -H "Authorization: Bearer $HA_TOKEN" \
  | jq -r '.[] | select(.entity_id | startswith("switch.")) | "\(.entity_id): \(.state)"'

# Lights
curl -s "$HA_URL/api/states" -H "Authorization: Bearer $HA_TOKEN" \
  | jq -r '.[] | select(.entity_id | startswith("light.")) | "\(.entity_id): \(.state)"'

# Sensors
curl -s "$HA_URL/api/states" -H "Authorization: Bearer $HA_TOKEN" \
  | jq -r '.[] | select(.entity_id | startswith("sensor.")) | "\(.entity_id): \(.state) \(.attributes.unit_of_measurement // "")"'
```

Replace the domain prefix (`switch.`, `light.`, `sensor.`, etc.) to discover entities
in any domain.

### Get single entity state

```bash
curl -s "$HA_URL/api/states/ENTITY_ID" -H "Authorization: Bearer $HA_TOKEN"
```

### Area & Floor Discovery

Use the template API to query areas, floors, and labels.

```bash
# List all areas
curl -s -X POST "$HA_URL/api/template" \
  -H "Authorization: Bearer $HA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "{{...

# Home Assistant Skill

An AI agent skill for controlling Home Assistant devices and automations through natural language. 25 entity domains including lights, climate, locks, presence, weather, calendars, notifications, and more — all via the HA REST API.

Works with [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenClaw](https://github.com/openclaw/openclaw), [Cursor](https://cursor.com), and any tool supporting the [SKILL.md](https://agentskills.io) standard.

[![ClawHub](https://img.shields.io/badge/ClawHub-homeassistant--skill-blue)](https://clawhub.ai/skills/homeassistant-skill)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

Part of [unsol.dev](https://unsol.dev)

## Prerequisites

- Home Assistant instance with API access
- `curl` and `jq` installed

## Installation

### Claude Code

```bash
git clone https://github.com/anotb/homeassistant-skill.git ~/.claude/skills/homeassistant-skill
```

### OpenClaw (via ClawdHub)

```bash
clawhub install homeassistant-skill
```

### Cursor / Other

Clone to your agent's skill directory.

## Configuration

1. Create a long-lived access token in Home Assistant: Profile → Long-Lived Access Tokens
2. Set environment variables:

```bash
export HA_URL=http://10.0.0.10:8123
export HA_TOKEN=your-long-lived-access-token
```

## What You Can Do

| Domain | Actions |
|--------|---------|
| Switches | Turn on, off, toggle |
| Lights | On/off, brightness, color, color temp |
| Scenes | Activate scenes |
| Scripts | List, run, run with variables |
| Automations | Trigger, enable, disable |
| Climate | Set temperature, HVAC mode |
| Covers | Open, close, set position (blinds, garage) |
| Locks | Lock, unlock (with safety confirmation) |
| Fans | On/off, speed |
| Media players | Play, pause, volume |
| Vacuum | Start, return to dock |
| Alarm | Arm, disarm (with safety confirmation) |
| Notifications | Send to mobile devices, list targets |
| Person / Presence | Who is home, device loca...