Agent Skills: Home Assistant Knowledge Patch

Home Assistant Knowledge Patch

Use this skill when configuring, upgrading, automating, extending, or troubleshooting a current Home Assistant installation. Start with the migration checks below, then open the task-specific reference before changing YAML, entity assumptions, integrations, dashboards, backups, or custom code.

Reference index

| Reference | Topics | | --- | --- | | Assist, Voice, and AI | Assist pipelines, satellites, speech, conversation agents, AI Tasks, and intents | | Automations, Scripts, and Templates | Triggers, conditions, actions, variable scope, templates, helpers, selectors, and editors | | Backups, Installation, and System Operations | Backup encryption and retention, restore, supported installations, Apps, runtime, networking, and updates | | Breaking Changes and Migrations | Removed APIs and entities, renamed states, unit changes, minimum versions, defaults, and patch corrections | | Dashboards and User Interface | Built-in dashboards, cards, pickers, Activity, energy views, search, and navigation | | Custom Integration and Frontend Development | Config flows, entity APIs, discovery, services, selectors, frontend interfaces, and custom panels | | Integrations, Devices, and Protocols | Integrations, device capabilities, actions, sensors, Matter, MQTT, Z-Wave, KNX, ESPHome, IR, RF, and Bluetooth |

Upgrade triage

Before an upgrade or migration:

1. Create and verify a restorable backup, including its encryption key and all configured destination uploads.
2. Confirm that the installation method, CPU architecture, container runtime, integrations, device firmware, and protocol servers remain supported.
3. Search YAML, templates, dashboards, and exported state consumers for removed fields, old service data, renamed states, exact units, and device IDs.
4. Inspect Repairs after startup; several device, backup, entity, and mapping migrations deliberately surface there.
5. Reauthenticate or reconfigure integrations whose login method, API, server minimum, or setup flow changed.
6. Run representative automations and inspect traces, especially flows using nested variables, response data, labels, Supervisor actions, or exact states.
7. Review disabled-by-default replacement entities before deleting compatibility templates or legacy references.

Open Breaking Changes and Migrations for the complete migration inventory rather than treating these checks as exhaustive.

Installation and backup essentials

• Home Assistant OS and Container are the supported installation paths. Core, Supervised, and the retired 32-bit architectures do not receive updates or security fixes.
• Current container images use zstd; an old Docker or containerd runtime may fail before Home Assistant starts.
• Backups use a mandatory encryption key by default. Preserve the emergency kit: a stored encrypted backup is not useful without the key.
• Retention is destination-specific. Automatic cleanup does not delete manual backups, but update backups and scheduled backups have their own retention behavior.
• A backup can finish creation while uploads are still running. Check each location's upload status before restarting, replacing hardware, or removing the source installation.
• A requested restart waits for an active backup, while Supervisor action failures now stop scripts unless the action explicitly permits continuation.
• Home Assistant OS calls managed sidecar software Apps. Do not confuse an App, which runs alongside Core, with an integration, which connects devices or services to Home Assistant.

See Backups, Installation, and System Operations for location behavior, restore paths, update safeguards, logging, and web-server configuration.

High-impact YAML and entity migrations

Use Kelvin color temperature

Light actions and state consumers should use:

actions:
  - action: light.turn_on
    target:
      entity_id: light.desk
    data:
      color_temp_kelvin: 3000

Do not rely on mired-based color_temp, min_mireds, or max_mireds fields. Use min_color_temp_kelvin and max_color_temp_kelvin where limits matter.

Use modern template configuration

Legacy template platforms under domain keys have been removed. Define supported template entities beneath template: and account for explicit unknown and unavailable behavior. In particular, returning None is not equivalent to a false or off state for binary sensors and fans.

Update MQTT configuration

• Put templates directly in mqtt.publish topic and payload; the old topic_template and payload_template fields are gone.
• Use default_entity_id instead of the removed MQTT object_id option.
• Modern MQTT setup and tools live on the integration's Configure page; broker reconfiguration is in the integration-entry context menu.
• Migrate old JSON-light color-mode parameters and legacy platform assumptions.

Treat machine states as machine data

Many integrations moved display-oriented values to lowercase snake case, split attributes into dedicated entities, or changed off, standby, unknown, and unavailable semantics. Prefer stable entity capabilities and translated UI labels for presentation. Audit every exact string comparison after an upgrade.

Read battery sensors

Vacuum and device-tracker battery properties have broadly moved to dedicated battery sensor entities. Cards, templates, automations, and scripts should target those sensors instead of entity attributes or platform properties.

