home-assistant-best-practices

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

AGENTS.md

evals/AGENTS.md

Audit 0.4.1 · source sha 801c5cb3ac27 · 20 Oct 2026Report an issue or request a re-scan

• Publisherhomeassistant-ai GitHub organizationOwner of the repository this skill is read from
• Source folderhomeassistant-ai/skills/skills/home-assistant-best-practicesThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict801c5cb3ac27A new audit runs when the source changes
• Repository statusNot archivedLast push 2 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Home Assistant (HA) best practices. Load first, before answering or exploring, on any HA request.

---
name: home-assistant-best-practices
description: >
  Home Assistant (HA) best practices. Load first, before answering or exploring, on any HA request.

  TRIGGER THIS SKILL WHEN:
  - Creating or editing automations, scripts, scenes, dashboards, blueprints
  - Choosing template sensors, helpers, or Jinja macros
  - Restructuring triggers, conditions, or modes; button, remote, or event-entity automations
  - Renaming entities or migrating device_id to entity_id
  - Looking up card types or domain docs; writing AppDaemon apps
  - Deleting or restoring a backup, or upgrading Core or the OS

  SYMPTOMS:
  - Jinja2 templates where native options exist
  - device_id used instead of entity_id
  - Entity IDs changed without checking consumers
  - Wrong automation mode chosen
  - Raw sensor or hard-coded value used where a helper belongs
  - Direct .storage edits or automation lookups there; generated YAML
  - User told to edit configuration.yaml for UI integrations
  - Hardcoded Blueprint entities or skipped selectors
  - Existing state changed with no recovery path
  - Jinja copy-pasted between templates
metadata:
  version: "51"
---

# Home Assistant Best Practices

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

**No tool reaches the HA API?** Do not stop to ask for access. If you can drive a browser on the HA web UI, make the change there, but first show the user the exact change and wait for their OK before you save: approving a click does not show them what it writes. Otherwise give the user the complete config to create in the UI (for an automation, the YAML for the editor's **Edit in YAML** mode; for a helper, its form fields), and name the entity IDs you assumed. Config that can only be written in YAML is edited with the File editor app (or in the config folder on a Container install): keep a copy of the file first, then check the configuration and run the matching reload in the **YAML** tab of **Tools** (named **Developer Tools** before 2026.8; restart if it isn't listed).

**A feature marked with a release (2026.5+) depends on the instance's version.** Read it before choosing: `version` in `GET /api/config`, or **Settings → About** in the UI. On that release or later, use the feature and do not offer the older way as an equal choice. If you cannot read the version, assume a current release and name the older fallback with the version it needs.

**Read the matching reference before you answer.** This page only summarizes the files in [Reference Files](#reference-files); the exact keys, fields and working examples are in them. Read every file whose row matches the task, and only those: do not load all reference files upfront.

## Decision Workflow

Follow this sequence when creating any automation:

### 0. Gate: modifying existing config?

If your change affects entity IDs, display names, or cross-component references — renaming entities or devices, replacing template sensors with helpers, converting device triggers, or restructuring automations — read [safe-refactoring](references/safe-refactoring.md) first. That reference covers impact analysis, device-sibling discovery, display-name overrides, 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. Read [triggers-and-conditions #purpose-specific-triggers--conditions-default-since-20267](references/triggers-and-conditions.md#purpose-specific-triggers--conditions-default-since-20267) before writing the trigger.

A purpose-specific trigger takes `entity_id` in its `target:` as well, so one known sensor is not a reason to fall back to `trigger: state`. Write the automation with the purpose-specific trigger; do not offer it only as an optional upgrade.

**Common substitutions:**
- `trigger: state` on a motion, occupancy or door `binary_sensor` → `motion.detected`/`motion.cleared`, `occupancy.detected`/`occupancy.cleared` or `door.opened`/`door.closed` with `target: {entity_id: ...}`, or `area_id` when the area is known
- List of individual sensor entities in a trigger → one purpose-specific trigger with an area/floor/label `target:`
- `delay` after `motion.detected` for "no motion anywhere for N minutes" → `motion.cleared` with `options: {behavior: all, for: ...}`, which fires once every targeted sensor has been clear that long (`unavailable` and `unknown` sensors are left out of the count)
- `{{ 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"`

### 2. Check for built-in helper or Template Helper
Read [helper-selection](references/helper-selection.md) before creating a template sensor.

**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 (programmatically or in the UI:
Settings → Devices & Services → Helpers → Create Helper → Template). A flow-created helper
is UI-editable; a `template:` YAML entry needs a `template.reload` and is not.

Write `template:` YAML when the user asks for it, when neither path is available, or when
the config needs a key the flow has no field for — trigger-base

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/homeassistant-ai/skills
git -C skills checkout 801c5cb3ac27

Works in

1. 2026-10-20
   ✓SAFE B 89 / 100

   first audit · source 801c5cb3ac27

Questions about home-assistant-best-practices

• github.com/homeassistant-ai/skills/tree/main/skills/home-assista — the audited source at commit 801c5cb3ac27 and every finding aboveObserved · 20 Oct 2026

Spotted something wrong? Report a correction · Methodology