home-assistant

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: home-assistant
description: Control and query Home Assistant smart home devices via the REST API. Use this skill whenever the user mentions Home Assistant, smart home control, IoT devices, home automation, turning lights on/off, checking sensor readings, thermostat control, door locks, or any task involving their home's connected devices — even if they don't explicitly say "Home Assistant." Also trigger when users ask about their home's state, want to create automations, or reference entity IDs like "light.living_room" or "switch.garage_door."
allowed-tools:
  - Bash(source ~/.config/home-assistant/.env)
  - Bash(curl:*)
  - Bash(bash:*)
---

# Home Assistant Control

This skill enables Claude to interact with a Home Assistant instance via its REST API — querying device states, controlling smart home devices, reviewing history, and working with automations.

## Slash Command

When invoked via `/home-assistant`, ensure authentication is set up (see below), then ask the user what they'd like to do — for example: check device status, control lights, adjust the thermostat, view history, or manage automations.

## Setup & Authentication

Configuration lives in `~/.config/home-assistant/.env`. On first use, check if this file exists:

```bash
cat ~/.config/home-assistant/.env 2>/dev/null || echo "NOT_FOUND"
```

**If the file exists**, source it to load `HA_URL` and `HA_TOKEN`:

```bash
source ~/.config/home-assistant/.env
```

**If the file doesn't exist**, walk the user through setup:

1. Explain what's needed: a Home Assistant URL and a Long-Lived Access Token
2. Ask for their HA URL (e.g., `http://192.168.1.100:8123` or `https://home.example.com`)
3. Guide them to create a token: Go to their HA instance → Profile (bottom-left) → Security tab → scroll to "Long-Lived Access Tokens" → click "Create Token" → give it a name like "Claude" → copy the token
4. Create the config:

```bash
mkdir -p ~/.config/home-assistant
cat > ~/.config/home-assistant/.env << 'EOF'
HA_URL="http://your-ha-address:8123"
HA_TOKEN="your_token_here"
EOF
chmod 600 ~/.config/home-assistant/.env
```

Replace the placeholder values with what the user provides. The `chmod 600` ensures only the user can read the token.

After sourcing, verify connectivity:

```bash
source ~/.config/home-assistant/.env
curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/"
```

Expected response: `{"message": "API running."}`. If it fails, check the URL and token with the user.

## Workflow

Follow this general approach for any Home Assistant task:

### 1. Discover what's available

Before trying to control or query specific devices, find out what entities exist. Run the discovery script to get a formatted overview:

```bash
bash <skill-path>/scripts/discover_entities.sh
```

This lists all entities grouped by domain (lights, switches, sensors, etc.) with their current states. Use this output to map the user's natural language ("the kitchen light") to actual entity IDs (`light.kitchen_ceiling`).

If the user asks about a specific type of device, you can filter:

```bash
bash <skill-path>/scripts/discover_entities.sh light
bash <skill-path>/scripts/discover_entities.sh sensor
bash <skill-path>/scripts/discover_entities.sh climate
```

### 2. Query state

To check the current state of a specific entity:

```bash
curl -s -H "Authorization: Bearer $HA_TOKEN" \
  -H "Content-Type: application/json" \
  "$HA_URL/api/states/<entity_id>"
```

The response includes `state` (the primary value) and `attributes` (detailed properties like brightness, temperature, friendly name, etc.).

### 3. Take action (with confirmation)

**Before performing any action that changes device state, describe what you're about to do and ask the user to confirm.** This applies to all service calls — turning things on/off, locking/unlocking, adjusting temperatures, triggering scenes, etc. The reason: smart home actions affect the physical world and can't be undone with ctrl-z.

To call a service:

``