Review device targets

Sub-devices and one-device-per-integration ownership can change registry device IDs while preserving entity IDs. Prefer entity, area, or label targets when they match the intent, and repair device-ID-based targets after a registry split.

Automation guidance

• Purpose-specific triggers and conditions are the editor default. Generic state triggers, templates, existing automations, and YAML still work.
• Purpose-specific blocks understand relevant unknown, unavailable, target, repeated-event, and cross-domain semantics. Recreate preview-era blocks whose keys or target behavior changed.
• A label target can include configuration and diagnostic entities. Expand and audit broad targets before invoking actions with side effects.
• Nested variables, wait, and response_variable results can propagate to an outer script-run scope. Do not depend on former local shadowing.
• Response actions and AI Tasks should always store their result in a named response variable before templates consume returned fields.
• Use continue_on_error: true only where proceeding after a failed action is an intentional workflow decision.
• Time triggers can use weekdays, datetime-helper triggers can use offsets, and purpose-specific state checks can require a duration.
• Automation and script notes survive duplication, export, and blueprint use; use them to record non-obvious target and failure behavior.

Open Automations, Scripts, and Templates before rewriting templates, selectors, helper-driven triggers, or editor-produced YAML.

Frequently used capabilities

Ask, generate, and continue conversations

Assist satellites can announce, start a conversation, and ask a question whose matched answer and slots return to an automation. AI Task entities can generate text, selector-defined structured data, or images from instructions and media attachments. A configured default AI Task entity allows reusable calls to omit the provider entity.

Conversation systems can stream responses, call tools, use exposed calendar or to-do context, and continue listening after a question. Exposure and diagnostic views matter: verify which entities, prompts, tools, arguments, and results enter the conversation.

See Assist, Voice, and AI for action shapes, satellite behavior, speech features, intents, and provider-specific changes.

Clean mapped areas

Supported vacuums can map their segments to Home Assistant areas and use vacuum.clean_area from automations or voice. Refresh mappings when a Repair reports that the segment layout changed. Template vacuums can expose compatible room segments and cleaning actions too.

Use native infrared and radio-frequency proxies

Device integrations can select native IR or RF transmitters supplied by ESPHome, Broadlink, or other supported integrations. A transmitter alone does not provide an appliance protocol; the corresponding device integration must implement it. IR receiver event entities can also turn original remote commands into automation events.

Model current energy and utility flow

Energy configuration accepts cumulative energy plus live power, signed flow or separate import/export sensors, parent-child meters, downstream water meters, and battery capacity and state-of-charge data. Configure device hierarchy and battery capacity to avoid double counting and misleading aggregate charge percentages.

Prefer entity-backed controls

Many former attributes and integration actions now have sensor, event, button, switch, select, number, update, notification, or siren entities. Entity-backed controls improve discoverability and targeting, but may require enabling a new entity and migrating exact references.

Open Integrations, Devices, and Protocols for device coverage and protocol details.

Dashboard and UI guidance

• Overview and the other built-in dashboards derive organization from areas, floors, labels, favorites, and primary sensors. Correct registry organization before compensating with card-specific configuration.
• Sections support backgrounds, spacing, auto height, sticky footers, strategies, and richer card interactions. Theme overrides may be needed where defaults changed.
• Energy, Activity, protocol, Maintenance, Security, and device-management views expose operational detail that previously required custom cards or developer tools.
• Target pickers show expanded entities for floors, areas, devices, and labels. Use that preview to audit broad actions and visibility conditions.
• Quick search covers navigation, commands, entities, devices, and areas; editor tooling adds YAML linting, Jinja completion, hover values, and full-screen views.

See Dashboards and User Interface before migrating an Areas or Home dashboard, changing card layouts, or relying on old navigation.

Custom integration checklist

• Validate imports for moved discovery models and removed typed-dictionary fields.
• Treat frozen core dataclasses as immutable and use current entity descriptions, features, units, and device classes.
• Migrate deprecated service registration helpers, device-tracker APIs, config entry listeners, trigger initialization flags, and platform-mismatched IDs.
• Do not assume one registry device can remain attached to multiple config entries.
• Test config-entry reconfiguration, unique IDs, subentries, backup-agent progress, OAuth errors, webhook reconfiguration, and update-coordinator retries.
• Update frontend cards and custom panels for current typography, safe-area, selector, dashboard-strategy, and entity-suggestion interfaces.

Open Custom Integration and Frontend Development for the detailed API and frontend migration notes.