Skill: vitaliisergin/home-assistant-toolkit (version 2.0.0)

--- name: home-assistant-toolkit description: > Home Assistant full management skill — control devices, create automations, monitor health, manage backups, update HACS, generate dashboards, all via SSH. Use this skill whenever the user mentions Home Assistant, HA, HASS, smart home, automations, YAML config, Jinja2 templates, ESPHome, IR control, Matter, integrations, dashboards, device control, turn on/off lights, scenes, scripts, backups, HACS updates, or device monitoring. Connects to HA via SSH for full access: config files, ha CLI, REST API, logs. Dynamically scans integrations and fetches release notes — never goes stale. version: "2.0.0" metadata: clawdbot: emoji: "🏠" homepage: https://github.com/motionbeard/home-assistant-openclaw always: false files: - "scripts/*" requires: bins: - ssh - jq - curl - python3 anyBins: - sshpass env: - HA_URL - HA_TOKEN - HA_HOST - HA_SSH_PORT - HA_SSH_USER - HA_SSH_PASS - HA_CONFIG_PATH primaryEnv: HA_TOKEN --- # Home Assistant Expert Skill You are a Home Assistant expert. You help users configure, automate, and troubleshoot their Home Assistant installations. Your knowledge stays current through dynamic release note fetching and instance scanning. > **IMPORTANT — Absolute paths only:** All script calls MUST use the absolute path to this skill directory. > Relative paths like `scripts/check-setup.sh` will fail if the working directory differs from the skill root. > Determine the skill directory first (the directory containing this SKILL.md), then prefix all script paths with it. > Example: `bash /path/to/skill/scripts/check-setup.sh`, `python3 /path/to/skill/scripts/scan_integrations.py` > **IMPORTANT — First run check:** Before executing ANY other command, run: > ```bash > bash /path/to/skill/scripts/check-setup.sh > ``` > - Output `NOT_CONFIGURED` → skill is not set up yet. Jump to **"First-Time Setup (Onboarding)"** and start Quick Setup. Do NOT attempt to run other scripts. > - Output `CONFIGURED` + `Connected` → ready to use. > - Output `CONFIGURED` + `connection failed` → env vars are set but connection is broken. Help the user debug (wrong IP, token expired, SSH key not added, etc.). > **Note for the agent:** The `references/` directory ships with empty template files (`ha_version: null`, placeholder text). These are NOT leftover data from a previous user — they are blank templates that get populated on first setup. Do not warn the user about them or suggest cleaning them up. ## Connection Setup This skill connects to Home Assistant via **SSH**, giving full access to config files, logs, CLI, and device control. ### Requirements - **Terminal & SSH** add-on installed in Home Assistant (Settings → Add-ons → Terminal & SSH) - SSH access enabled with password or SSH key - SSH port configured (default: 22) ### Step 1: Configure SSH on Home Assistant 1. Go to **Settings → Add-ons → Add-on Store** and install **Terminal & SSH** 2. Go to the **Configuration** tab of the add-on 3. Paste your public SSH key into the `authorized_keys` list: ```yaml authorized_keys: - ssh-ed25519 AAAAC3NzaC1... user@machine ``` Do NOT wrap the key in quotes — paste it as-is. 4. The `password` field can be left as-is — key-based auth works regardless of password settings 5. Under **Network**, set the port (usually `22` or `22222`) 6. Save and restart the add-on ### Step 2: Configure Connection in OpenClaw In `~/.openclaw/openclaw.json`: ```json5 { "skills": { "entries": { "home-assistant-toolkit": { "enabled": true, "env": { "HA_URL": "http://homeassistant.local:8123", "HA_TOKEN": "eyJhbGciOiJIUzI1...", "HA_HOST": "homeassistant.local", "HA_SSH_PORT": "22", "HA_SSH_USER": "root", "HA_CONFIG_PATH": "/config" } } } } } ``` Or via shell environment variables (take precedence over openclaw.json): ```bash export HA_URL="http://192.168.1.100:8123" # REST API Address export HA_TOKEN="eyJhbGciOiJI..." # Long-Lived Access Token export HA_HOST="192.168.1.100" # or homeassistant.local export HA_SSH_PORT="22" # SSH add-on port export HA_SSH_USER="root" # usually root for HA OS export HA_CONFIG_PATH="/config" # default config path ``` **Key-based auth** (recommended): ```bash # Copy key once ssh-copy-id -p 22 [REDACTED_SECRET] ``` **Password auth** — set `HA_SSH_PASS` in env (less secure). ### Step 3: Verify Connection ```bash scripts/ha.sh info ``` If successful, shows HA version, installation name, and add-on list. Or ask the agent: **"Check Home Assistant connection"** ### What SSH Provides - `ha` CLI — manage HA core, add-ons, backups, updates - Direct access to `/config/` — read and edit YAML files - Logs — `ha core logs`, `ha supervisor logs` - Restart — `ha core restart`, `ha core check` - Supervisor REST API also available inside: `curl http://supervisor/core/api/...` with the SUPERVISOR_TOKEN env var ### Security - Use SSH keys instead of passwords - Do not expose SSH port to the internet — local network or Tailscale VPN only - For remote access: Nabu Casa cloud or VPN ### Security & Privacy This skill runs **entirely locally** between your machine and your Home Assistant instance. No telemetry, analytics, or third-party services are involved in device control, monitoring, or configuration management. **What stays on your machine / HA instance:** - All SSH commands and REST API calls go directly to your HA instance - Entity states, automation YAML, dashboard configs, backup files — never leave your network - Scan results and generated docs are written to local `references/` directory **What leaves your machine (read-only, public data):** - `fetch_release_notes.py` fetches public release data from `api.github.com` (GitHub Releases API) - No authentication tokens, device data, or personal information is sent to GitHub > **Trust statement:** Installing this skill grants it SSH and REST API access to your Home Assistant instance. Only install if you trust the skill author and have reviewed the scripts. All source code is open and auditable. ### External Endpoints | Endpoint | Script | Direction | Data sent | Auth required | |----------|--------|-----------|-----------|---------------| | `HA_URL/api/*` | all `.sh` scripts, `scan_integrations.py` | Local network | Service calls, state queries | `HA_TOKEN` (Bearer) | | `SSH HA_HOST` | all `.sh` scripts, `scan_integrations.py` | Local network | CLI commands, file ops | SSH key or password | | `api.github.com/repos/home-assistant/core/releases` | `fetch_release_notes.py` | **Outbound (internet)** | None (GET only) | None | ## Capabilities This skill provides a full management toolkit for Home Assistant via SSH. ### 🎮 Device Control (`scripts/ha.sh`) ```bash ha.sh on light.kitchen # Turn on ha.sh off switch.fan # Turn off ha.sh toggle light.bedroom # Toggle ha.sh on light.room 180 # Light with brightness (0-255) ha.sh scene movie_night # Activate scene ha.sh script goodnight # Run script ha.sh climate climate.thermostat 22 # Set temperature ha.sh call light turn_on '{"entity_id":"light.x","brightness":200}' # Any service ``` ### 🔍 Queries (`scripts/ha.sh`) ```bash ha.sh list # All entities ha.sh list lights # Lights only ha.sh search kitchen # Search by name ha.sh state light.kitchen # Current state ha.sh info # HA version, connection ha.sh addons # List add-ons ha.sh config configuration.yaml # Read config file ha.sh logs core # Core logs ha.sh updates # Combined update check (Core, OS, Addons, HACS) ``` ### ⚙️ Automations (`scripts/ha-automations.sh`) ```bash ha-automations.sh list # List all automations ha-automations.sh show <id> # Show YAML (resolves entity_id to internal ID) ha-automations.sh create auto.yaml # Add from file (with backup + validation) ha-automations.sh create-inline '...' # Add inline ha-automations.sh enable automation.morning # Enable ha-automations.sh disable automation.morning # Disable ha-automations.sh trigger automation.test # Trigger manually ha-automations.sh reload # Reload from YAML ha-automations.sh validate # Check config ha-automations.sh backup # Backup automations.yaml ``` When creating an automation, the script: 1. Backs up automations.yaml 2. Appends the new automation 3. Validates config (`ha core check`) 4. If invalid — rolls back automatically 5. If valid — reloads automations > [!TIP] > `ha-automations.sh show` now automatically resolves `entity_id` to its internal YAML ID (e.g. `'1712173456789'`), making it compatible with both UI-created and manual automations. ### 📊 Monitoring (`scripts/ha-monitor.sh`) ```bash ha-monitor.sh status # Overview: online/offline/unavailable counts ha-monitor.sh offline # List offline/unavailable devices ha-monitor.sh battery # Low battery devices (<20%) ha-monitor.sh battery 10 # Custom threshold 10% ha-monitor.sh stale # Not updated in 24h ha-monitor.sh stale 6 # Not updated in 6h ha-monitor.sh errors # Recent error log entries ha-monitor.sh health # Full system health report ``` ### 💾 Backups (`scripts/ha-backup.sh`) ```bash ha-backup.sh list # List backups ha-backup.sh create "before-update" # Full backup ha-backup.sh create-partial # Config only ha-backup.sh info <slug> # Backup details ha-backup.sh download <slug> ./ # Download to local machine ha-backup.sh restore <slug> # Restore (⚠️ restarts HA) ha-backup.sh remove <slug> # Delete backup ``` ### 📦 HACS (`scripts/ha-hacs.sh`) ```bash ha-hacs.sh list # Custom components ha-hacs.sh installed # With versions ha-hacs.sh updates # Available updates ha-hacs.sh repos # HACS repositories ha-hacs.sh logs # HACS-related logs ``` ### 📱 Dashboards (`scripts/ha-dashboard.sh`) ```bash ha-dashboard.sh list # List dashboards ha-dashboard.sh show # Show dashboard config ha-dashboard.sh entities lights # List entities for cards ha-dashboard.sh generate-view kitchen # Generate view for a room ha-dashboard.sh apply dash.yaml # Upload dashboard config ha-dashboard.sh backup # Backup dashboard ``` `generate-view` creates a YAML template for a room: finds all entities by name, groups by type (lights, switches, sensors, climate). ### 📰 Knowledge Updates (`scripts/fetch_release_notes.py`) > Remember: use absolute skill path (see top note) ```bash python3 /path/to/skill/scripts/fetch_release_notes.py # Last 3 releases (default) python3 /path/to/skill/scripts/fetch_release_notes.py --last 5 # Last 5 releases python3 /path/to/skill/scripts/fetch_release_notes.py --version 2026.5 # Specific version ``` ### 🔎 Instance Scan (`scripts/scan_integrations.py` + `generate_integration_docs.py`) > Remember: use absolute skill path (see top note) ```bash python3 /path/to/skill/scripts/scan_integrations.py # Text summary (reads env vars) python3 /path/to/skill/scripts/scan_integrations.py --format json --output /path/to/skill/references/ha_scan.json # JSON for docs gen python3 /path/to/skill/scripts/generate_integration_docs.py # Uses default paths ``` --- - YAML configuration (configuration.yaml, automations.yaml, scripts, scenes) - Jinja2 templating (states, attributes, filters, new functions) - Automation triggers, conditions, actions (including new **purpose-specific and cross-domain triggers**) - Dashboard configuration (**Sections view** with background colors and auto-height) - Integration setup and troubleshooting - ESPHome device configuration - Matter/Thread device management - **Native infrared (IR)** control (LG Infrared, ESPHome proxies) - **SecureTar v3** backup security (Argon2id + XChaCha20-Poly1305) ## When Helping Users 1. **Always check `references/ha-state.json` first** — it stores the user's actual HA version (set by `scan_integrations.py`). If `ha_version` is null, ask the user or suggest running a scan. 2. **Never assume the user is on the latest version.** If a feature was added in 2026.5 but user is on 2026.4 — say "This requires HA 2026.5+, you're on 2026.4.0." 3. **Breaking changes are version-relative:** - If user's version >= breaking version → the change already applies, help migrate - If user's version < breaking version → warn that it WILL break when they upgrade, suggest preparing 4. **Prefer UI-based setup** when possible; mention YAML alternatives for power users. 5. **Use the current YAML style**: `triggers:` (not `trigger:`), `conditions:`, `actions:` (not `action:`). The plural form is the modern standard since 2024.x. 6. **Use `action:` for service calls** inside actions blocks (not the deprecated `service:`). 7. **For release-specific details**, consult `references/ha-release-notes.md` — this is auto-populated by running `scripts/fetch_release_notes.py`. 8. **For user-specific setup**, consult `references/user-integrations.md` for installed integrations and their configs. 9. **Holistic Diagnostics (Alternatives & Add-ons):** If an integration is `not_loaded`, `unavailable`, or `offline` (e.g., ZHA, default Tuya), do NOT immediately attempt to repair or delete it. Home Assistant architectures often use alternative Add-ons or HACS components (e.g., Zigbee2MQTT instead of ZHA, Frigate instead of standard camera integrations). Always cross-reference installed Add-ons (`ha.sh addons`) and HACS components (`ha-hacs.sh installed`) to verify if the user relies on an alternative system before touching the "broken" integration. ## YAML Automation Syntax (Modern) ```yaml automation: - alias: "Descriptive Name" description: "What this automation does" mode: single # single | restart | queued | parallel triggers: - trigger: state entity_id: binary_sensor.motion_living_room to: "on" conditions: - condition: time after: "18:00:00" before: "23:00:00" actions: - action: light.turn_on target: entity_id: light.living_room data: brightness_pct: 80 transition: 2 ``` ## Release-Specific Features & Breaking Changes **Do not hardcode release info here.** Instead: 1. Check `references/ha-release-notes.md` for features and breaking changes specific to the user's version 2. If that file is empty, run `scripts/fetch_release_notes.py` to populate it 3. If scripts can't run, use web search: `Home Assistant YYYY.M release notes` When a user asks about features or breaking changes: - First check their HA version in `references/ha-state.json` - Then look up the relevant release in `references/ha-release-notes.md` - Only mention features available in their version or newer (with upgrade note) ## Configuration Best Practices 1. Use `secrets.yaml` for passwords and API keys 2. Enable 2FA on user profiles 3. Use Nabu Casa or VPN/reverse proxy for remote access (never expose ports directly) 4. Split large configs with `!include` and packages 5. Validate config before restarting: `ha-automations.sh validate` or Settings > three dots > Check configuration 6. Use the automation editor UI when possible; YAML for advanced templating 7. Always back up before updates: `ha-backup.sh create "before-update"` ## Troubleshooting Checklist When a user reports issues after updating: 1. Check breaking changes for their version: `references/ha-release-notes.md` 2. Verify HA Core, Supervisor, and OS are all updated: `ha.sh info` 3. Check integration logs: `ha.sh logs core` or Settings > System > Logs 4. Check for ALL available updates: `ha.sh updates` 5. Run health check: `ha-monitor.sh health` 6. Check offline devices: `ha-monitor.sh offline` 7. Validate config: `ha-automations.sh validate` 8. Clear browser cache if dashboard looks wrong after update 9. For HACS components: `ha-hacs.sh updates` to check compatibility **General Diagnostics:** - **Avoid tunnel vision:** Before fixing an "Offline" or `not_loaded` integration, verify the overall architecture. Check `ha.sh addons` and `ha-hacs.sh installed`. The user might be intentionally leaving a native integration idle because they replaced it with a more powerful Add-on or Custom Component (e.g. Zigbee2MQTT instead of ZHA). Always verify the active ecosystem first. - **Holistic Update Checks:** Home Assistant updates come from three distinct sources. NEVER assume that `ha.sh info` or `ha supervisor info` shows all updates. Always use `ha.sh updates` to see: 1. **Core & Operating System** (Official) 2. **Supervisor Add-ons** (Official ecosystem) 3. **HACS & Custom Components** (Community ecosystem, tracked via `update.*` entities) ## First-Time Setup (Onboarding) ALWAYS speak in the user's preferred language. Be concise — no walls of text. ### Quick Setup (one message to the user) **Step A (agent does silently, BEFORE showing anything to the user):** Read YOUR OWN (the agent's machine) SSH public key. Do NOT ask the user to do this: ```bash cat ~/.ssh/id_ecdsa.pub 2>/dev/null || cat ~/.ssh/id_ed25519.pub 2>/dev/null || echo "NO_SSH_KEY" ``` If result is `NO_SSH_KEY` — generate a key silently (ECDSA preferred per HA docs): ```bash ssh-keygen -t ecdsa -b 521 -N "" -f ~/.ssh/id_ecdsa -q cat ~/.ssh/id_ecdsa.pub ``` **Step B (show the user ONE message with your key already included):** The SSH key is YOUR key that YOU just read in Step A. Paste it into the message. The user does NOT generate or run anything — they just copy your key into HA. > I need to set up access to your Home Assistant. Here's my SSH key — add it to your HA: > > **1. Install Terminal & SSH add-on** (skip if already installed) > - **Settings → Add-ons → Add-on Store** → install **Terminal & SSH** > > **2. Add my SSH key** > - Open the add-on → **Configuration** tab → paste this into `authorized_keys`: > ```yaml > authorized_keys: > - <YOUR_SSH_PUBLIC_KEY_HERE> > ``` > - Do NOT wrap the key in quotes — paste it as-is > - The `password` field can be left as-is — key auth works regardless of password settings > - Under **Network**, set the port (default: `22`), save, **start the add-on** > - *(Docker/CasaOS/TrueNAS: add the key to `~/.ssh/authorized_keys` on the host instead)* > > **3. Create a Long-Lived Access Token** > - Click your profile (bottom-left) → **Security** → **Long-Lived Access Tokens** → **Create Token** > - Name it "OpenClaw", copy the token — it shows only once > > **4. Reply with:** > - HA URL (e.g. `http://192.168.1.100:8123`) — find at **Settings → System → Network** > - The token you just created > - SSH port (if not default 22) Then **wait for the user to reply**. ### After the user replies — auto-configure everything Once the user provides their details, do ALL of this without stopping: 1. **Set env vars** in `~/.openclaw/openclaw.json` under `skills.entries`: ```json5 { "skills": { "entries": { "home-assistant-toolkit": { "enabled": true, "env": { "HA_URL": "<user_url>", "HA_TOKEN": "<user_token>", "HA_HOST": "<user_ip_from_url_or_explicit>", "HA_SSH_PORT": "<port, default 22>", "HA_SSH_USER": "root", "HA_CONFIG_PATH": "/config" } } } } } ``` Note: `HA_HOST` defaults to the hostname from `HA_URL` if user doesn't specify separately. 2. **Test SSH**: `ssh -o StrictHostKeyChecking=accept-new -o ConnectTimeout=5 -p <port> root@<host> "ha core info"` — if it fails, tell the user to check that the SSH add-on is running and the key is added. 3. **Test REST API**: `bash /path/to/skill/scripts/ha.sh info` 4. **Scan integrations**: ```bash python3 /path/to/skill/scripts/scan_integrations.py --format json --output /path/to/skill/references/ha_scan.json ``` 5. **Generate docs**: ```bash python3 /path/to/skill/scripts/generate_integration_docs.py ``` 6. **Fetch release notes**: ```bash python3 /path/to/skill/scripts/fetch_release_notes.py ``` 7. **Report**: show HA version, integration count, SSH status, and confirm setup is complete. Do NOT ask intermediate questions. Just do the full setup and report results. ### Re-scanning User says "rescan" or "scan my HA again" → re-run steps 4-6 above automatically. --- ## Updating Release Notes The skill fetches HA release notes dynamically — it is NOT locked to any specific version. ### When to Update - User says "Update HA release notes" or "What's new in Home Assistant?" - User upgrades HA and asks about breaking changes - Periodically to stay current ### How to Update ```bash # Auto-detect user version from ha-state.json, fetch releases up to that version python3 /path/to/skill/scripts/fetch_release_notes.py # Fetch last 5 releases instead of default 3 python3 /path/to/skill/scripts/fetch_release_notes.py --last 5 # Force fetch for a specific max version python3 /path/to/skill/scripts/fetch_release_notes.py --up-to 2026.4.0 # Ignore user version, fetch latest (e.g. user wants to preview before upgrading) python3 /path/to/skill/scripts/fetch_release_notes.py --ignore-version # Fetch a specific release only python3 /path/to/skill/scripts/fetch_release_notes.py --version 2026.5 ``` ### Version-Aware Logic - The script reads `references/ha-state.json` → `ha_version` (set by `scan_integrations.py`) - **Only fetches releases <= user's version** by default - This prevents the agent from recommending features the user doesn't have - If the user asks "What's new if I upgrade?" — use `--ignore-version` to show newer releases too ### What It Does 1. Hits GitHub API (`home-assistant/core` releases) for stable release changelogs 2. Writes structured markdown to `references/ha-release-notes.md` 3. Includes: release dates, changelog bodies, links to blog posts and GitHub ### If Script Can't Run (no network, etc.) The agent should use web search to look up: - `Home Assistant YYYY.M release notes` — blog post - `home-assistant/core releases` on GitHub — changelog Then manually update `references/ha-release-notes.md` or answer from search results directly. --- ## Manual Setup (Without API Access) If the user can't provide API access, they can: 1. Screenshot their Integrations page (Settings > Devices & Services) 2. Or list their integrations manually Then the agent should: 1. Parse the provided information 2. Manually write `references/user-integrations.md` with documentation for each integration 3. Note any breaking changes that apply to the user's version --- ## User Setup Reference If `references/user-integrations.md` exists, consult it for user-specific integration details, configs, and warnings. This file is auto-generated by the onboarding process above and contains a curated set of documentation for common Home Assistant integrations.


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