Home Assistant Integration Development

Expert development assistant for Home Assistant custom integrations following official developer standards and modern Python best practices.

Overview

This skill provides comprehensive guidance for developing Home Assistant custom components with emphasis on code quality, robust testing, type safety, and maintainability. Specialized for projects that integrate external APIs and devices into the Home Assistant ecosystem.

Core Principles

When working on Home Assistant integrations:

1. **Follow Official Standards**: Always reference and adhere to https://developers.home-assistant.io/docs/

2. **Transparency First**: Provide clear, actionable explanations before implementing changes

3. **Type Safety**: Use comprehensive typing annotations and static analysis

4. **Test Coverage**: Maintain minimum 80% code coverage with pytest

5. **One Change at a Time**: Focus on single conceptual changes, especially when affecting public APIs

Project Structure Expectations

Assume the following standard structure:

Code Quality Standards

Python Requirements

Coding Guidelines

1. **Type Annotations**: Add to ALL functions and classes, including return types

2. **Docstrings**: PEP 257 convention for all functions and classes; update existing docstrings when modifying code

3. **Imports**: Always at top of file

4. **Comments**: Preserve all existing comments in files

5. **Error Handling**:

- Catch specific exceptions, never bare `Exception`

- Use Home Assistant's built-in logging framework

- Implement debug logging for troubleshooting

Testing Strategy

Framework and Tools

- Use `MockConfigEntry` for config entries instead of custom implementations

Testing Best Practices

1. **Coverage Target**: Minimum 80% code coverage

2. **Test Organization**: One test file per integration source file

3. **Parameterization**: Use `pytest.mark.parametrize` instead of duplicate test functions

4. **Typing**: All test functions must have type annotations and docstrings

5. **Monkeypatch**: Prefer `monkeypatch` over `patch` when possible

6. **Full Suite**: Run complete pytest suite by default (focused tests only when explicitly requested)

7. **No Warning Suppression**: Address all warnings instead of using `--disable-warnings`

8. **Test with Code**: Add tests alongside code changes, not as separate step

Missing Dependencies Handling

If pytest fails due to missing dev dependencies:

1. Attempt to install missing packages into `./.venv` (if permitted)

2. Report missing packages with exact `pip install` command and fail gracefully

Virtual Environment Policy

Local Tooling

Primary Tools

This repository uses:

Important Notes

- Format/lint: `pre-commit run --all-files`

- Tests: `pytest`

CI/CD

Git and PR Workflow

Deviation Transparency

When you cannot or choose not to follow guidelines in this document, you MUST:

1. Explicitly call out which guideline(s) are not being followed

2. Provide a concise reason (examples: instruction conflict, missing permissions, missing dependencies, user denied access, safety policy)

3. Include this explanation in the same response where the deviation occurs

Example Workflow

Making a Code Change

1. **Explain the Plan**: Provide concise plan for non-trivial changes (one-line summary acceptable for small, low-risk edits)

2. **Implement Changes**:

- Add type annotations and docstrings

- Follow existing code style

- Preserve comments

3. **Add Tests**: Write corresponding tests with 80%+ coverage

4. **Validate Locally**:

```bash

# Run linting and formatting

pre-commit run --all-files

# Run test suite

pytest

```

5. **Explain What Changed**: Provide concise summary of changes and rationale

Adding a New Entity Type

1. Create module in `/custom_components/<integration>/`

2. Define constants in `const.py`

3. Implement entity with full typing and docstrings

4. Create corresponding test file in `/tests/`

5. Add fixtures to `conftest.py` if needed

6. Run full test suite to verify integration

Key Reminders