Imported from nolte/claude-home-assistant (skills/ha-backup-platform-add/SKILL.md). Install upstream with npx skills add nolte/claude-home-assistant --skill ha-backup-platform-add. Copyright stays with the author.

HA Backup Platform Add

Spec: spec/claude/ha-backup-platform-add/en.md (EN canonical) / spec/claude/ha-backup-platform-add/de.md (DE translation).

Why this is a skill, not an agent

• Human-visible augmentation surface — the user describes the integration type and reads back the backup.py module and the conformance report; a skill keeps this on the visible command surface, like the sibling augment skills (ha-config-flow-augment, ha-coordinator-add, ha-repairs-add, ha-device-automation-add).
• Mid-flow interactivity — the hooks-vs-agent disambiguation is a per-run dialogue the user approves before generation.
• Bounded, inline generation — one platform module (the two hook functions, or the agent class plus its registration) fits inline; no isolated agent context is needed.
• Counter-dimension considered: the draft→validate loop could be an agent, but the surface decision belongs in the user's working context; skill wins.

When this skill activates

Use this skill to add one backup-platform surface — pre/post backup hooks (for DB-writing or stateful integrations) or a backup agent (for storage-providing integrations) — to an existing integration via its backup.py platform module.

When NOT to activate

• greenfield integration scaffolding → ha-integration-scaffold
• the sibling diagnostics platform module → ha-diagnostics-augment
• backup encryption, retention, scheduling, or restore orchestration → owned by the backup manager / HA core, out of scope
• deploying/importing into a running HA instance → out of scope

Hard rules

1. One surface, one run. Either pre/post hooks or a backup agent — no combined batch.
2. Read spec/ha/backup-platform/en.md first. Do not generate from memory.
3. Disambiguate the surface. Stateful / DB-writing integration → pre/post hooks; storage-providing (cloud-storage) integration → backup agent. When both apply, have the user pick the one this run augments.
4. Hooks contract. async_pre_backup(hass: HomeAssistant) -> None and async_post_backup(hass: HomeAssistant) -> None are top-level async functions; whatever async_pre_backup pauses, async_post_backup resumes.
5. Agent registration. async_get_backup_agents(hass) returns list[BackupAgent] and must return [] when no loaded config entry exists for the domain (hass.config_entries.async_loaded_entries(DOMAIN)). async_register_backup_agents_listener(hass, *, listener, **kwargs) is a @callback returning an unregister function; notify listeners during async_setup_entry.
6. Agent contract. The BackupAgent subclass (from homeassistant.components.backup) sets domain/name/unique_id and implements async_upload_backup, async_download_backup, async_list_backups, async_get_backup, and async_delete_backup — the full abstract interface.
7. Error semantics. Errors raise BackupAgentError (or a subclass) — no other exception leaves the agent; a missing backup raises BackupNotFound in async_download_backup/async_delete_backup/async_get_backup. Call the on_progress callback periodically in async_upload_backup.
8. No backup-manager territory. Never implement encryption, retention, scheduling, or restore orchestration; those belong to the backup manager or the core.
9. Name per spec/ha/naming-conventions/en.md and verify HA internals against the official docs (see spec/ha/upstream-docs-verification/en.md).

Inputs

If the user is silent on an optional field, use the default but state it explicitly.

Pre-flight (in order — abort on first failure)

1. target_dir/custom_components/<domain>/manifest.json exists; read domain.
2. Resolve surface (infer + confirm). Disambiguate hooks vs. agent by integration type; when both apply, have the user pick the one for this run.
3. Read ha/backup-platform.
4. The targeted exports are not already declared in backup.py. If they are, abort.

Workflow

1) Resolve and confirm

State domain, the resolved surface, and (for an agent) the name/unique_id and storage binding in one paragraph. Wait for confirmation.

2) Generate

Write to custom_components/<domain>/backup.py. Mention the python3 -m script.scaffold backup template as a quick start; the skill itself generates offline.

3) Validate and report

Validate offline (backup.py present; for hooks both top-level functions exported; for an agent async_get_backup_agents + the listener @callback exported, the empty-list-without-entry guard present, the BackupAgent subclass sets the identity and implements the five methods, errors raise BackupAgentError/BackupNotFound). Emit a CONFORMANT / NEEDS-WORK report keyed to ha/backup-platform acceptance criteria, plus the changed file paths and the chosen surface.

4) No deploy

The skill never deploys to a live HA instance. Surface the report and stop.

Boundaries

• Greenfield scaffold → ha-integration-scaffold
• Sibling diagnostics module → ha-diagnostics-augment
• Encryption / retention / scheduling / restore → backup manager / HA core, out of scope
• Deploy to live HA → out of scope