name: home-assistant-config-dev description: Safely develop, debug, validate, test, roll back, and document Home Assistant configuration changes. Use for automations, scripts, packages, helpers, Assist pipelines, calendar-trigger behavior, traces, config API objects, live-first mutation, curated pull-back, or recovery planning; use hass-cli instead for routine household control and reporting. metadata: version: "1.0.0"

Home Assistant configuration development

Treat Home Assistant configuration work as a reversible live-system change, not as ordinary text editing. Prefer supported APIs, exact evidence, boring rollback, and production-path tests.

This skill complements hass-cli. Use that skill for entity discovery, state, areas, safe household control, and deterministic local intents. Do not enlarge this skill into a general home-control interface.

Establish the boundary

Before mutation:

1. Read the target repository's agent, planning, task, and snapshot documents.
2. Require a clean worktree and inspect the curated pull preview when the repo

uses one.

1. Classify the object as YAML-backed, storage-backed, runtime-only, or external.

Read persistence-boundaries.md.

1. Name the inverse operation and external cleanup before changing anything.
2. Identify the exact objects and files expected to change.
3. For Assist-facing work, enumerate required and forbidden exposed entities and

capture their live entity-registry conversation options.

1. Stop if the supported interface cannot capture and restore the original.

Never edit .storage generically. Never paste tokens into chat or commands. Never treat Git as disaster recovery when the repository is only a projection.

Use current diagnostic tools

Paths below are relative to this skill directory. The wrappers use exported HASS_SERVER and HASS_TOKEN; when absent, they reuse the sibling hass-cli environment loader without copying credentials.

All output is bounded JSON. Exit codes are 0 for success, 2 for invalid or rejected work, and 3 for authentication, transport, dependency, timeout, or protocol failures.

ha-assist-run requires --execute because text processing may perform real Home Assistant actions. Inspect pipeline, engine, processed_locally, response_type, and events; do not infer production routing from a direct conversation-agent call.

ha-calendar-events is deliberately limited to the read-like calendar.get_events action. Use exact ISO start/end values and an exact calendar.* entity. Descriptions are omitted unless explicitly requested.

Trace output excludes raw config and detailed step payloads by default. Use it to establish run identity, completion, last step, errors, and executed path—not to dump unbounded integration data into context.

Repeat the opt-in metadata-only live checks with:

HA_DEV_LIVE_SMOKE=1 \
HA_DEV_SMOKE_CALENDAR=calendar.example \
HA_DEV_SMOKE_TRACE_DOMAIN=automation \
HA_DEV_SMOKE_TRACE_ITEM_ID=example \
tests/live_smoke.sh

Add HA_DEV_SMOKE_ASSIST=1 only when a production-pipeline query is authorized. The default phrase is “What time is it?”; override it with HA_DEV_SMOKE_ASSIST_PHRASE only after reviewing its possible actions.

Audit Assist exposure

Treat entity exposure as an explicit storage-backed dependency. A valid entity, script, automation, or prompt does not imply that the selected LLM can see or invoke it. Creation, rename, replacement, integration migration, and deletion can all change the effective allowlist outside the curated YAML snapshot.

For every Assist-facing change:

1. List the exact required entities and action tools.
2. Inspect each live entity-registry conversation.should_expose value.
3. Inspect exposed scripts' current fields and action-response contracts; a tool

schema that exists but returns an invalid shape is still broken.

1. Search for stale, duplicate, unavailable, renamed, or superseded exposed

entities that could conflict with the authoritative source.

1. Keep implementation-only entities unexposed when a narrower script provides

the intended contract.

1. Test a safe phrase through the selected production pipeline, including one

wording that bypasses deterministic local sentence triggers; correlate the result with the invoked script or automation trace.

1. Record storage-backed exposure semantics in repository documentation because

a pull-only snapshot cannot preserve or review them directly.

Audit positive and negative space. Confirming the required tool is exposed does not establish that a stale contradictory helper is absent, and confirming stale entities are absent does not establish that the required tool is available.

Follow the live-first workflow

For authorized YAML-backed automation or script changes:

1. Baseline: verify expected live/repository drift and record current states.
2. Capture: save exact API objects and complete relevant files under a

durable rollback ID with private permissions.

1. Deactivate: turn off affected behavior when practical.
2. Install: use the supported config-object API; install scripts before

automations that depend on them.

1. Check: keep affected behavior off and run target-side ha core check.
2. Compare: fetch installed objects and compare normalized JSON exactly.
3. Activate: reload only required domains, then explicitly enable behavior.
4. Test actions: exercise action sequences independently where possible.
5. Audit exposure: verify the required and forbidden Assist allowlist when

the feature participates in conversation.

1. Test triggers: use the actual production path and inspect traces.
2. Verify effects: inspect external state and clean conspicuous test data.
3. Pull back: preview the curated rsync, require only expected paths, apply,

parse/lint, and review the full diff.

1. Document: update durable decisions, validation evidence, pending tests,

limitations, and rollback identity.

Read validation-matrix.md before claiming a change is validated. Syntax, action, trigger, collision, cancellation, and recovery are different evidence layers.

Preserve rollback discipline

The config APIs can write live files or reload an individual object before a whole-system check. Deactivation and capture reduce that risk; they do not make the change atomic.

A config-transaction wrapper is intentionally not implemented yet. Until its rollback paths have fault-injection tests, manual mutation remains exceptional: show the exact object set, rollback location, and activation boundary before proceeding. Never reconstruct rollback commands from memory after failure.

Use artifact-schema.md when capturing mutation evidence. Keep installation, check, activation, restart, and acceptance as separate states. Restart always requires explicit authorization.

Respect Git ownership

Pulling accepted live configuration into a working tree does not grant permission to stage, commit, amend, or push. Inspect and validate the diff, then leave history to the human unless separately authorized.

Current limitations

• Configuration transaction and rollback wrappers remain future work.
• Storage-backed object support is not generic and must be designed per API.
• Live Assist tests can incur LLM cost or real side effects.
• Calendar and integration polling can make successful API writes temporally

invisible to triggers; test platform timing rather than assuming immediacy.

• An HA outage can preserve an external record while still missing an HA action.