haos-ssh-maintenance

SKILL.md

---
name: "haos-ssh-maintenance"
description: "Home Assistant OS SSH maintenance for config files, YAML, custom components, shell troubleshooting, or interactive ha CLI."
---

# HAOS SSH Maintenance

Use SSH only when API-based inspection is not enough.

## Default posture

Prefer the Home Assistant API first for:
- entity state inspection
- history and logbook
- automation listing, enable/disable, and trigger
- service-level testing

Switch to SSH when:
- files under `/config` need reading or editing
- YAML definitions must be inspected directly
- `custom_components` must be inspected
- shell-level troubleshooting is required
- `ha` CLI work is needed

Use the SSH target stored in the workspace `AGENTS.md` `## Tools` section.

## Common HAOS paths

- `/config`
- `/config/configuration.yaml`
- `/config/automations.yaml`
- `/config/scripts.yaml`
- `/config/scenes.yaml`
- `/config/custom_components/`
- `/config/home-assistant_v2.db`

## Logs

Do not assume Home Assistant writes logs to a file by default.

Check logs in this order:
1. Home Assistant UI logs when the issue is visible there
2. interactive `ha` CLI log access such as `ha core logs`
3. Supervisor or container-side logs when available
4. file-based logs only if the environment explicitly enables them

Observed behavior for this environment:
- `ha core logs` may fail in one-shot SSH mode
- `ha core logs` works in an interactive PTY-backed SSH session

## Workflow

1. Decide whether the task is one-shot SSH or interactive SSH.
2. Start read-only.
3. Identify the smallest affected file or command path.
4. Explain the intended change before risky edits.
5. Edit minimally.
6. Verify surrounding context after the change.
7. Prefer reload over full restart when possible.
8. Report exactly what changed.

## Home Assistant YAML pitfalls

When editing Home Assistant automations or packages by hand:
- In automation YAML, use `service:` to call a service such as `shell_command.foo` or `light.turn_on`.
- Do not write `action: shell_command.foo` in YAML automations. That produces an unknown action error in this environment.
- `action` is the UI/schema concept for a step in the actions list, but in hand-written YAML the concrete service call key should be `service:`.
- After editing automation/package YAML, reload both core config and automations when possible, then validate by triggering the automation once.

## SSH modes

### One-shot SSH

Use one-shot SSH commands for:
- reading files under `/config`
- grepping YAML or custom component code
- listing directories
- small targeted edits
- quick environment inspection

One-shot SSH is appropriate for commands like:
- `cat`
- `grep`
- `sed`
- `find`
- `ls`

Do not assume `ha` CLI commands will work in one-shot mode.

### Interactive SSH

Use an interactive PTY-backed SSH session for:
- `ha core logs`
- other `ha` CLI commands that fail in one-shot mode
- shell flows that require a login session or interactive context

When running from OpenClaw, prefer a PTY-backed exec session and then send commands into the live SSH shell.

## Investigation order

### Automation problems

1. API logbook and history
2. `/config/automations.yaml`
3. `/config/scripts.yaml`
4. relevant Home Assistant or Supervisor logs

### Naming or entity-origin confusion

1. API-visible attributes and registry-derived metadata
2. YAML definitions under `/config`
3. template, MQTT, REST, command_line, utility_meter, and custom component definitions

### Integration or startup failures

1. relevant Home Assistant or Supervisor logs
2. referenced YAML blocks
3. `custom_components` if relevant

## Change boundaries

Use SSH for:
- YAML edits
- package edits
- `custom_components` inspection
- interactive `ha` CLI log inspection
- Supervisor or container-side log inspection
- shell-level checks
- targeted `.storage` inspection or edits when UI/registry-backed state must be changed directly

Do not use SSH first for:
- normal state checks
- routine entity discovery
- simple automation enable/disable/trigger actions

## `.storage` direct-edit policy

Home Assistant internal storage under `/config/.storage/` can be edited when necessary, including files such as:
- `/config/.storage/core.entity_registry`
- `/config/.storage/core.device_registry`
- `/config/.storage/core.config_entries`

Rules:
- Treat `.storage` edits as a last-resort or targeted-operation path, not the default first move.
- Back up the exact file before every edit.
- Prefer the smallest possible change to a specific entity/device/config entry.
- Expect UI names to live in `core.entity_registry`; YAML `friendly_name` overlays can override what the UI shows.
- Be aware of writeback/refresh timing: changes may not appear immediately and may require reload or restart.
- Avoid broad rewrites of `.storage` JSON unless explicitly necessary.
- Report both the file path edited and the rollback path created.

## Safety

- Read before editing.
- Change the smallest possible region.
- Avoid broad rewrites when a targeted edit is enough.
- Ask before changing behavior that affects locks, alarms, access control, or physical entry.

## Reporting

When using this skill, report:
- what path was inspected
- what was found
- what changed, if anything
- whether reload or restart is needed