claude-skills/skills/homeassistant/SKILL.md

name, description

name

description

homeassistant

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:

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:

python3 scripts/list_entities.py --url http://homeassistant.local:8123 --token YOUR_TOKEN

Get specific entity state:

python3 scripts/api_client.py --url http://homeassistant.local:8123 --token YOUR_TOKEN get-state light.living_room

Control a device:

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:

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:

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:

python3 scripts/validate_yaml.py configuration.yaml

Validate automation configuration:

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:

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:

   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:

   python3 scripts/list_entities.py --domain light
   

2. Check current state:

   python3 scripts/api_client.py get-state light.living_room
   

3. List available services for domain:

   python3 scripts/list_services.py --domain light
   

4. Call service:

   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:

   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:

   python3 scripts/api_client.py get-error-log
   

4. Verify entity IDs exist:

   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