homeassistant-config

What this skill does

# Home Assistant Configuration Skill

Create and manage Home Assistant YAML configuration files including automations, scripts, templates, blueprints, and file organization.

## Slash Commands

| Command | Description |
|---------|-------------|
| `/ha-find-duplicates [path]` | Find duplicate automations and scripts in configuration |

### /ha-find-duplicates
Scans Home Assistant configuration files to find:
- **Exact duplicates**: Automations/scripts with identical triggers and actions
- **Similar items**: Items with 80%+ similarity (name, entities, structure)
- **Trigger conflicts**: Multiple automations responding to the same trigger

Usage: `/ha-find-duplicates /path/to/config` or `/ha-find-duplicates` for current directory.

## Subagents

| Agent | Description |
|-------|-------------|
| `ha-suggestions` | Smart home improvement advisor for automations, scenes, and device recommendations |

### ha-suggestions
A proactive smart home consultant that analyzes your Home Assistant configuration and provides personalized suggestions for:

- **New Automations**: Motion lighting, presence detection, time-based routines, energy saving
- **New Scenes**: Movie night, morning energy, dinner time, work from home, party mode
- **Script Improvements**: Reusable sequences and parameterized routines
- **Device Recommendations**: Sensors, switches, and integrations to enhance your setup
- **Optimization**: Consolidation, trigger efficiency, mode usage, blueprint conversion

The agent automatically discovers your configuration files, inventories entities by domain (lights, sensors, climate, etc.), and generates prioritized suggestions with complete, ready-to-use YAML code.

## Validation Scripts

This skill includes scripts to validate and analyze Home Assistant configurations.

### YAML Validator
Validates YAML syntax and checks for common HA issues (tabs, unquoted booleans, deprecated syntax):
```bash
python3 {baseDir}/scripts/validate_yaml.py /path/to/config.yaml
python3 {baseDir}/scripts/validate_yaml.py /path/to/config.yaml --strict
```

### Configuration Checker
Analyzes HA configuration structure, finds entities, tracks includes and secrets:
```bash
python3 {baseDir}/scripts/check_config.py /path/to/config/directory
python3 {baseDir}/scripts/check_config.py /path/to/config.yaml --verbose
```

### Lovelace Validator
Validates Lovelace dashboard configurations (YAML and JSON .storage format):
```bash
python3 {baseDir}/scripts/lovelace_validator.py /path/to/ui-lovelace.yaml
python3 {baseDir}/scripts/lovelace_validator.py /path/to/.storage/lovelace --strict
```
Features:
- Validates card types (built-in and custom)
- Checks entity ID formats
- Validates actions (tap_action, hold_action)
- Detects custom cards (HACS)
- Supports both YAML and JSON storage formats

### Duplicate Finder
Finds duplicate and similar automations/scripts across configuration files:
```bash
python3 {baseDir}/scripts/find_duplicates.py /path/to/config/directory
python3 {baseDir}/scripts/find_duplicates.py /path/to/automations.yaml --verbose
```
Features:
- Exact duplicate detection (identical triggers + actions)
- Similar item detection (80% threshold for names, entities, structure)
- Trigger conflict detection (multiple automations on same trigger)
- Entity overlap analysis between automations
- JSON output with detailed findings

## Pre-Save Validation Hook

This plugin includes a pre-save hook that automatically validates YAML files before saving. It checks for:
- Tab characters (HA requires spaces)
- Basic YAML syntax errors

The hook runs automatically on Write/Edit operations for `.yaml` and `.yml` files.

## YAML Requirements

- **Indentation**: 2 spaces per level (never tabs)
- **Strings**: Quote boolean-like values ("on", "off", "yes", "no")
- **Lists**: Use `-` prefix with proper indentation
- **Comments**: Use `#` for inline documentation
- **Key Terms**: Use `action:` (not `service:`), `triggers:` (not `trigger:`), `actions:` (not `action:` for sequences)

## File Organization

