Skill: nextaltair/haos-ssh-maintenance (version 1.0.1)

--- name: haos-ssh-maintenance description: Use when Home Assistant OS needs SSH-based maintenance that cannot be completed cleanly through the Home Assistant API alone. Prefer API-first investigation for states, history, logbook, and routine automation checks; use this skill when direct filesystem access, YAML edits, custom_components inspection, HAOS shell troubleshooting, or interactive `ha` CLI work is required. Distinguish one-shot SSH commands from interactive SSH sessions: `ha` commands such as `ha core logs` may work only inside an interactive PTY-backed SSH session. --- # 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 `TOOLS.md`. ## 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


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)