Help us improve
Share bugs, ideas, or general feedback.
Manages Home Assistant YAML configurations: editing configuration.yaml, integrations setup, secrets management, packages organization, and troubleshooting errors.
npx claudepluginhub laurigates/claude-plugins --plugin home-assistant-pluginHow this skill is triggered — by the user, by Claude, or both
Slash command
/home-assistant-plugin:ha-configurationhaikuThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
| Use this skill when... | Use ha-automations instead when... |
Create and manage Home Assistant YAML configuration files including automations, scripts, templates, blueprints, Lovelace dashboards, and file organization. Use when working with Home Assistant configuration files (.yaml, .yml) or discussing HA automations, scripts, sensors, or dashboards.
Develops custom Home Assistant integrations including config flows, entities, platforms, manifest.json, and device registry. Prevents common errors in coordinators, async setup, and entity registration.
Provides best practices for Home Assistant automations, helpers, scripts, and dashboards. Guides on avoiding templates, using native constructs, and safe refactoring.
Share bugs, ideas, or general feedback.
| 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 |
| 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 |
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.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
| 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 |
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') }}
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 }}"
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:
- 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_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
# 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
| 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:
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:
default: warning
logs:
homeassistant.core: info
homeassistant.components.mqtt: debug
custom_components.my_integration: debug
# Reduce noise
homeassistant.components.websocket_api: error
# 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
| 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 |
| 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) |
| 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'))" |