Home / All Skills / Workflow & Core Tools / home-assistant
English (EN)简体中文 (ZH)日本語 (JA)
Workflow & Core Tools · komal-SkyNET/claude-skill-homeassistant

home-assistant

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.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit
Author komal-SkyNETGitHub komal-SkyNET/claude-skill-homeassistant ↗Stars 958License MIT（仓库根 LICENSE 文件；gh api spdx MIT；plugin.json 中 "license": "MIT"）Commit 21126796f5
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Zero-code core: The skill includes no executable scripts; all capabilities are delivered via host tools + domain knowledge. Remote HA operations rely on three existing channels, with SKILL.md purely handling selection and orchestration.

skills/home-assistant-manager/SKILL.md
- Access via one or more of: `hass-cli` (REST), SSH `ha`, or an MCP server (see below).
Mechanism: Abstracting HA connectivity into three selectable transports, where the skill defines decision rules (when to use which) rather than implementing a client. Verified: The repository contains no scripts/ directory and no .sh/.py/.js files, confirming the zero-code claim.

MCP-first strategy: If an MCP server is attached to the host, use its first-class tools for real-time state inspection and service calls, avoiding hass-cli environment variable preload friction; references both official and community servers.

skills/home-assistant-manager/SKILL.md
juggling. Official `mcp_server` integration (HA core ≥2025.2) or community `ha-mcp`
Mechanism: Provides two MCP sources and version requirements (HA core ≥2025.2 introduces the official mcp_server integration) while noting community ha-mcp offers broader coverage (80+ tools). Note: SKILL.md only states preferences without installation commands; the only executable MCP instruction is the context7 entry in the README.

Deployment pipeline formalized into a strict 6-step workflow (edit → check → commit/push → pull → reload/restart → verify), explicitly defining changes as live only after Step 4 via remote git pull.

skills/home-assistant-manager/SKILL.md
Changes are not live until step 4.
Mechanism: Assumes the user's HA /config is itself a git repository; local editing + pushing serves only as staging, requiring a pull on the instance to take effect. This two-way consistency protocol distinguishes this skill from generic file-editing skills.

Fast-feedback bypass: Skips git to scp single files directly to /config on the instance followed by reload, tailored for dashboard iteration and rapid prototyping; git commits are deferred until stable.

skills/home-assistant-manager/SKILL.md
**Rapid iteration:** skip git and `scp` straight to the instance, then reload
Mechanism: Balances speed against traceability via dual fast vs. canonical paths. The trade-off is that scp-deployed files remain unversioned until committed, which the author makes explicit via 'Commit to git only once stable'.

Reload vs. restart decisions are table-driven rather than heuristic: domain entities (automations, scripts, scenes, templates, themes) use reload; core configuration.yaml, new integrations, platform sensors, MQTT platforms, and dashboard registries require restart.

skills/home-assistant-manager/SKILL.md
| automations, scripts, scenes, groups, template entities, themes | **reload** the domain (`hass-cli service call automation.reload`, etc.) |
Mechanism: Translates HA hot-reload semantics into an actionable decision matrix to prevent disruption from blanket restarts, outlining both appropriate restart scopes and their ~30s downtime cost.

Rigorous verification loop: Reload/restart, manually trigger automations for instant feedback, grep logs by change identifier, and verify entity states, explicitly noting the trap that automation.trigger bypasses conditions by default.

skills/home-assistant-manager/SKILL.md
`hass-cli service call automation.trigger --arguments entity_id=automation.<id>`
Mechanism: Accompanied by 'This bypasses conditions by default — it proves the actions, not the gate.', requiring skip_condition: false or genuine trigger testing with trace inspection. Turns hard-learned operational edge cases into discipline rather than generic testing advice.

Tiered knowledge architecture: SKILL.md remains lightweight (107 non-empty lines; streamlined from 627 lines in v1.0.0), delegating in-depth automation and Lovelace details to two reference files routed on-demand for progressive disclosure.

skills/home-assistant-manager/SKILL.md
**Full automation reference** (syntax table, `mode:` behavior, blueprints, trace debugging, pitfalls) → read [`reference/automations.md`](reference/automations.md) when writing or debugging automations.
Mechanism: Dedicated reference pointers in the Dashboards section route to reference/dashboards.md. v1.0.0 release notes document slimming SKILL.md from 627 to 106 lines and stripping redundant deployment commands, aligning with this layered architecture.

Embedded security boundaries: Confines file edits strictly to .yaml/.yml/.md, explicitly forbids reading or writing .env and secrets.yaml (enforcing !secret), mandates passing ha core check before restart, and requires ha backups new snapshots prior to risky changes.

skills/home-assistant-manager/SKILL.md
- Only edit `.yaml`/`.yml`/`.md`. Never read/write `.env` or `secrets.yaml`; use `!secret`.
Mechanism: Explicitly excludes credential files from agent read/write scope—a critical self-limiting design. The backup instruction 'it's cheap: `ssh root@homeassistant.local "ha backups new --name pre-<change>"`' serves as the paired rollback mechanism.