### Basic Includes
```yaml
# configuration.yaml
automation: !include automations.yaml
script: !include scripts.yaml
sensor: !include sensors.yaml
```

### Directory Includes
```yaml
# Merge all files in directory
automation: !include_dir_merge_list automations/
sensor: !include_dir_merge_list sensors/
```

### Secrets Management
```yaml
# secrets.yaml
mqtt_password: "super_secret_password"
api_key: "your-api-key-here"

# configuration.yaml
mqtt:
  password: !secret mqtt_password
```

## Automations (2024+ Syntax)

### Basic Structure
```yaml
automation:
  - alias: "Descriptive Name"
    id: unique_automation_id
    description: "What this automation does"
    mode: single  # single, restart, queued, parallel
    triggers:
      - trigger: state
        entity_id: binary_sensor.motion
        to: "on"
    conditions:
      - condition: time
        after: "sunset"
    actions:
      - action: light.turn_on
        target:
          entity_id: light.living_room
```

### Common Triggers

**State Trigger**
```yaml
triggers:
  - trigger: state
    entity_id: sensor.temperature
    from: "off"
    to: "on"
    for:
      minutes: 5
```

**Time Trigger**
```yaml
triggers:
  - trigger: time
    at: "07:00:00"
```

**Numeric State Trigger**
```yaml
triggers:
  - trigger: numeric_state
    entity_id: sensor.temperature
    above: 25
    below: 30
```

**Sun Trigger**
```yaml
triggers:
  - trigger: sun
    event: sunset
    offset: "-00:30:00"
```

**Template Trigger**
```yaml
triggers:
  - trigger: template
    value_template: "{{ states('sensor.power') | float > 1000 }}"
```

**Calendar Trigger**
```yaml
triggers:
  - trigger: calendar
    entity_id: calendar.work
    event: start
    offset: "-00:15:00"  # 15 min before event
```

**Device Trigger**
```yaml
triggers:
  - trigger: device
    device_id: abc123
    domain: zwave_js
    type: event.value_notification.entry_control
```

**Event Trigger**
```yaml
triggers:
  - trigger: event
    event_type: mobile_app_notification_action
    event_data:
      action: "CONFIRM_ACTION"
```

### Trigger IDs (for multi-trigger automations)
```yaml
triggers:
  - trigger: state
    id: "motion_detected"
    entity_id: binary_sensor.motion
    to: "on"
  - trigger: state
    id: "door_opened"
    entity_id: binary_sensor.door
    to: "on"
actions:
  - choose:
      - conditions:
          - condition: trigger
            id: "motion_detected"
        sequence:
          - action: light.turn_on
            target:
              entity_id: light.hallway
```

### Common Actions

**Service Call**
```yaml
actions:
  - action: light.turn_on
    target:
      entity_id: light.bedroom
    data:
      brightness_pct: 50
      color_temp: 350
```

**Delay**
```yaml
actions:
  - delay:
      seconds: 30
```

**Conditional (Choose)**
```yaml
actions:
  - choose:
      - conditions:
          - condition: state
            entity_id: sun.sun
            state: "below_horizon"
        sequence:
          - action: light.turn_on
            target:
              entity_id: light.porch
    default:
      - action: light.turn_off
        target:
          entity_id: light.porch
```

**Repeat**
```yaml
actions:
  - repeat:
      count: 3
      sequence:
        - action: notify.mobile_app
          data:
            message: "Alert!"
        - delay:
            minutes: 1
```

**If-Then-Else**
```yaml
actions:
  - if:
      - condition: state
        entity_id: sun.sun
        state: "below_horizon"
    then:
      - action: light.turn_on
        target:
          entity_id: light.porch
    else:
      - action: light.turn_off
        target:
          entity_id: light.porch
```

**Parallel Actions**
```yaml
actions:
  - parallel:
      - action: notify.person1
        data:
          message: "Alert sent simultaneously!"
      - action: notify.person2
        data:
          message: "Alert sent simultaneously!"
      - sequence:
          - action: light.turn_on
            target: