home-assistant-best-practices

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: home-assistant-best-practices
description: >
  Best practices for HA automations, helpers, scripts, controls, and dashboards.

  TRIGGER THIS SKILL WHEN:
  - Creating or editing automations, scripts, scenes, or dashboards
  - Choosing between template sensors and built-in helpers
  - Restructuring triggers, conditions, or automation modes
  - Setting up Zigbee button/remote automations
  - Renaming entities or migrating device_id to entity_id
  - Configuring dashboard cards or selecting helpers
  - Looking up card types or domain docs
  - Writing or reviewing AppDaemon apps
  - Authoring or editing reusable Blueprints

  SYMPTOMS:
  - Agent uses Jinja2 templates where native options exist
  - Agent uses device_id instead of entity_id
  - Agent changes entity IDs without checking consumers
  - Wrong automation mode
  - Agent hard-codes values or uses raw sensor over helper
  - Agent edits .storage, writes YAML, or generates YAML snippets
  - Agent tells user to edit configuration.yaml for UI integrations
  - Agent hardcodes entities in a Blueprint or uses free-text input over a selector
metadata:
  version: 16
---

# Home Assistant Best Practices

**Core principle:** Use native Home Assistant constructs wherever possible. Templates bypass validation, fail silently at runtime, and make debugging opaque.

## Decision Workflow

Follow this sequence when creating any automation:

### 0. Gate: modifying existing config?

If your change affects entity IDs or cross-component references — renaming entities, replacing template sensors with helpers, converting device triggers, or restructuring automations — read `references/safe-refactoring.md` first. That reference covers impact analysis, device-sibling discovery, and post-change verification. Complete its workflow before proceeding.

Steps 1-5 below apply to new config or pattern evaluation.

### 1. Check for a purpose-specific, then generic native, trigger/condition
Since 2026.7 the default building blocks are purpose-specific triggers/conditions — `<domain>.<name>` keys (motion detected, battery low, door opened) with area/floor/label targets. Check for one that matches the intent first, then a generic native trigger/condition, and only then a template. See `references/automation-patterns.md#purpose-specific-triggers--conditions-default-since-20267`.

**Common substitutions:**
- List of individual sensor entities in a trigger → one purpose-specific trigger with an area/floor/label `target:`
- `{{ states('x') | float > 25 }}` → `numeric_state` condition with `above: 25`
- `{{ is_state('x', 'on') and is_state('y', 'on') }}` → `condition: and` with state conditions
- `{{ now().hour >= 9 }}` → `condition: time` with `after: "09:00:00"`
- `wait_template: "{{ is_state(...) }}"` → `wait_for_trigger` with state trigger (caveat: different behavior when state is already true — see `references/safe-refactoring.md#trigger-restructuring`)

### 2. Check for built-in helper or Template Helper
Before creating a template sensor, check `references/helper-selection.md`.

**Common substitutions:**
- Sum/average multiple sensors → `min_max` integration
- Binary any-on/all-on logic → `group` helper
- Rate of change → `derivative` integration
- Cross threshold detection → `threshold` integration
- Consumption tracking → `utility_meter` helper

**If no built-in helper fits, use a Template Helper — not YAML.**
Create it via the HA config flow (MCP tool or API) or via the UI:
Settings → Devices & Services → Helpers → Create Helper → Template.
Only write `template:` YAML if explicitly requested or if neither path is available.

### 3. Select correct automation mode
Default `single` mode is often wrong. See `references/automation-patterns.md#automation-modes`.

| Scenario | Mode |
|----------|------|
| Motion light with timeout | `restart` |
| Sequential processing (door locks) | `queued` |
| Independent per-entity actions | `parallel` |
| One-shot notifications | `single` |

### 4. Use entity_id over