claude-skills/skills/homeassistant/SKILL.md

---
name: homeassistant
description: "Comprehensive Home Assistant smart home automation toolkit. Use when users need help with: (1) Creating or editing automations in YAML, (2) Controlling or querying devices via the Home Assistant API, (3) Writing and validating configuration files, (4) Troubleshooting automation or configuration issues, (5) Understanding Home Assistant concepts like triggers, conditions, actions, (6) Integrating with smart home devices and services. Trigger for queries about home automation, YAML automation configs, entity states, service calls, or debugging Home Assistant setups."
---

# Home Assistant

## Overview

This skill enables Claude to work with Home Assistant, the open-source home automation platform. It provides tools for creating automations, controlling devices via API, validating configurations, and troubleshooting common issues.

## Core Capabilities

### 1. Automation Creation and Editing

Create, modify, and troubleshoot Home Assistant automations in YAML format.

**Key concepts:**
- **Triggers** - What starts the automation (state change, time, sun event, etc.)
- **Conditions** - Optional checks that must pass before actions run
- **Actions** - What the automation does (call services, delays, notifications, etc.)

**Quick example:**
```yaml
automation:
  - alias: "Motion Light"
    trigger:
      - trigger: state
        entity_id: binary_sensor.motion
        to: "on"
    action:
      - action: light.turn_on
        target:
          entity_id: light.hallway
```

**For detailed automation syntax:** See `references/automation_reference.md`

**For common patterns:** See `references/common_patterns.md`

**Pre-built templates:** Available in `assets/automation_templates/`:
- `motion_light.yaml` - Motion-activated lighting
- `time_based.yaml` - Time-scheduled actions
- `climate_control.yaml` - Temperature-based climate control
- `presence_detection.yaml` - Arrival/departure automation
- `notification.yaml` - Alert and notification patterns

### 2. Device Control via API

Query entity states and control devices through Home Assistant's REST or WebSocket API.

**Prerequisites:**
- Home Assistant URL (e.g., `http://homeassistant.local:8123`)
- Long-lived access token (from Profile page in HA)

**Common operations:**

**List all entities:**
```bash
python3 scripts/list_entities.py --url http://homeassistant.local:8123 --token YOUR_TOKEN
```

**Get specific entity state:**
```bash
python3 scripts/api_client.py --url http://homeassistant.local:8123 --token YOUR_TOKEN get-state light.living_room
```

**Control a device:**
```bash
python3 scripts/api_client.py --url http://homeassistant.local:8123 --token YOUR_TOKEN call-service light turn_on --entity light.kitchen --data '{"brightness": 255}'
```

**List available services:**
```bash
python3 scripts/list_services.py --url http://homeassistant.local:8123 --token YOUR_TOKEN
```

**Environment variables:**
Set `HA_URL` and `HA_TOKEN` to avoid passing credentials each time:
```bash
export HA_URL=http://homeassistant.local:8123
export HA_TOKEN=your_token_here
```

**For complete API documentation:** See `references/api_reference.md`

### 3. Configuration Validation

Validate YAML configuration files for syntax errors and common issues.

**Validate any YAML file:**
```bash
python3 scripts/validate_yaml.py configuration.yaml
```

**Validate automation configuration:**
```bash
python3 scripts/validate_yaml.py automations.yaml --type automation
```

**Common issues detected:**
- Tab characters (Home Assistant requires spaces)
- Missing required fields (e.g., `trigger` in automations)
- Incorrect YAML syntax
- Unquoted boolean states
- Structural problems

**Verbose output:**
```bash
python3 scripts/validate_yaml.py automations.yaml --type automation --verbose
```

### 4. Troubleshooting and Debugging

Diagnose and fix common Home Assistant issues.

**Common problems:**

**YAML syntax errors:**
- Tab characters: Use spaces only (2 spaces per indent level)
- Boolean states: Quote them: `state: "on"` not `state: on`
- Indentation: Must be exact (2 spaces per level)

**Automations not triggering:**
1. Check automation is enabled
2. Verify entity IDs are correct
3. Check trigger conditions (quoted states, numeric values)
4. Review automation trace in Home Assistant UI

