Agent skill

ha-operations

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/ha-operations

SKILL.md

Home Assistant Operations

Quick Start

Check if Home Assistant is healthy:

bash
# ✅ CORRECT: Use GET request
curl -s https://ha.temet.ai/ | grep "Home Assistant"

# ❌ WRONG: HEAD returns 405 (but this is expected behavior, not an error!)
curl -I https://ha.temet.ai/
# Returns: HTTP/2 405 Method Not Allowed - THIS IS NORMAL

Send a notification:

bash
source /Users/dawiddutoit/projects/play/network-infrastructure/.env

curl -X POST "${HA_BASE_URL}/api/services/notify/${HA_NOTIFY_SERVICE#*.}" \
  -H "Authorization: Bearer ${HA_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Test from infrastructure monitoring",
    "title": "Infrastructure Alert"
  }'

When to Use

Triggers:

  • "Interact with Home Assistant"
  • "Call HA service"
  • "Send HA notification"
  • "Check HA health"
  • "Home Assistant returns 405"
  • "HA health check failing"

Key Concepts

The 405 Situation

Home Assistant does NOT support HEAD requests. It returns HTTP 405 Method Not Allowed for HEAD, which is EXPECTED and NORMAL behavior.

Correct Health Check:

bash
# ✅ Use GET and check content
curl -s https://ha.temet.ai/ --max-time 5 | grep "Home Assistant"

Operations

API Access

Create long-lived token in HA UI → Profile → Long-Lived Access Tokens

Store in .env:

bash
HA_ACCESS_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
HA_BASE_URL=http://192.168.68.123:8123
HA_NOTIFY_SERVICE=notify.mobile_app_your_phone

Send Notifications

bash
curl -X POST "${HA_BASE_URL}/api/services/notify/${HA_NOTIFY_SERVICE#*.}" \
  -H "Authorization: Bearer ${HA_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"message": "Alert text", "title": "Title"}'

Call Services

bash
# General pattern
curl -X POST "${HA_BASE_URL}/api/services/<domain>/<service>" \
  -H "Authorization: Bearer ${HA_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "entity.name"}'

# Trigger automation
curl -X POST "${HA_BASE_URL}/api/services/automation/trigger" \
  -H "Authorization: Bearer ${HA_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "automation.infrastructure_alert_handler"}'

Read Entity States

bash
# Specific entity
curl -s "${HA_BASE_URL}/api/states/sensor.temperature" \
  -H "Authorization: Bearer ${HA_ACCESS_TOKEN}" | jq .

# All entities
curl -s "${HA_BASE_URL}/api/states" \
  -H "Authorization: Bearer ${HA_ACCESS_TOKEN}" | jq .

Supporting Files

File Purpose
references/api-endpoints.md Complete HA REST API endpoint reference

Requirements

  • Home Assistant running at 192.168.68.123:8123
  • Long-lived access token
  • Environment variables: HA_BASE_URL, HA_ACCESS_TOKEN, HA_NOTIFY_SERVICE
  • Tools: curl, jq (optional)

Red Flags

  • Do not use HEAD requests (always returns 405)
  • Do not assume 405 means HA is broken
  • Do not expose access tokens in logs
  • Do not hardcode tokens in scripts (use .env)
  • Do not skip token creation

Common Issues

Symptom Cause Fix
HTTP 405 Used HEAD instead of GET Use GET
401 Unauthorized Invalid token Verify token, recreate
404 Not Found Wrong entity_id Check entity exists
Connection refused HA not running Check HA server
No notification Wrong service name Verify HA_NOTIFY_SERVICE

Didn't find tool you were looking for?

Be as detailed as possible for better results