2Core Capabilities

01Entity state inspection and service calls via hass-cli REST or MCP
02Automation YAML authoring adhering to modern 2024.10+ syntax (triggers/conditions/actions, trigger:, action:) with mandatory stable id: and alias
03Automation mode execution semantics and blueprint (use_blueprint) usage, including blueprints directory conventions and reload requirements
04Jinja2 template type-safety enforcement: mandatory casting (| int(0) / | float(0)) prior to comparisons, default values to guard startup None states, and guards for missing state_attr
05Lovelace dashboard development: sections vs. panel view architecture, tile/heading/Mushroom card selection, Jinja template cards, and tablet grid layouts
06Deployment and hot-reloading: git pull production updates / rapid scp delivery with domain reload, distinguishing that direct .storage/lovelace.* edits require a restart due to in-memory caching
07Troubleshooting: Good/Bad log keyword patterns, automation trace inspection, and quick-reference trap resolution tables (symptom → cause → fix)
08Visual browser verification of dashboard changes: driving user-authenticated sessions via Claude-in-Chrome with screenshots and coordinate clicks (handling shadow DOM accessibility tree limitations)

3External Dependencies

KindDependency / Endpoint
apiHome Assistant REST API（经 hass-cli 调用）
clihass-cli（homeassistant-cli，pipx 安装）
clissh / scp / 远端 `ha` CLI（HA 宿主 root@homeassistant.local 为占位符）
apiHome Assistant MCP server（官方 mcp_server 集成 / 社区 ha-mcp）
networkContext7 MCP（HA 官方文档检索，可选）
networkGitHub（README 安装方式三：curl 下载仓库 tarball）
packageHACS（安装 custom:mushroom-* 卡片的前提）
cliClaude-in-Chrome 浏览器扩展（原生浏览器验证通道，参考中说明不用 Playwright/MCP）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation
For Agent Runtime
Graded/per-use authorization, sandbox recommended
For Administrators
Approval workflow, rollback support, full audit
Evidence & Triggers (File Paths & Excerpts)
  • scripts/: Executes local scripts or commands: ssh root@homeassistant.local "ha core check" (configuration validation, ~30-60s)
  • 网络端点: Declares external network access: http://homeassistant.local:8123 — Home Assistant REST API, hass-cli via HASS_SERVER
  • 本地工作目录: File I/O and artifact output: Writes .yaml/.yml within the HA instance /config (automations.yaml, scripts/scenes/templates, configuration.yaml)