**Template errors:**
- Use default filters: `{{ states('sensor.test') | default('unknown') }}`
- Check entity exists before accessing

**API errors:**
- 401 Unauthorized: Verify access token is valid
- 404 Not Found: Check entity ID spelling and existence
- Service call fails: List services to verify parameters

**For complete troubleshooting guide:** See `references/troubleshooting.md`

## Workflow Examples

### Creating a New Automation

1. **Understand the requirement:**
   - What should trigger it? (motion, time, state change, etc.)
   - What conditions should apply? (time of day, presence, etc.)
   - What should it do? (turn on lights, send notification, etc.)

2. **Choose a starting point:**
   - Use pre-built template from `assets/automation_templates/`
   - Or reference common pattern from `references/common_patterns.md`
   - Or build from scratch using `references/automation_reference.md`

3. **Customize for specific entities:**
   - Replace placeholder entity IDs (e.g., `REPLACE_WITH_MOTION_SENSOR`)
   - List available entities: `python3 scripts/list_entities.py`
   - Adjust parameters (brightness, temperature, delays, etc.)

4. **Validate the configuration:**
   ```bash
   python3 scripts/validate_yaml.py your_automation.yaml --type automation
   ```

5. **Test and iterate:**
   - Add to Home Assistant
   - Use automation trace feature to debug
   - Refine based on behavior

### Controlling Devices from API

1. **Discover available entities:**
   ```bash
   python3 scripts/list_entities.py --domain light
   ```

2. **Check current state:**
   ```bash
   python3 scripts/api_client.py get-state light.living_room
   ```

3. **List available services for domain:**
   ```bash
   python3 scripts/list_services.py --domain light
   ```

4. **Call service:**
   ```bash
   python3 scripts/api_client.py call-service light turn_on --entity light.living_room --data '{"brightness": 128}'
   ```

### Debugging a Failed Automation

1. **Check for YAML errors:**
   ```bash
   python3 scripts/validate_yaml.py automations.yaml --type automation
   ```

2. **Review error patterns in troubleshooting guide:**
   - See `references/troubleshooting.md`
   - Common issues: tabs, boolean states, indentation

3. **Check Home Assistant logs:**
   ```bash
   python3 scripts/api_client.py get-error-log
   ```

4. **Verify entity IDs exist:**
   ```bash
   python3 scripts/list_entities.py | grep "problem_entity"
   ```

5. **Test with simplified version:**
   - Remove conditions temporarily
   - Add debug notification action
   - Use automation trace in HA UI

## Important Notes

**YAML Syntax Rules:**
- Use 2 spaces for indentation (never tabs)
- Quote state values: `"on"`, `"off"`, `"home"`, `"not_home"`
- Entity IDs are case-sensitive
- All states are strings (use `| int` or `| float` for numeric operations)

**API Authentication:**
- Requires long-lived access token from Profile page
- Pass via `Authorization: Bearer TOKEN` header
- Or set `HA_TOKEN` environment variable

**Templates:**
- Use Jinja2 syntax: `{{ states('entity_id') }}`
- Add default values: `{{ states('sensor.test') | default('unknown') }}`
- Access attributes: `{{ state_attr('entity_id', 'attribute') }}`

**Service Calls:**
- Domain and service required: `light.turn_on`, `climate.set_temperature`
- Target entities via `target` or `entity_id` field
- Additional parameters go in `data` field

## Resources

### Scripts

- `api_client.py` - Home Assistant REST API client for controlling devices and querying states
- `validate_yaml.py` - Validate YAML configurations and automations
- `list_entities.py` - List all entities with filtering options
- `list_services.py` - List available services by domain

All scripts support `--help` flag for usage information.

### References

Load these as needed for detailed information:

- `api_reference.md` - Complete REST and WebSocket API documentation
- `automation_reference.md` - Full automation YAML structure and syntax
- `common_patterns.md` - Real-world automation examples and patterns
- `troubleshooting.md` - Comprehensive debugging guide for common issues

### Assets

- `automation_templates/` - Pre-built YAML templates for common automation types
  - Copy and customize templates by replacing placeholder entity IDs
  - Each template includes comments explaining configuration options