Home Assistant Alexa Skill — Complete Guide

In this tutorial, you'll learn about Home Assistant Alexa Skill. We cover key concepts, practical examples, and best practices.

Hook

You enable the Home Assistant Alexa Smart Home Skill in the Amazon Alexa app. It says "Skill enabled" but discovers no devices. Or discovery finds devices but they show "Not responding" when you ask Alexa to control them.

The Wrong Way

Using a self-signed SSL certificate for your Home Assistant URL causes Alexa to reject the connection — Alexa requires a valid, publicly-trusted certificate.

# BAD: Self-signed cert
# Using https://hass.local:8123 with a self-signed cert

Alexa Skill: "Unable to link Home Assistant"
SSL Error: Certificate not trusted by Amazon servers

Alexa's cloud backend must trust your SSL certificate. Self-signed certs are not trusted by any public certificate authority.

The Right Way

Expose Home Assistant with a valid SSL certificate (Let's Encrypt) and configure the Alexa skill properly.

# 1. Set up remote access with a valid domain and SSL
# Options: DuckDNS + Let's Encrypt add-on, Cloudflare Tunnel, or Nginx Proxy Manager

# 2. Enable the Alexa integration in configuration.yaml

alexa:
  smart_home:
    filter:
      include_domains:
        - light
        - switch
        - lock
      include_entity_globs:
        - sensor.temperature*
    entity_config:
      light.living_room:
        name: "Living Room Light"
        display_categories: "LIGHT"

# 3. Configure Cloud API (for Alexa to reach HA)
# Settings → Cloud → Alexa → Enable Smart Home Skill

# 4. Create a skill in the Alexa Developer Console
# https://developer.amazon.com/alexa/console/ask
# Smart Home skill → Account linking with Home Assistant Cloud

# 5. In the Alexa app:
# More → Skills & Games → Home Assistant → Enable
# Link account → enter HA credentials
# Discover devices

Discovery: 15 devices found
Alexa: "Alexa, turn on living room light" → Light turns on ✓

# 6. Troubleshoot "Not responding":
# Check the HA log for alexa errors
docker logs hass --tail 50 | grep -i "alexa"

Prevention

• Use Home Assistant Cloud (Nabu Casa) for the easiest Alexa setup — no SSL hassle.
• If self-hosting, use a valid Let's Encrypt certificate with DuckDNS or a custom domain.
• Expose only the minimum entities needed (use include_domains or include_entity_globs).
• Test entity control in Home Assistant first before exposing to Alexa.
• Keep the Nabu Casa subscription for hassle-free cloud connectivity.

Common Mistakes with assistant alexa skill

1. Mixing let bindings with <- bindings in do notation, producing type errors
2. Overlapping type class instances that cause GHC to reject the program with ambiguous dispatch errors
3. Non-exhaustive pattern matches that compile with warnings then crash at runtime

These mistakes appear frequently in real-world HOME code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ

DodaTech — Alexa smart home skill, actually smart.