Home Assistant Agent Skills
An Agent Skill is a portable Markdown knowledge pack that teaches AI coding agents best practices for a specific technology. This repository provides one for Home Assistant, following the open Agent Skills standard. Install it and your agent applies Home Assistant best practices in every session.
Included Skill
home-assistant-best-practices — a decision workflow and anti-pattern table in SKILL.md, backed by reference files the agent loads on demand. It covers:
- Authoring — native triggers and conditions over templates, helper selection, automation modes, device control and button/remote patterns, scenes, blueprints
- Dashboards — layout, views, cards, badges, custom cards
- Operations — YAML-only integration management, backups and recovery, safe refactoring of existing config
- AppDaemon — when to use it over native HA, and how to structure apps
Agents make a predictable set of mistakes with Home Assistant config — Jinja templates where a native trigger, condition, or helper exists, device_id where entity_id belongs, mode: single on a motion light, renames that silently break dashboards and scripts — and the anti-pattern table names each one with its fix. A typical entry:
# Without the skill: a template condition. HA checks only the Jinja syntax when the automation loads
condition: template
value_template: "{{ states('sensor.living_room_temperature') | float > 25 }}"
# With the skill: a native condition. HA checks every key, the entity ID format and the threshold when it loads
condition: numeric_state
entity_id: sensor.living_room_temperature
above: 25
See Skill Contents for the file-by-file map.
Installation
Agent Skills installer
Requires Node.js 22.20+.
npx skills add homeassistant-ai/skills
Works with AI coding agents that support the Agent Skills standard: Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and 70+ others. It installs into the current project; add -g to install it for all projects. To update: npx skills update
Claude Code plugin
Claude Code also accepts the installer above, which places the skill files in your .claude/skills/ directory. The commands below install it as a plugin instead, kept in Claude Code's own plugin cache.
Run each command separately inside Claude Code:
/plugin marketplace add homeassistant-ai/skills
/plugin install home-assistant-skills@home-assistant-skills
Run /reload-plugins or restart Claude Code for the skill to take effect.
Auto-update is off by default for third-party marketplaces. To turn it on, run /plugin, open Marketplaces, choose home-assistant-skills, and select Enable auto-update. To update by hand instead, run /plugin, open Marketplaces, choose home-assistant-skills, and select Update marketplace, then run /reload-plugins. From a shell, run these, then /reload-plugins or restart Claude Code:
claude plugin marketplace update home-assistant-skills
claude plugin update home-assistant-skills@home-assistant-skills
Claude Desktop / claude.ai
Both apps share the same Customize UI, reached via the left sidebar (Claude Desktop) or claude.ai/customize (browser).
- Enable code execution: Settings → Capabilities → turn on Cloud code execution and file creation (required for skills)
- Customize → Plugins → Add → Add marketplace → Add from a repository
- Select or enter
homeassistant-ai/skills (or the full URL, https://github.com/homeassistant-ai/skills) → Sync
This installs the skill as a plugin synced from this repo — no download or zip needed. Sync automatically is on by default, so later updates arrive on their own. To pull an update at once, open Add → Manage marketplaces, then the marketplace's menu → Check for updates.
- Enable code execution: Settings → Capabilities → turn on Cloud code execution and file creation (required for skills)
- Download or clone this repository
- Zip the skill folder:
cd skills && zip -r home-assistant-best-practices.zip home-assistant-best-practices/
- Customize → Skills → Add → Upload skill
Usage
Once installed, the skill loads on its own whenever the agent works on automations, scripts, scenes, helpers, dashboards, blueprints, or backups — it needs no explicit invocation. Try:
Create an automation that turns on the hallway light when motion is detected and turns it off five minutes after the motion stops.
Skill Contents
The home-assistant-best-practices skill includes:
| File | Purpose |
|---|
SKILL.md | Decision workflow, anti-pattern table, and pointers to the reference files below |
references/safe-refactoring.md | Safe workflow for renaming entities and their display names, replacing helpers, restructuring automations; display-name override, config-entry, and storage-dashboard blind spots |
references/triggers-and-conditions.md | Purpose-specific and native triggers/conditions, for: durations, trigger IDs |
references/automation-actions.md | Waits, variables, automation modes, control flow (choose, repeat, parallel), error handling (continue_on_error, admin-only actions), disabling automations, measuring elapsed time via last_triggered, Mobile App notify action vs entity, trace retention |
references/helper-selection.md | Built-in helpers vs template sensors (with decision matrix) |
references/template-guidelines.md | When to use templates, when to avoid them, template sensor best practices, reusable custom_templates macros |
|
Contributing
See CONTRIBUTING.md for guidelines on writing and submitting skills.
Skill misled your agent? Open an issue with the Report Bad Skill Advice template and let the agent fill it in — it holds the context to trace the failure to its source in the skill.
License
MIT
