Home Assistant Integration knowledge
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.
How do I install this agent skill?
npx skills add https://github.com/home-assistant/core --skill home-assistant-integration-knowledgeIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides developer documentation and best practices for building, testing, and reviewing Home Assistant integrations. It contains no malicious code or instructions and explicitly includes security guidance to prevent the exposure of sensitive data.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
2/3 files flagged
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
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.
The following platforms have extra guidelines:
- Diagnostics:
platform-diagnostics.mdfor diagnostic data collection - Repairs:
platform-repairs.mdfor user-actionable repair issues
Integration Quality Scale
- When validating the quality scale rules, check them at https://developers.home-assistant.io/docs/core/integration-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://developers.home-assistant.io/docs/development_testing/#writing-tests-for-integrations
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/home-assistant/core/home-assistant-integration-knowledge">View Home Assistant Integration knowledge on skillZs</a>