Audit Notes: Amber (Caution Required). Evaluation factors: ① Real credential/environment variable exposure: SKILL.md checks `[ -n "$HASS_TOKEN" ]` and the README specifies `export HASS_TOKEN=your_long_lived_access_token` (long-lived access token), granting full HA REST API privileges in the host shell for hass-cli/MCP consumption; ② Third-party dependencies: Relies on community MCP server `ha-mcp` (explicitly cited in SKILL.md for 80+ tools) and the context7 remote MCP endpoint (https://mcp.context7.com/mcp), neither of which are maintained in this repository; ③ Operational outbound network traffic: Involves SSH/scp to the HA host and REST calls to homeassistant.local:8123 with write operations directly targeting live smart home hardware (restarts, config edits, automation triggers), where errors impact physical devices. Mitigating factors: Zero scripts or executable files in the repository, preserves TLS, avoids web scraping or batch harvesting, presents no arbitrary code execution surface, and establishes clear self-limitations (edits limited to .yaml/.yml/.md, never reads/writes `.env` or `secrets.yaml`, requires ha core check before restarts and ha backups new before critical edits, and prohibits credential entry during browser validation). Thus, it does not warrant Red; however, due to full-access token usage and third-party MCP dependencies, it cannot be downgraded to Yellow.

5Second-Pass Verification

  • [ok] skill 目录与 SKILL.md 定位（任务提示为待定位） — 实际路径 skills/home-assistant-manager/SKILL.md 存在，frontmatter name: home-assistant-manager 与 description 与任务给的一字不差；同目录含 reference/{automations,dashboards}.md 与 dashboard.png。
  • [ok] 『MCP 还是原生 REST？』的事实核对 — 两者都给，但性质不同：SKILL.md 只对 MCP 表达偏好（'MCP (preferred when available)'）并点名官方 mcp_server 集成与社区 ha-mcp，却未给任何 MCP 安装/配置命令；真正可直接执行的命令全是 hass-cli/ssh/scp。README 中唯一的 claude mcp add 是 context7（文档检索），不是 HA 控制通道。故『MCP 优先』属策略声明，可执行面是 CLI/SSH。
  • [ok] 凭证读取【决定档位的关键项】 — HASS_TOKEN 全仓命中 4 处：SKILL.md 第 22/24 行（hass-cli 需 HASS_SERVER/HASS_TOKEN、判存在 `[ -n "$HASS_TOKEN" ]`）、README 第 83 行（前置条件列出两个环境变量）、README 第 328 行（export 占位值）。无任何要求打印、回显、上传或写入 token 的指令；同时 SKILL.md 明令不读不写 .env/secrets.yaml。结论：存在环境变量依赖但无外泄路径，仍因持 token 的 CLI/MCP 通道记 orange。
  • [ok] 隐藏脚本 / 可执行代码核查 — glob 含隐藏文件全量结果仅 9 个：.gitignore、LICENSE、README.md、release.txt、SKILL.md、dashboard.png、reference/automations.md、reference/dashboards.md、.claude-plugin/{plugin,marketplace}.json、.github/FUNDING.yml。无 .sh/.py/.js/.ts，无 package.json，无 hook 配置。所以 security.scripts_executed 列出的都是 SKILL.md 指示宿主去跑的外部命令，不是仓库自带脚本。
  • [ok] 网络端点清点（区分服务端点与文档链接） — 真实服务端点仅两个：http://homeassistant.local:8123（HA REST，README 第 327 行）与 https://mcp.context7.com/mcp（README 第 347 行）。其余 URL 为 shields 徽章、github.com 仓库/安装 tarball、home-assistant.io 文档、buymeacoffee 按钮、semver.org，均非 skill 运行所需的调用面。websocket 与 supervisor 全仓零命中——SKILL.md 未声称也不使用 WebSocket API 或 Supervisor API。
  • [discrepancy] 功能声明 vs 实际能力（夸大检查） — README『Workflow Optimization』bullet 写 'No Restart for Dashboards'，而同仓库 dashboards.md 与 SKILL.md 都明确写直接文件编辑（scp/git）到 .storage/lovelace.* 可能不被识别、需 `ha core restart`（HA 缓存 lovelace store）。README 该 bullet 只在『UI 编辑 + 硬刷新』这一子情形下成立，属表述宽于实际；这是唯一发现的声明出入，不影响其余能力项（自动化语法、验证闭环、卡片选型等条条有正文支撑）。
  • [ok] reference 分层是否真实被引用（而非死文件） — SKILL.md 正文对 reference/automations.md 与 reference/dashboards.md 各有一条显式指路句（'→ read [`reference/…`](reference/…)'），且两个文件首行都反向声明 'Core deploy/verify rules are in `../SKILL.md`'，双向链接成立。
  • [ok] reload/restart 决策表与 HA 语义一致性 — 表内 reload 集合（automations/scripts/scenes/groups/template entities/themes）与 restart 集合（configuration.yaml core、新集成、platform sensors、MQTT 平台、lovelace_dashboards）与 automations.md 中 blueprint 改动需 reload、dashboard 注册需 restart 的说明自洽，无自相矛盾。

6Verdict & Scenarios

  • Transforms safe deployment into an actionable protocol: Strict 6-step workflow (validate → push → pull → reload/restart → verify) with Step 4 gating production, combined with tabular reload/restart decisions and log/trace verification to minimize configuration downtime.
  • Optimized 3-tier transport routing with documented failure modes: MCP-first, hass-cli secondary (including localhost connection diagnostics), and SSH fallback, preserving operational continuity across varied environments.
  • Disciplined knowledge layering: Lean 106-line core document paired with on-demand references; core rules handle routing and safety while deep reference tables (syntax, execution modes, card catalogs, troubleshooting) minimize token overhead without sacrificing depth.
  • Codifies counterintuitive edge cases to reduce debugging cycles: Highlights that automation.trigger skips conditions by default, .storage/lovelace.* modifications require restarts due to memory caching, and mode: single drops re-triggers (e.g., motion lights cutting off early).
  • Proactive credential boundaries: Limits edits exclusively to .yaml/.yml/.md, strictly denies access to .env/secrets.yaml, avoids handling credentials during browser verification, and relies on manual user site authorizations.
    • Best for: Self-hosted Home Assistant users who maintain /config in git with SSH, MCP, or hass-cli access—especially power users authoring automation YAML, resolving template typing issues, or building tablet dashboards requiring verified deployments. Also serves as an operational discipline layer for LLMs paired alongside existing HA MCP servers (complementary rather than redundant).
    Not for: HA beginners: Assumes existing SSH key-based access, a git-connected /config, and an understanding of reload vs. restart and .storage semantics without providing zero-knowledge setup tutorials. Pure GUI users lacking remote CLI access. Scenarios requiring built-in executable pipelines (the repository contains zero scripts). Multi-tenant or managed services lacking multi-instance isolation, RBAC, or audit logging.
    Install Agent-Ready
    ① Verified Mirror 2026-09-15
    Option A · Direct DownloadDownload home-assistant.tar.gz
    sha256: 23d2cb212a09fcaf…
    Option B · Copy Guide for Agent
    install.json
    Agents automatically download and verify mirrors from this JSON guide.
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit 21126796f5.