home-assistant-integration-knowledge
The definitive guide for Home Assistant integration development and testing.
Install
mkdir -p .claude/skills/home-assistant-integration-knowledge && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/696" && unzip -o skill.zip -d .claude/skills/home-assistant-integration-knowledge && rm skill.zipInstalls to .claude/skills/home-assistant-integration-knowledge
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Everything you need to know to build, test and review Home Assistant Integrations. If you're looking at an integration, you must use this as your primary reference.Key capabilities
- →Structure integration code and test files
- →Implement entity platforms using base classes
- →Manage lifecycle methods like async_added_to_hass
- →Apply integration quality scale rules
- →Configure diagnostic and repair platforms
How it works
It enforces architectural patterns and quality standards by referencing specific file structures, base class APIs, and quality scale rules for Home Assistant integrations.
Inputs & outputs
When to use home-assistant-integration-knowledge
- →Building a new home automation integration
- →Debugging existing integration logic
- →Reviewing integration code against HA standards
- →Writing tests for Home Assistant entities
About this skill
File Locations
- Integration code:
./homeassistant/components/<integration_domain>/ - Integration tests:
./tests/components/<integration_domain>/
General guidelines
- When looking for examples, prefer integrations with the platinum or gold quality scale level first.
- Polling intervals are NOT user-configurable. Never add scan_interval, update_interval, or polling frequency options to config flows or config entries.
- Do NOT allow users to set config entry names in config flows. Names are automatically generated or can be customized later in UI. Exception: helper integrations may allow custom names.
- For entity actions and entity services, avoid requesting redundant defensive checks for fields already enforced by Home Assistant validation schemas and entity filters; only request extra guards when values bypass validation or are transformed unsafely.
- When validation guarantees a key is present, prefer direct dictionary indexing (
data["key"]) over.get("key")so invalid assumptions fail fast. - Integrations should be thin wrappers. Protocol parsing, device state machines, or other domain logic belong in a separate PyPI library, not in the integration itself. If unsure, ask before inlining.
- Integrations should not implement fixes or workarounds for limitations in libraries. Instead, the library should be updated to fix the issue.
- Do not add entities for data that Home Assistant intentionally only exposes through an action, for example weather forecasts (
weather.get_forecasts). - In config flows, map known failures to the matching standard error (for example
invalid_auth,cannot_connect) without logging them. If unexpected exceptions are caught, log them with_LOGGER.exception()and map them tounknown. Do not mix translated and untranslated text in an error shown to the user. - Bump dependencies in a standalone PR that contains only the compatibility adjustments the bump requires. Features that need the new version go in a follow-up PR.
The following platforms have extra guidelines:
- Device tracker:
platform-device-tracker.mdfor replacing legacy device trackers - Diagnostics:
platform-diagnostics.mdfor diagnostic data collection - Repairs:
platform-repairs.mdfor user-actionable repair issues
Entity platforms
- Ensure
async_added_to_hass()andasync_will_remove_from_hass()have symmetrical behavior. For example, if a subscription is created inasync_added_to_hass(), it should be unsubscribed inasync_will_remove_from_hass(). Also, if something is torn down inasync_will_remove_from_hass(), it should be set up inasync_added_to_hass(). - Use
_attr_*attributes instead of properties for values that never change. Define them as class attributes only when the value is shared by all instances. - When overriding
available, combine it with the parent's value (return super().available and ...). - Entity base class (e.g.
SensorEntity,TrackerEntity) provide a stable API for child classes to inherit from. Do not suggest redeclaring or duplicating attributes, properties, or methods the base class already provides, and do not add guards against the parent's behavior changing — rely on the base class instead.
Actions
- Action names and action fields are defined in
<Prefix>Serviceand<Prefix>ServiceArgumentStrEnums, using the integration's usual class prefix (for exampleTadoService,AITaskServiceArgument). Integrations define them inservices.py, or inconst.pywhen other modules need them; entity platforms define them inconst.pyand export them. - The members cover the registered actions and their fields as listed in
services.yaml. Do not add members for actions that are not registered, such as staleservices.yamlentries or description templates for legacy per-platform actions. - Use the members for action registration, schema keys and
call.datalookups instead of raw strings or other string constants (whatever their prefix, for exampleSERVICE_*,ATTR_*orCONF_*). Shared selector fields such asconfig_entry_id,device_idandentity_idkeep using thehomeassistant.constconstants. - Only request these enums, as a blocking change, when a PR adds an integration's first actions (a new
services.yaml). Do not flag or suggest them for an integration that already has actions.
Integration Quality Scale
- When validating the quality scale rules, check them at https://contributors.home-assistant.io/core/quality-scale/rules/
- When implementing or reviewing an integration, always consider the quality scale rules, since they promote best practices.
Template scale file: ./script/scaffold/templates/integration/integration/quality_scale.yaml
How Rules Apply
- Check
manifest.json: Look for"quality_scale"key to determine integration level - Bronze Rules: Always required for any integration with quality scale
- Higher Tier Rules: Only apply if integration targets that tier or higher
- Rule Status: Check
quality_scale.yamlin integration folder for:done: Rule implementedexempt: Rule doesn't apply (with reason in comment)todo: Rule needs implementation
Testing Requirements
- Tests should avoid interacting or mocking internal integration details. For more info, see https://contributors.home-assistant.io/core/development/tests/#test-through-home-assistant
- Define shared mocks as fixtures in
conftest.pyso every platform test can reuse them, including amock_config_entry. Give it aunique_idwhen the integration's config entries have one. - Load substantial or reused mock API data from JSON fixture files with
load_json_object_fixtureorload_json_array_fixturefrompytest_homeassistant.common(or theirasync_variants) instead of building it inline withjson.dumps(). - Do not manually assert values that a snapshot test already covers.
- When a
Platformmember or anATTR_*constant exists for a value, use it instead of a string literal. - Patch objects where they are used, not where they are defined.
- To give one test different mock data, parametrize the fixture that provides it with
pytest.mark.parametrizeinstead of patching again inside the test. Useindirect=Truewhen the fixture reads the value fromrequest.param.
When not to use it
- →Adding scan_interval to config flows
- →Hardcoding integration names in config flows
- →Implementing library workarounds in integration code
Prerequisites
Limitations
- →Polling intervals are not user-configurable
- →Requires adherence to specific quality scale rules
How it compares
It mandates adherence to specific quality scale tiers and architectural constraints that are unique to the Home Assistant ecosystem.
Compared to similar skills
home-assistant-integration-knowledge side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| home-assistant-integration-knowledge (this skill) | 8 | 5mo | No flags | Advanced |
| temporal-python-testing | 8 | 7mo | No flags | Advanced |
| whart-test | 5 | 5mo | Review | Beginner |
| setup-web-tests | 1 | 5mo | Caution | Advanced |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by home-assistant
View all by home-assistant →You might also like
temporal-python-testing
wshobson
Test Temporal workflows with pytest, time-skipping, and mocking strategies. Covers unit testing, integration testing, replay testing, and local development setup. Use when implementing Temporal workflow tests or debugging test failures.
whart-test
MGdaasLab
WHartTest测试管理平台工具集。用于管理项目、模块、测试用例的增删改查,以及截图上传和drawio图表操作。当用户需要操作测试用例、查询项目信息、上传截图或创建编辑图表时使用。
setup-web-tests
PostHog
Set up Python test environment in Claude Code for web where flox is unavailable. Use when you need to run backend tests and `uv sync` fails due to Python version mismatch.
paasta-api-endpoint
Yelp
Automates the creation of new PaaSTA API endpoints following established patterns
agent-implementer-sparc-coder
ruvnet
Agent skill for implementer-sparc-coder - invoke with $agent-implementer-sparc-coder
test-api-serializer
engremran07
Serializer tests: to_representation, to_internal_value, validation. Use when: testing DRF serializer output, input validation, custom field logic.