数据助手
- 作者仓库星标 452
- 作者更新于 实时读取
- 作者仓库 skills
- 领域
- 工程开发
- 兼容 Agent
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- 信任分
- 88 / 100 · 社区维护
- 作者 / 版本 / 许可
- @homeassistant-ai · 未声明 license
- Token 消耗评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部 API Key
- 不需要
- 兼容的系统
- 未声明（默认跨平台）
- 底层运行要求
- 无特殊要求
- 文件与系统权限
-
- 只读
- 允许写入 / 修改
- 网络行为
- 仅限本地
- 安装命令数
- 26 条
档案由构建时根据 SKILL.md 与安装命令自动衍生，可能与作者实际意图存在差异。
需要注意： 未限定 allowed-tools，默认拥有全部工具权限。
---
name: home-assistant-best-practices
description: > Follow this sequence when creating any automation: If your change affects entity IDs or cross-…
category: 工程开发
runtime: 无特殊运行时
---
# home-assistant-best-practices 输出预览
## PART A: 任务判断
- 适用问题：代码实现、重构、调试或代码审查。
- 输入要求：目标材料、限制条件、期望输出和验收方式。
- 证据边界：围绕“Decision Workflow / 0. Gate: modifying existing config? / 1. Check for native condition/trigger”读取原文规则，不把推断写成作者承诺。
## PART B: 执行结果
- **01** 任务判断：确认你的需求是否属于代码实现、重构、调试或代码审查，并标出输入、限制和预期结果。
- **02** 执行计划：优先按“Decision Workflow / 0. Gate: modifying existing config? / 1. Check for native condition/trigger”拆成步骤，说明每一步会读取什么、修改什么、产出什么。
- **03** 交付结果：给出可复制的命令、文件改动、检查清单或内容草稿，并说明如何继续迭代。
- **04** 风险边界：结合 读取文件、写入/修改文件、主要在本地完成、通常不需要额外 API Key 给出执行前确认项。
## Running Rules
- 读取文件、写入/修改文件；主要在本地完成；通常不需要额外 API Key。
- 先小样例验证，再放大到真实任务。
- 交付时同时给结果、检查口径和下一步迭代建议。 先确认触发方式
原文没有稳定的斜杠命令要求。安装验证后通常全局生效，直接在对话里点名这个 Skill 并描述任务即可。
给清楚输入和边界
告诉 Agent 目标文件或材料、期望结果、不可改范围、是否允许联网或执行命令。本 Skill 的权限画像是：读取文件、写入/修改文件。
小样例验证后再放大
先用一个小任务确认它会围绕“Decision Workflow / 0. Gate: modifying existing config? / 1. Check for native condition/trigger”工作；涉及文件或命令时，先看 diff、日志、预览或测试结果。
复核后再交付
检查最终产物是否包含明确结果、必要证据和下一步动作；如果输出泛泛而谈，就补充输入、边界和验收标准后重跑。
---
name: home-assistant-best-practices
description: > Follow this sequence when creating any automation: If your change affects entity IDs or cross-…
category: 工程开发
source: homeassistant-ai/skills
---
# home-assistant-best-practices
## 什么时候使用
- 把工程方向的常用动作沉淀成 Agent 可调用的技能 适合处理工程开发场景下的代码实现、调试、重构、测试或代码审查，核心价值是把输入、判断、执行、验证和交付边界固定下来，避免 Agent 泛泛回答。 把任务拆成可执行、可检查、可继续迭代…
- 面向代码实现、重构、调试或代码审查，优先处理能明确输入、步骤和验收标准的工作。
## 需要提供什么
- 目标材料、目录范围、期望结果和不可改动内容。
- 是否允许联网、执行命令、读写文件或调用外部服务。
## 执行规则
- 围绕「Decision Workflow / 0. Gate: modifying existing config? / 1. Check for native condition/trigger」组织步骤，不把推断写成作者事实。
- 读取文件、写入/修改文件；主要在本地完成；通常不需要额外 API Key。
- 先跑小样例，确认结果可检查后再扩大任务范围。
## 输出要求
- 给出最终产物、关键证据、验证方式和下一步动作。
- 信息不足时标记 unknown，不编造命令、平台或依赖。 证据边界与执行链路
作者原文负责流程事实；仓库文件负责来源和命令；流狐只补充适用场景、限制和质量判断。
skill "home-assistant-best-practices" {
输入层 -> 用户目标 + 目标文件 + 禁止范围 + 验收标准
上下文层 -> Decision Workflow / 0. Gate: modifying existing config? / 1. Check for native condition/trigger
规则层 -> SKILL.md 触发条件 / 执行顺序 / 输出格式
运行层 -> 无特殊运行时 | 读取文件、写入/修改文件 | 主要在本地完成
安全层 -> 通常不需要额外 API Key + 小任务验证 + diff / 日志复核
输出层 -> 可复制结果 + 检查清单 + 下一步迭代
}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 native condition/trigger
Before writing any template, check references/automation-patterns.md for native alternatives.
Common substitutions:
{{ states('x') | float > 25 }}→numeric_statecondition withabove: 25{{ is_state('x', 'on') and is_state('y', 'on') }}→condition: andwith state conditions{{ now().hour >= 9 }}→condition: timewithafter: "09:00:00"wait_template: "{{ is_state(...) }}"→wait_for_triggerwith state trigger (caveat: different behavior when state is already true — seereferences/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_maxintegration - Binary any-on/all-on logic →
grouphelper - Rate of change →
derivativeintegration - Cross threshold detection →
thresholdintegration - Consumption tracking →
utility_meterhelper
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 device_id
device_id breaks when devices are re-added. See references/device-control.md.
Exception: Zigbee2MQTT autodiscovered device triggers are acceptable.
5. For Zigbee buttons/remotes
- ZHA: Use
eventtrigger withdevice_ieee(persistent) - Z2M: Use
devicetrigger (autodiscovered) ormqtttrigger
See references/device-control.md#zigbee-buttonremote-patterns.
Critical Anti-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) |
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 |
enabled: false as a top-level key in automations.yaml |
automation.turn_off (temporary) or entity registry disable (permanent) |
Not a valid top-level key — rejected during schema validation; automation loads as unavailable |
references/automation-patterns.md#disabling-automations |
| 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, scenes, Config-Entry data, and storage dashboards 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 |
| Renaming entities used by Config-Entry integrations (Better/Generic Thermostat, Min/Max, Threshold) without patching Config-Entry data | Scan and patch core.config_entries data+options fields |
These integrations store entity_ids in Config Entry — not updated by entity registry renames | references/safe-refactoring.md#config-entry-data--blind-spots-for-entity-registry-renames |
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 |
Editing .storage/ files or other HA internal state directly |
Use the HA REST/WebSocket API to manage state and config entries | .storage/ files are HA's internal state database; direct edits bypass validation, risk corruption, and can be silently overwritten by HA |
— |
Writing raw YAML to configuration.yaml by hand for YAML-only integrations |
Use managed YAML config editing with backup and validation | Unmanaged writes risk syntax errors, have no backup, and skip check_config — managed editing provides all three |
references/yaml-only-integrations.md |
| 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 | — |
| Referring to HA "add-ons" | Use the term "Apps" | HA renamed add-ons to Apps in 2026.2 — "Apps are standalone applications that run alongside Home Assistant" | — |
vacuum.send_command with vendor room IDs |
vacuum.clean_area with HA area_id (if segments are mapped) |
Uses native HA areas, works across integrations — but requires segment-to-area mapping in entity settings first | references/device-control.md#vacuum-control |
Using color_temp (mireds) in light service calls |
Use color_temp_kelvin |
The color_temp parameter was removed in 2026.3; only Kelvin is supported |
references/device-control.md#lights |
Person/Device Tracker entered_home/left_home device triggers or is_home/is_not_home conditions |
state trigger to: home / to: not_home, or state condition |
These were removed in 2026.5 — state triggers and conditions are the correct replacements | references/automation-patterns.md#presence-and-person-triggers-and-conditions-removed-in-20265 |
Registering callbacks or calling self.turn_on()/self.get_state() in __init__() |
Register everything in initialize() |
Plugin connection not established during __init__ — calls fail silently |
references/appdaemon.md#app-structure-and-lifecycle |
Calling run_in on repeated triggers without cancelling the previous handle |
cancel_timer(self._off_handle) before each new run_in |
Every trigger stacks an independent timer — devices toggle unpredictably | references/appdaemon.md#scheduling-and-timers |
| Storing persistent state in instance variables | Use HA input_number, input_boolean, or input_text helpers |
Instance variables reset on app reload or daemon restart | references/appdaemon.md#state-management-and-inter-app-communication |
| Hardcoding entity IDs inside the class body | Pass entity IDs via self.args in apps.yaml |
Hardcoded IDs prevent reuse and require code edits per installation | references/appdaemon.md#appsyaml-configuration |
Reference Files
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, #config-entry-data--blind-spots-for-entity-registry-renames, #storage-mode-dashboards-storagelovelace |
references/automation-patterns.md |
Writing triggers, conditions, waits, or choosing automation modes; disabling automations | #native-conditions, #trigger-types, #wait-actions, #automation-modes, #continue-on-error, #repeat-actions, #ifthen-vs-choose, #trigger-ids, #disabling-automations |
references/helper-selection.md |
Deciding whether to use a built-in helper vs template sensor | #menu-based-helpers, #numeric-aggregation, #rate-and-change, #time-based-tracking, #counting-and-timing, #scheduling, #entity-grouping, #data-smoothing, #random-values, #climate-control, #domain-conversion, #template-helpers, #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/yaml-only-integrations.md |
Creating or editing YAML-only integrations that have no config flow (e.g. command_line, platform-based mqtt, rest) |
#yaml-only-integration-types, #post-edit-actions |
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 | — |
references/appdaemon.md |
AppDaemon apps: when to use vs. native HA, app structure, service calls, scheduling, error handling, safe refactoring impact | — |
先判断是否适合
作者设计意图
作者的方法与取舍
边界和复核