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.
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 — template condition: a typo or wrong entity ID surfaces only when it runs
condition: template
value_template: "{{ states('sensor.living_room_temperature') | float > 25 }}"
# With the skill — native condition: config validated when the automation loads
condition: numeric_state
entity_id: sensor.living_room_temperature
above: 25See Skill Contents for the file-by-file map.
Requires Node.js 22.20+.
npx skills add homeassistant-ai/skillsWorks with AI coding agents that support the Agent Skills standard: Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and 70+ others. To update: npx skills update
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 claude plugin update home-assistant-skills from a shell, then /reload-plugins.
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.
Alternative: upload the skill manually as a zip
- 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 a skill
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.
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, replacing helpers, restructuring automations; config-entry and storage-dashboard blind spots |
references/automation-patterns.md |
Purpose-specific and native triggers/conditions, waits, variables, automation modes, control flow (choose, repeat, parallel), disabling automations |
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 |
references/yaml-only-integrations.md |
YAML-only integration types, post-edit actions (reload vs restart) |
references/device-control.md |
Actions and targeting, entity_id vs device_id, buttons and remotes, domain-specific patterns |
references/scenes.md |
Scene authoring: config shape, snapshot/restore, snapshot-vs-script distinction |
references/dashboard-guide.md |
Dashboard layout, view types, strategies, sections, cards, badges, custom cards, CSS styling, HACS |
references/dashboard-cards.md |
Card type lookup and card-specific documentation |
references/domain-docs.md |
Integration and domain documentation (actions, entity attributes); doc pages for specific triggers, conditions, and actions |
references/examples.yaml |
Compound examples combining multiple best practices |
references/appdaemon.md |
AppDaemon apps: when to use vs. native HA, app structure, actions, scheduling, error handling, safe refactoring impact |
references/blueprint-guide.md |
Blueprint authoring: metadata & source_url, inputs & selectors, target vs entity, defaults, !input templating, versioning |
references/backups.md |
Full instance backups vs rolling one object back, when an operation needs a backup first, what an archive contains, encryption keys, restore verification, backup deletion |
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.
MIT