home-assistant-best-practices by homeassistant-ai/skills
npx skills add https://github.com/homeassistant-ai/skills --skill home-assistant-best-practices核心原则: 尽可能使用原生的 Home Assistant 结构。模板会绕过验证,在运行时静默失败,并使调试变得不透明。
创建任何自动化时,请遵循以下顺序:
如果你的更改影响实体 ID 或跨组件引用——例如重命名实体、用辅助工具替换模板传感器、转换设备触发器或重构自动化——请先阅读 references/safe-refactoring.md。该参考文档涵盖了影响分析、设备兄弟节点发现和更改后验证。在继续之前,请完成其工作流。
下面的步骤 1-5 适用于新配置或模式评估。
在编写任何模板之前,请检查 references/automation-patterns.md 以寻找原生替代方案。
常见替换:
{{ states('x') | float > 25 }} → 使用 above: 25 的 numeric_state 条件{{ is_state('x', 'on') and is_state('y', 'on') }} → 包含状态条件的 广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
condition: and{{ now().hour >= 9 }} → 使用 after: "09:00:00" 的 condition: timewait_template: "{{ is_state(...) }}" → 使用状态触发器的 wait_for_trigger(注意:当状态已经为真时行为不同——参见 references/safe-refactoring.md#trigger-restructuring)在创建模板传感器之前,请检查 references/helper-selection.md。
常见替换:
min_max 集成group 辅助工具derivative 集成threshold 集成utility_meter 辅助工具如果没有合适的内置辅助工具,请使用模板辅助工具——而不是 YAML。 通过 HA 配置流程(MCP 工具或 API)或通过 UI 创建它:设置 → 设备与服务 → 辅助工具 → 创建辅助工具 → 模板。只有在明确要求或两种路径都不可用时,才编写 template: YAML。
默认的 single 模式通常是错误的。参见 references/automation-patterns.md#automation-modes。
| 场景 | 模式 |
|---|---|
| 带超时的运动感应灯 | restart |
| 顺序处理(门锁) | queued |
| 每个实体的独立操作 | parallel |
| 一次性通知 | single |
当设备被重新添加时,device_id 会失效。参见 references/device-control.md。
例外: Zigbee2MQTT 自动发现的设备触发器是可以接受的。
device_ieee(持久性)的 event 触发器device 触发器(自动发现)或 mqtt 触发器参见 references/device-control.md#zigbee-buttonremote-patterns。
| 反模式 | 替代方案 | 原因 | 参考 |
|---|---|---|---|
带有 float > 25 的 condition: template | condition: numeric_state | 在加载时验证,而非运行时 | references/automation-patterns.md#native-conditions |
wait_template: "{{ is_state(...) }}" | 带有状态触发器的 wait_for_trigger | 事件驱动,而非轮询;等待 变化(语义差异见 references/safe-refactoring.md#trigger-restructuring) | references/automation-patterns.md#wait-actions |
触发器中的 device_id | entity_id(或 ZHA 的 device_ieee) | device_id 在重新添加时会失效 | references/device-control.md#entity-id-vs-device-id |
运动感应灯的 mode: single | mode: restart | 重新触发必须重置计时器 | references/automation-patterns.md#automation-modes |
| 用于求和/平均的模板传感器 | min_max 辅助工具 | 声明式,处理不可用状态 | references/helper-selection.md#numeric-aggregation |
| 带阈值的模板二进制传感器 | threshold 辅助工具 | 内置迟滞支持 | references/helper-selection.md#threshold |
| 重命名实体 ID 而不进行影响分析 | 遵循 references/safe-refactoring.md 工作流 | 重命名会静默破坏仪表板、脚本和场景 | references/safe-refactoring.md#entity-renames |
| 重命名基于配置条目的组(UI 组)的成员而不更新成员资格 | 在注册表重命名后通过选项流更新组成员资格 | 实体注册表重命名不会更新配置条目中的 options.entities——组会静默失效 | references/safe-refactoring.md#config-entry-groups |
YAML 中的 template: 传感器/二进制传感器 | 模板辅助工具(UI 或配置流程 API) | 需要文件编辑和配置重新加载;更难管理 | references/template-guidelines.md |
| 在磁盘上搜索或读取 HA 配置文件 | 使用 HA REST/WebSocket API 以编程方式管理配置 | HA 是通过 API 访问的远程系统;配置文件不在本地文件系统上 | — |
| 为自动化/脚本/场景生成 YAML 片段 | 使用 HA 配置 API 以编程方式创建自动化/脚本 | API 调用会验证配置,避免语法错误,并且不需要手动编辑文件或重启 | references/automation-patterns.md, references/examples.yaml |
告诉用户编辑 configuration.yaml 来配置集成 | 引导用户前往 HA UI 中的 设置 > 设备与服务 | 大多数集成是通过 UI 配置的;YAML 集成配置很少见且特定于集成 | — |
需要详细信息时请阅读这些文件:
| 文件 | 何时阅读 | 关键章节 |
|---|---|---|
references/safe-refactoring.md | 重命名实体、替换辅助工具、重构自动化或任何对现有配置的修改 | #universal-workflow, #entity-renames, #helper-replacements, #trigger-restructuring |
references/automation-patterns.md | 编写触发器、条件、等待操作或选择自动化模式 | #native-conditions, #trigger-types, #wait-actions, #automation-modes, #ifthen-vs-choose, #trigger-ids |
references/helper-selection.md | 决定是使用内置辅助工具还是模板传感器 | #numeric-aggregation, #rate-and-change, #time-based-tracking, #counting-and-timing, #scheduling, #entity-grouping, #decision-matrix |
references/template-guidelines.md | 确认模板确实适用于某个用例 | #when-templates-are-appropriate, #when-to-avoid-templates, #template-sensor-best-practices, #common-patterns, #error-handling |
references/device-control.md | 编写服务调用、Zigbee 按钮自动化或使用 target: | #entity-id-vs-device-id, #service-calls-best-practices, #zigbee-buttonremote-patterns, #domain-specific-patterns |
references/dashboard-guide.md | 设计或修改 Lovelace 仪表板——布局、视图类型、区域、自定义卡片、CSS 样式、HACS | #dashboard-structure, #view-types, #built-in-cards, #features, #custom-cards, #css-styling, #common-pitfalls |
references/dashboard-cards.md | 查找可用的卡片类型或获取特定卡片的文档 | — |
references/domain-docs.md | 查找服务调用、实体属性或配置的集成或领域文档 | — |
references/examples.yaml | 需要结合多个最佳实践的复合示例 | — |
每周安装数
1.2K
代码仓库
GitHub 星标数
189
首次出现
2026年1月31日
安全审计
安装于
opencode1.1K
codex950
gemini-cli938
github-copilot908
kimi-cli891
amp889
Core principle: Use native Home Assistant constructs wherever possible. Templates bypass validation, fail silently at runtime, and make debugging opaque.
Follow this sequence when creating any automation:
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.
Before writing any template, check references/automation-patterns.md for native alternatives.
Common substitutions:
{{ 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)Before creating a template sensor, check references/helper-selection.md.
Common substitutions:
min_max integrationgroup helperderivative integrationthreshold integrationutility_meter helperIf 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.
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 |
device_id breaks when devices are re-added. See references/device-control.md.
Exception: Zigbee2MQTT autodiscovered device triggers are acceptable.
event trigger with device_ieee (persistent)device trigger (autodiscovered) or mqtt triggerSee references/device-control.md#zigbee-buttonremote-patterns.
| Anti-pattern | Use instead | Why | Reference |
|---|---|---|---|
condition: template with float > 25 | condition: numeric_state | Validated at load, not runtime | references/automation-patterns.md#native-conditions |
wait_template: "{{ is_state(...) }}" | wait_for_trigger with state trigger | Event-driven, not polling; waits for change (see references/safe-refactoring.md#trigger-restructuring for semantic differences) |
Read these when you need detailed information:
| File | When to read | Key sections |
|---|---|---|
references/safe-refactoring.md | Renaming entities, replacing helpers, restructuring automations, or any modification to existing config | #universal-workflow, #entity-renames, #helper-replacements, #trigger-restructuring |
references/automation-patterns.md | Writing triggers, conditions, waits, or choosing automation modes | #native-conditions, , , , , |
Weekly Installs
1.2K
Repository
GitHub Stars
189
First Seen
Jan 31, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
opencode1.1K
codex950
gemini-cli938
github-copilot908
kimi-cli891
amp889
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
103,800 周安装
references/automation-patterns.md#wait-actions |
device_id in triggers | entity_id (or device_ieee for ZHA) | device_id breaks on re-add | references/device-control.md#entity-id-vs-device-id |
mode: single for motion lights | mode: restart | Re-triggers must reset the timer | references/automation-patterns.md#automation-modes |
| Template sensor for sum/mean | min_max helper | Declarative, handles unavailable states | references/helper-selection.md#numeric-aggregation |
| Template binary sensor with threshold | threshold helper | Built-in hysteresis support | references/helper-selection.md#threshold |
| Renaming entity IDs without impact analysis | Follow references/safe-refactoring.md workflow | Renames break dashboards, scripts, and scenes silently | references/safe-refactoring.md#entity-renames |
| Renaming members of Config-Entry-based groups (UI groups) without updating membership | Update group membership via Options Flow after the registry rename | The entity registry rename does not update options.entities in the Config Entry — group silently breaks | references/safe-refactoring.md#config-entry-groups |
template: sensor/binary sensor in YAML | Template Helper (UI or config flow API) | Requires file edit and config reload; harder to manage | references/template-guidelines.md |
| Searching for or reading HA config files on disk | Use the HA REST/WebSocket API to manage config programmatically | HA is a remote system accessed via APIs; config files are not on the local filesystem | — |
| Generating YAML snippets for automations/scripts/scenes | Use the HA config API to create automations/scripts programmatically | API calls validate config, avoid syntax errors, and don't require manual file edits or restarts | references/automation-patterns.md, references/examples.yaml |
Telling user to edit configuration.yaml for integrations | Direct user to Settings > Devices & Services in the HA UI | Most integrations are UI-configured; YAML integration config is rare and integration-specific | — |
#trigger-types#wait-actions#automation-modes#ifthen-vs-choose#trigger-idsreferences/helper-selection.md | Deciding whether to use a built-in helper vs template sensor | #numeric-aggregation, #rate-and-change, #time-based-tracking, #counting-and-timing, #scheduling, #entity-grouping, #decision-matrix |
references/template-guidelines.md | Confirming templates ARE appropriate for a use case | #when-templates-are-appropriate, #when-to-avoid-templates, #template-sensor-best-practices, #common-patterns, #error-handling |
references/device-control.md | Writing service calls, Zigbee button automations, or using target: | #entity-id-vs-device-id, #service-calls-best-practices, #zigbee-buttonremote-patterns, #domain-specific-patterns |
references/dashboard-guide.md | Designing or modifying Lovelace dashboards — layout, view types, sections, custom cards, CSS styling, HACS | #dashboard-structure, #view-types, #built-in-cards, #features, #custom-cards, #css-styling, #common-pitfalls |
references/dashboard-cards.md | Looking up available card types or fetching card-specific documentation | — |
references/domain-docs.md | Looking up integration or domain documentation for service calls, entity attributes, or configuration | — |
references/examples.yaml | Need compound examples combining multiple best practices | — |