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 — 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: 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. 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 claude plugin update home-assistant-skills from a shell, then /reload-plugins.

Claude Desktop / claude.ai

Both apps share the same Customize UI, reached via the left sidebar (Claude Desktop) or claude.ai/customize (browser).

1. Enable code execution: Settings → Capabilities → turn on Cloud code execution and file creation (required for skills)
2. Customize → Plugins → Add → Add marketplace → Add from a repository
3. 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.

<details>
<summary>Alternative: upload the skill manually as a zip</summary>

1. Enable code execution: Settings → Capabilities → turn on Cloud code execution and file creation (required for skills)
2. Download or clone this repository
3. Zip the skill folder: cd skills && zip -r home-assistant-best-practices.zip home-assistant-best-practices/
4. Customize → Skills → Add → Upload a skill

</details>

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:

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