Agent Skills: Home Assistant Configuration

Home Assistant Configuration

When to Use This Skill

| Use this skill when... | Use ha-automations instead when... | |------------------------|-----------------------------------| | Editing configuration.yaml | Creating automation rules | | Setting up integrations | Writing automation triggers/actions | | Managing secrets.yaml | Debugging automation logic | | Organizing with packages | Working with automation blueprints | | Troubleshooting config errors | Setting up device triggers |

Core Configuration Files

| File | Purpose | |------|---------| | configuration.yaml | Main configuration entry point | | secrets.yaml | Sensitive values (passwords, API keys, tokens) | | automations.yaml | Automation rules (usually UI-managed) | | scripts.yaml | Reusable script sequences | | scenes.yaml | Scene definitions | | customize.yaml | Entity customizations | | packages/*.yaml | Modular configuration packages |

Configuration Structure

Basic configuration.yaml

homeassistant:
  name: Home
  unit_system: metric
  time_zone: Europe/Helsinki
  currency: EUR
  country: FI

  # External files
  customize: !include customize.yaml
  packages: !include_dir_named packages/

# Core integrations
default_config:

# Text-to-speech
tts:
  - platform: google_translate

automation: !include automations.yaml
script: !include scripts.yaml
scene: !include scenes.yaml

Secrets Management

secrets.yaml:

# API keys
openweathermap_api_key: "abc123def456"
spotify_client_id: "your_client_id"
spotify_client_secret: "your_client_secret"

# Database
recorder_db_url: "postgresql://user:pass@localhost/hass"

# MQTT
mqtt_username: "homeassistant"
mqtt_password: "secure_password"

# Network
latitude: 60.1699
longitude: 24.9384

Reference in configuration.yaml:

weather:
  - platform: openweathermap
    api_key: !secret openweathermap_api_key

recorder:
  db_url: !secret recorder_db_url

Include Directives

| Directive | Description | Example | |-----------|-------------|---------| | !include | Include single file | !include automations.yaml | | !include_dir_list | Include files as list items | !include_dir_list sensors/ | | !include_dir_named | Include files as named mappings | !include_dir_named packages/ | | !include_dir_merge_list | Merge files into single list | !include_dir_merge_list automations/ | | !include_dir_merge_named | Merge files into single mapping | !include_dir_merge_named integrations/ | | !secret | Reference from secrets.yaml | !secret api_key | | !env_var | Environment variable | !env_var DB_PASSWORD |

Package Organization

Packages allow modular configuration by domain:

packages/climate.yaml:

climate_package:
  sensor:
    - platform: template
      sensors:
        average_indoor_temp:
          friendly_name: "Average Indoor Temperature"
          unit_of_measurement: "°C"
          value_template: >-
            {{ (states('sensor.living_room_temp') | float +
                states('sensor.bedroom_temp') | float) / 2 | round(1) }}

  automation:
    - alias: "Climate - AC Auto Off"
      trigger:
        - platform: numeric_state
          entity_id: sensor.average_indoor_temp
          below: 22
      action:
        - service: climate.turn_off
          target:
            entity_id: climate.living_room_ac

  script:
    climate_cool_down:
      alias: "Cool Down House"
      sequence:
        - service: climate.set_temperature
          target:
            entity_id: climate.living_room_ac
          data:
            temperature: 20
            hvac_mode: cool

packages/presence.yaml:

presence_package:
  input_boolean:
    guest_mode:
      name: "Guest Mode"
      icon: mdi:account-multiple

  binary_sensor:
    - platform: template
      sensors:
        anyone_home:
          friendly_name: "Anyone Home"
          device_class: presence
          value_template: >-
            {{ is_state('person.user1', 'home') or
               is_state('person.user2', 'home') or
               is_state('input_boolean.guest_mode', 'on') }}

Common Integration Patterns

MQTT Configuration

mqtt:
  broker: !secret mqtt_broker
  port: 1883
  username: !secret mqtt_username
  password: !secret mqtt_password
  discovery: true
  discovery_prefix: homeassistant

  sensor:
    - name: "Outdoor Temperature"
      state_topic: "sensors/outdoor/temperature"
      unit_of_measurement: "°C"
      device_class: temperature
      value_template: "{{ value_json.temperature }}"

REST Sensors

sensor:
  - platform: rest
    name: "GitHub Stars"
    resource: https://api.github.com/repos/home-assistant/core
    value_template: "{{ value_json.stargazers_count }}"
    scan_interval: 3600
    headers:
      Authorization: !secret github_token

Template Sensors

template:
  - sensor:
      - name: "Sun Elevation"
        unit_of_measurement: "°"
        state: "{{ state_attr('sun.sun', 'elevation') | round(1) }}"

      - name: "Daylight Hours"
        unit_of_measurement: "hours"
        state: >-
          {% set sunrise = as_timestamp(state_attr('sun.sun', 'next_rising')) %}
          {% set sunset = as_timestamp(state_attr('sun.sun', 'next_setting')) %}
          {{ ((sunset - sunrise) / 3600) | round(1) }}

  - binary_sensor:
      - name: "Workday"
        state: "{{ now().weekday() < 5 }}"

Input Helpers

input_boolean:
  vacation_mode:
    name: "Vacation Mode"
    icon: mdi:airplane

input_number:
  target_temperature:
    name: "Target Temperature"
    min: 16
    max: 28
    step: 0.5
    unit_of_measurement: "°C"
    icon: mdi:thermometer

input_select:
  house_mode:
    name: "House Mode"
    options:
      - Home
      - Away
      - Sleep
      - Guest
    icon: mdi:home

input_text:
  notification_message:
    name: "Custom Notification"
    max: 255

input_datetime:
  alarm_time:
    name: "Alarm Time"
    has_date: false
    has_time: true

Configuration Validation

Check Configuration

# Docker/Container
docker exec homeassistant hass --script check_config

# Home Assistant OS
ha core check

# Supervised
hassio homeassistant check

# Python venv
hass --script check_config -c /path/to/config

Common Validation Errors

| Error | Cause | Fix | |-------|-------|-----| | found undefined alias | Missing !secret value | Add to secrets.yaml | | could not determine a constructor | Invalid YAML syntax | Check indentation | | duplicate key | Same key defined twice | Remove duplicate | | Platform not found | Missing integration | Install via UI/HACS |

Recorder Configuration

recorder:
  db_url: !secret recorder_db_url
  purge_keep_days: 10
  commit_interval: 1

  exclude:
    domains:
      - automation
      - updater
    entity_globs:
      - sensor.weather_*
    entities:
      - sun.sun
      - sensor.date

  include:
    domains:
      - sensor
      - binary_sensor
      - switch

Logger Configuration

logger:
  default: warning
  logs:
    homeassistant.core: info
    homeassistant.components.mqtt: debug
    custom_components.my_integration: debug
    # Reduce noise
    homeassistant.components.websocket_api: error

Lovelace Dashboard (YAML Mode)

# configuration.yaml
lovelace:
  mode: yaml
  resources:
    - url: /hacsfiles/button-card/button-card.js
      type: module
  dashboards:
    lovelace-home:
      mode: yaml
      filename: dashboards/home.yaml
      title: Home
      icon: mdi:home
      show_in_sidebar: true

Quick Reference

YAML Tips

| Pattern | Example | |---------|---------| | Multi-line string | value: >- or value: \|- | | List item | - item | | Inline list | [item1, item2] | | Comment | # comment | | Anchor | &anchor_name | | Reference | *anchor_name | | Merge | <<: *anchor_name |

Template Syntax

| Function | Example | |----------|---------| | State value | states('sensor.temp') | | State attribute | state_attr('sun.sun', 'elevation') | | Convert to float | states('sensor.temp') \| float | | Round | value \| round(1) | | Default value | states('sensor.x') \| default('unknown') | | Timestamp | as_timestamp(now()) | | Time delta | now() - timedelta(hours=1) |

Agentic Optimizations

| Context | Command | |---------|---------| | Validate config | docker exec homeassistant hass --script check_config 2>&1 \| head -50 | | Find entity usage | grep -r "entity_id:" config/ --include="*.yaml" | | Find secret refs | grep -r "!secret" config/ --include="*.yaml" | | List packages | ls -la config/packages/ | | Check YAML syntax | python3 -c "import yaml; yaml.safe_load(open('file.yaml'))" |