# home-assistant-manager

Adopt this skill: https://proskills.md/skills/other/komal-skynet-claude-skill-homeassistant-skills-home-assistant-manager

Page: https://proskills.md/skills/other/komal-skynet-claude-skill-homeassistant-skills-home-assistant-manager
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/home-assistant-manager/SKILL.md
size: 7172
upstream: https://github.com/komal-skynet/claude-skill-homeassistant/blob/main/skills/home-assistant-manager/SKILL.md

````text
---
name: home-assistant-manager
description: Manage Home Assistant configuration safely and fast — edit and deploy YAML (automations, blueprints, scripts, scenes, templates, MQTT), validate with ha core check, deploy via git or rapid scp, reload-vs-restart correctly, verify changes from logs, traces and entity state, and build Lovelace dashboards. Use for any Home Assistant config, automation, template, or dashboard work over SSH/hass-cli/MCP.
---

# Home Assistant Manager

Operate a remote Home Assistant instance precisely: make a change, get it live, prove it
worked. Optimize for the fewest safe round-trips.

## Assumptions
- The repo you're editing **is** the HA `/config` dir, git-connected to the instance.
  Edits aren't live until pulled on the instance.
- `root@homeassistant.local` in examples is a placeholder. Resolve the real user/host once
  (project CLAUDE.md, `~/.ssh/config`, or ask) and if it isn't recorded in the project
  CLAUDE.md yet, add it so future sessions skip this step.
- Access via one or more of: `hass-cli` (REST), SSH `ha`, or an MCP server (see below).
- Only edit `.yaml`/`.yml`/`.md`. Never read/write `.env` or `secrets.yaml`; use `!secret`.

## Remote access — pick the right tool
- **SSH `ha`** — always works, needs no local env. Use for `ha core check|restart|logs|info`.
- **`hass-cli`** (REST) — state/service calls, but needs `HASS_SERVER`/`HASS_TOKEN` in the
  shell *before* the session starts. If they're unset, hass-cli falls back to the wrong
  host (localhost) and errors — don't retry, check `[ -n "$HASS_TOKEN" ]` once, then use
  SSH or MCP instead.
- **MCP** (preferred when available) — first-class tools for live state/control, no env
  juggling. Official `mcp_server` integration (HA core ≥2025.2) or community `ha-mcp`
  (richer, 80+ tools). Use it instead of shelling out when present.

