| name | ha-migration |
| description | Home Assistant integration upgrade guide — config entry version migration and deprecation fixes. Use when upgrading an integration to a newer HA version or handling migration warnings. |
Home Assistant Integration Migration
This skill is an entry point for two distinct migration concerns:
Config Entry Version Migration
When your config entry schema changes (renaming keys, adding required fields), you need to increment VERSION and implement async_migrate_entry.
See ha-config-migration for the full pattern and template.
When to use it: You changed what's stored in entry.data or entry.options and existing users' data needs to be transformed.
Deprecation Fixes
When upgrading to a newer HA version, imports, type annotations, and API patterns that were deprecated may now emit warnings or fail.
See ha-deprecation-fixes for 2024–2025 deprecation patterns with before/after examples.
When to use it: You see deprecation warnings in HA logs, or you're upgrading homeassistant minimum version in hacs.json.
Migration Checklist (Per Version Upgrade)
-
Check the Home Assistant Developer Blog for breaking changes
-
Search for deprecated imports in your code
-
Run check-patterns.py to detect common issues:
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/check-patterns.py" custom_components/my_integration/
-
Update minimum HA version in hacs.json
-
Test against target HA version
Related Skills
- Config entry migration →
ha-config-migration
- Deprecation patterns →
ha-deprecation-fixes
- Integration structure →
ha-integration-scaffold
