/ha-integration

Home Assistant Integration Development

Create professional-grade custom Home Assistant integrations with complete config flows and entity implementations.

What This Skill Does

Helps developers create professional Home Assistant integrations from scratch, including:

• manifest.json configuration with proper dependencies and metadata
• Config flows with user-friendly setup UI and validation
• Entity implementation (sensors, switches, lights, etc.) with device linking
• DataUpdateCoordinator patterns for polling external APIs
• Device registry integration for multi-device setups
• Async/await best practices to prevent blocking the event loop

Covers the complete integration lifecycle from initialization through entity updates and error handling.

Core Capabilities

• Create manifest.json with all required fields and dependencies
• Implement config flows with validation and reauth support
• Build entity classes with proper unique_id and device_info
• Design DataUpdateCoordinator for robust polling patterns
• Handle async initialization and entity lifecycle
• Integrate with device and entity registries
• Implement proper error handling and status management

Auto-Trigger Keywords

Primary Keywords

Exact terms that strongly trigger this skill:

• custom component
• home assistant integration
• config flow
• entity implementation
• platform development
• manifest.json

Secondary Keywords

Related terms that may trigger in combination:

• device registry
• coordinator
• sensor entity
• switch entity
• config entry
• async setup

Error-Based Keywords

Common error messages that should trigger this skill:

• "Unknown platform"
• "Config flow validation failed"
• "Entity already exists"
• "Duplicate unique_id"
• "Device not found in registry"
• "Coordinator update failed"

Known Issues Prevention

When to Use

Use This Skill For

• Creating new Home Assistant custom integrations/components
• Implementing config flows with user input validation
• Building entity classes (sensors, switches, lights, climate, etc.)
• Setting up DataUpdateCoordinator for polling external data
• Linking entities to device registry
• Handling async initialization and lifecycle

Don't Use This Skill For

• Built-in Home Assistant components (use official docs)
• Non-integration Python packages
• UI card development (use lovelace skill instead)
• Automation or template development (use automations skill)

Quick Usage

# 1. Create manifest.json
{
  "domain": "my_integration",
  "name": "My Integration",
  "codeowners": ["@username"],
  "config_flow": true,
  "requirements": []
}

# 2. Create config_flow.py with validation
async def async_step_user(self, user_input=None):
    if user_input is not None:
        try:
            await self._validate_input(user_input)
        except Exception:
            return self.async_show_form(step_id="user", errors={"base": "invalid_auth"})
        return self.async_create_entry(title="...", data=user_input)

# 3. Create __init__.py with async setup
async def async_setup_entry(hass, entry):
    coordinator = MyDataUpdateCoordinator(hass, entry)
    await coordinator.async_config_entry_first_refresh()
    hass.data[DOMAIN][entry.entry_id] = coordinator
    await hass.config_entries.async_forward_entry_setups(entry, ["sensor"])
    return True

# 4. Create sensor.py with entities
class MySensor(SensorEntity):
    @property
    def unique_id(self) -> str:
        return f"{self.coordinator.data['id']}_sensor"

    @property
    def device_info(self) -> DeviceInfo:
        return DeviceInfo(identifiers={(DOMAIN, self.coordinator.data['id'])})

Token Efficiency

File Structure

ha-integration/
├── SKILL.md        # Detailed instructions and patterns
├── README.md       # This file - discovery and quick reference
├── assets/         # Templates and boilerplate
│   ├── manifest.json
│   ├── __init__.py
│   ├── config_flow.py
│   └── coordinator.py
└── references/     # Supporting documentation
    ├── manifest-reference.md
    ├── entity-base-classes.md
    └── config-flow-patterns.md

Dependencies

Official Documentation

• Creating a Component
• Config Entries
• Entity Index
• Device Registry

Related Skills

• ha-dashboard - Configure Home Assistant Lovelace dashboards and cards
• frigate-configurator - Set up Frigate NVR with Home Assistant integration

License: MIT