## The deploy pipeline (the one canonical flow)
Changes are not live until step 4.
1. Edit YAML locally.
2. Validate: `ssh root@homeassistant.local "ha core check"` (slow, ~30-60s — see "when to
   skip" below).
3. Commit + push: `git add … && git commit -m "…" && git push`.
4. **Make it live:** `ssh root@homeassistant.local "cd /config && git pull"`.
5. Apply: **reload** if possible, else **restart** (table below).
6. Verify (next section).

**Rapid iteration:** skip git and `scp` straight to the instance, then reload — good for
dashboards and tight test loops. Commit to git only once stable.
`scp automations.yaml root@homeassistant.local:/config/` → reload.

**When to skip `ha core check`:** it parses the whole config and is slow. For an isolated
YAML edit you're confident in, a domain reload surfaces errors faster and the logs tell
you immediately. Always run it before a *restart* or for `configuration.yaml` changes.

## Reload vs restart
| Change | Action |
|--------|--------|
| automations, scripts, scenes, groups, template entities, themes | **reload** the domain (`hass-cli service call automation.reload`, etc.) |
| `configuration.yaml` core, new integrations, platform sensors (min/max), MQTT sensor/binary_sensor platforms, dashboard registry (`lovelace_dashboards`) | **restart** (`ssh … "ha core restart"`, ~30s) |

Prefer reload. Never restart without a passing `ha core check`. Before risky changes
(core `configuration.yaml` surgery, removing an integration), snapshot first — it's cheap:
`ssh root@homeassistant.local "ha backups new --name pre-<change>"`.

## Verify — don't assume it worked
1. Reload/restart the right domain.
2. For automations, **trigger manually** for instant feedback:
   `hass-cli service call automation.trigger --arguments entity_id=automation.<id>`
   (or call the service via MCP). This **bypasses `conditions` by default** — it proves the
   actions, not the gate. To test conditions too, pass `skip_condition: false` or exercise
   the real trigger, then read the automation's trace in the UI.
3. Read the logs filtered to your change:
   `ssh root@homeassistant.local "ha core logs | grep -iE '<name>|error' | tail -20"`.
   Good: `Running automation actions`, `Executing step …`. Bad: `Invalid data for
   call_service`, `TypeError`, `Template variable warning`, `Error executing script`.
4. Confirm the real outcome: device/sensor state (`hass-cli state get <entity>`), or ask
   the user for notification-type actions.
5. On error: fix → re-pull/scp → reload → re-check. Loop until clean.

## Automations — write modern syntax
HA 2024.10 renamed the keys; legacy syntax still works but don't emit it in new code:
top-level `triggers:/conditions:/actions:` (plural), `trigger:` not `platform:` inside a
trigger, `action:` not `service:` for calls. Every automation gets a stable `id:` (traces
and UI editing need it) plus an `alias`.

**Full automation reference** (syntax table, `mode:` behavior, blueprints, trace debugging,
pitfalls) → read [`reference/automations.md`](reference/automations.md) when writing or
debugging automations.

## Templates — the precision rules
- Always coerce types before comparing: `states('sensor.x') | int(0) < 7`. Bare states are
  strings; `'5' < 7` raises `TypeError`. Provide a default (`int(0)`) so startup `None`
  doesn't error.
- Test in **Developer Tools → Template** before committing.
- `state_attr(...)` returns `None` if the entity/attr is missing — guard it.

## Conventions
- Surgical edits; preserve comments; 2-space indent.
- Validate before restart; prefer reload; verify from logs.
- Use context7 MCP for current HA docs before non-trivial or unfamiliar config.

## Dashboards
Lovelace dashboards live in `.storage/lovelace.*` (JSON). UI edits show on a browser refresh;
**direct file edits (scp/git) may not appear until a `ha core restart`** — HA caches the
lovelace store in memory. Adding a *new* dashboard to `.storage/lovelace_dashboards` also needs
a restart. `scp` + refresh is the fast loop; validate JSON first:
`python3 -m json.tool .storage/lovelace.x > /dev/null`. After deploying, **validate the UI
visually in the browser** (see the reference) — logs/state won't catch a broken card or a
mis-sorted popup.

**Full dashboard reference** (view types, card catalog, template cards, tablet layout,
pitfalls, debugging) → read [`reference/dashboards.md`](reference/dashboards.md) when doing
UI work. Modern HA: native **sections** view (drag-drop grid, badges, `heading` cards) and
feature-rich **tile** cards now cover most needs without custom cards; reach for Mushroom
only when you want its specific look.

## Quick reference
```bash
# Validate / apply
ssh root@homeassistant.local "ha core check"
ssh root@homeassistant.local "ha core restart"
ssh root@homeassistant.local "cd /config && git pull"     # make pushed changes live

# Logs
ssh root@homeassistant.local "ha core logs | grep -iE 'error|<name>' | tail -20"

# State / services (needs env loaded, or use MCP)
hass-cli state get <entity>
hass-cli service call <domain>.reload
hass-cli service call automation.trigger --arguments entity_id=automation.<id>

# Rapid deploy
scp <file>.yaml root@homeassistant.local:/config/ && hass-cli service call automation.reload
```
````

## File: README.md
upstream: https://github.com/komal-skynet/claude-skill-homeassistant/blob/main/README.md

````text
# Home Assistant Manager - Claude Code Skill

> Expert-level Home Assistant configuration management with efficient deployment workflows, remote CLI access, automation verification, and comprehensive Lovelace dashboard development.

[![Claude Code](https://img.shields.io/badge/Claude-Code-8A2BE2)](https://github.com/anthropics/claude-code)
[![Home Assistant](https://img.shields.io/badge/Home%20Assistant-Compatible-41BDF5)](https://www.home-assistant.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

![Tablet Dashboard Example](skills/home-assistant-manager/dashboard.png)
*Example tablet-optimized dashboard built using this skill - touch-friendly controls, color-coded status, and responsive grid layout*

## 🎬 See It In Action

### Quick Skill Check
Verify Claude can see and use this skill:

https://github.com/user-attachments/assets/a215df83-ce84-4ed2-bb93-f3a3ee0c43e8

*Shows Claude recognizing the skill and loading Home Assistant expertise*

### Full Workflow Demo
Watch the complete workflow in action - end to end (3x speed):

https://github.com/user-attachments/assets/eab53b18-ae2b-4d43-b1e4-e45bf9357099

*Complete automation development cycle including deployment, testing, log analysis, and git workflow*

## 🚀 What This Skill Does

This Claude Code skill transforms Claude into a **Home Assistant expert** that helps you:

### Configuration Management
- **Rapid Development Workflow**: Deploy changes via `scp` for instant testing, commit to git when stable
- **Smart Reload vs Restart**: Automatically determines whether to reload or restart based on change type
- **Configuration Validation**: Always validates before applying changes to prevent downtime
- **Remote CLI Access**: Seamlessly manages HA instances via SSH and `hass-cli`

### Automation Development
- **Modern Syntax by Default**: Writes current (2024.10+) automation YAML — `triggers:/conditions:/actions:`, `action:` not `service:` — instead of the deprecated syntax LLMs tend to emit
- **Complete Verification Protocol**: Automatically tests automations by triggering manually and checking logs and traces — including the `automation.trigger`-skips-conditions gotcha
- **Blueprints & Modes**: Knows blueprint structure/usage and when an automation needs `mode: restart` vs `single`
- **Error Detection**: Identifies template errors, type mismatches, and execution failures
- **Log Analysis Patterns**: Knows what success and error indicators to look for
- **Iterative Fix Workflow**: Guides through debugging and re-testing cycles

### Lovelace Dashboard Development
- **Tablet Optimization**: Creates touch-friendly dashboards optimized for specific screen sizes (7", 11", 13")
- **Card Type Expertise**: Knows when to use Mushroom cards, Tile cards, Panel vs Sections views
- **Template Patterns**: Provides ready-to-use Jinja2 templates for common use cases:
  - Door/window counting with color coding
  - Conditional display based on time/state
  - Multi-condition status indicators
- **Common Pitfall Solutions**: Solves dashboard registration, auto-entities failures, template type errors
- **Real-World Examples**: Includes working examples from production tablet dashboards

### Workflow Optimization
- **Git + scp Hybrid**: Uses git for version control, scp for rapid iteration
- **No Restart for Dashboards**: Deploys dashboard changes with just browser refresh
- **Context7 Integration**: Leverages official HA documentation via MCP when available
- **Deployment Decision Tree**: Guides through the optimal workflow based on change type

## 🆚 How Is This Different From an HA MCP Server?

They solve different problems, and they compose:

- **MCP servers** (the official `mcp_server` integration or community `ha-mcp`) give Claude **live tools** — read entity state, call services, control devices. They don't teach Claude *how to work on your config*.
- **This skill** encodes the **procedure and judgment**: the git/scp deploy pipeline, reload-vs-restart decisions, validate-before-restart discipline, the verify-from-logs-and-traces loop, template type-safety rules, dashboard storage-cache gotchas, and modern automation syntax.

Without the skill, an MCP-equipped Claude can flip your lights but will still happily restart HA on an unvalidated config or write deprecated automation YAML. Without MCP, the skill falls back to SSH/`hass-cli`. Together is best: the skill explicitly prefers MCP tools for live state and service calls when available.

## 📦 Installation

### Prerequisites

1. **Claude Code** installed and configured
2. **Home Assistant** instance with:
   - SSH access enabled
   - Git repository connected to `/config` directory
3. **Local tools**:
   - `hass-cli` installed (`pipx install homeassistant-cli`)
   - SSH key authentication configured
   - Environment variables set: `HASS_SERVER`, `HASS_TOKEN`

### Install the Skill

#### Option 1: Claude Code plugin marketplace (recommended)

This repo is also a self-hosted plugin marketplace, so you can install it with two slash commands — no manual cloning required:

```
/plugin marketplace add komal-SkyNET/claude-skill-homeassistant
/plugin install home-assistant-manager@claude-skill-homeassistant
```

Run these from anywhere — they install the plugin (and its skill) globally for Claude Code, so it's available whenever you open a Home Assistant config repo. Update later with `/plugin marketplace update claude-skill-homeassistant` followed by `/plugin update home-assistant-manager`.

#### Option 2: Clone into your Home Assistant config repository

```bash
cd /path/to/your/homeassistant/config
mkdir -p .claude/skills
cd .claude/skills
git clone git@github.com:komal-SkyNET/claude-skill-homeassistant.git home-assistant-manager-repo
ln -s home-assistant-manager-repo/skills/home-assistant-manager home-assistant-manager
```

#### Option 3: Download and extract

```bash
cd /path/to/your/homeassistant/config
mkdir -p .claude/skills/home-assistant-manager
cd .claude/skills/home-assistant-manager
curl -L https://github.com/komal-SkyNET/claude-skill-homeassistant/archive/main.tar.gz | tar xz --strip-components=2 claude-skill-homeassistant-main/skills/home-assistant-manager
```

### Verify Installation

After installing via the plugin marketplace, run `/plugin` to confirm `home-assistant-manager` is listed and enabled. With the manual options, the skill should appear when you start Claude Code in your Home Assistant repository. Either way, Claude will automatically load the skill and apply the expertise.

## 🎯 Usage Examples

### Example 1: Create a New Automation

```
User: "Create an automation that sends a notification when the front door
       is left open for more than 5 minutes"

Claude: [Uses skill to]:
1. Create automation YAML with proper syntax
2. Deploy via scp for testing
3. Reload automations (no restart needed)
4. Manually trigger to test
5. Check logs for execution
6. Verify notification received
7. Commit to git when working
```

### Example 2: Build a Tablet Dashboard

```
User: "Create a dashboard for my 11-inch tablet in the living room
       with lights, thermostat, and door status"

Claude: [Uses skill to]:
1. Create new dashboard file in .storage/
2. Register in lovelace_dashboards
3. Use 3-column grid layout (optimal for 11")
4. Add Mushroom cards for touch-friendly controls
5. Create template card with door counting
6. Deploy via scp for instant preview
7. Iterate on layout based on feedback
8. Commit when finalized
```

### Example 3: Debug a Template Error

```
User: "My automation has a TypeError about comparing str and int"

Claude: [Uses skill to]:
1. Check logs for exact error message
2. Identify template needs | int filter
3. Fix the template syntax
4. Deploy via scp
5. Trigger manually to verify
6. Check logs confirm no errors
7. Commit the fix
```

## 🏗️ Skill Architecture

This skill provides expertise in three core areas:

### 1. Remote Access Patterns
- `hass-cli` commands with environment variables
- S
````
