ホーム / 全スキル / ワークフロー＆基本ツール / home-assistant
English (EN)简体中文 (ZH)日本語 (JA)
ワークフロー＆基本ツール · komal-SkyNET/claude-skill-homeassistant

home-assistant

Home Assistantの設定を安全かつ迅速に管理します。YAML（自動化、ブループリント、スクリプト、シーン、テンプレート、MQTT）の編集とデプロイ、ha core checkによる検証、gitまたは高速scp経由のデプロイ、reloadとrestartの適切な使い分け、ログ・トレース・エンティティ状態からの変更検証、Lovelaceダッシュボードの構築を行います。SSH/hass-cli/MCP経由でのHA設定、自動化、テンプレート、ダッシュボード作業全般に使用します。

L4 高権限 · 段階的認可と監査V1 コミット固定コマンド実行ネットワーク通信ファイル書き込みDual-pass Audit
Author komal-SkyNETGitHub komal-SkyNET/claude-skill-homeassistant ↗Stars 958License MIT（仓库根 LICENSE 文件；gh api spdx MIT；plugin.json 中 "license": "MIT"）Commit 21126796f5
管理レベルは Skill の能力と推奨統制措置を示すものであり、品質や安全性の認証、利用可否の判定ではありません。使用の可否はユーザーおよび管理者が決定します。Agent 環境によって制約が異なるため、自動保護を仮定しないでください。第三者製 Skill の著作権は原著作者に帰属し、利用リスクは利用者が負います。

1仕組みと動作原理

本体コードゼロ：本スキルにはスクリプトが一切含まれず、すべての機能は「ホストツール＋ドメイン知識」によって提供されます。リモートHAインスタンスの操作は既存の3つの経路に依存し、SKILL.mdはそれらの選択とオーケストレーションのみを担います。

skills/home-assistant-manager/SKILL.md
- Access via one or more of: `hass-cli` (REST), SSH `ha`, or an MCP server (see below).
動作の仕組み：「HAへの接続方法」を3つの選択可能なトランスポートとして抽象化し、スキル側はクライアントを実装せず判定ルール（いつどれを使うか）のみを記述しています。検証結果：リポジトリ全体にscripts/ディレクトリや.sh/.py/.jsファイルが存在しないため、「コードレス」であることが確認されています。

MCP優先戦略：ホストにMCPサーバーが接続されている場合、そのファーストクラスツールを使用してリアルタイムの状態取得やサービス呼び出しを行い、hass-cliの環境変数読み込みに伴うオーバーヘッドを回避します。公式統合とコミュニティ版の両方に対応しています。

skills/home-assistant-manager/SKILL.md
juggling. Official `mcp_server` integration (HA core ≥2025.2) or community `ha-mcp`
動作の仕組み：MCPの2つの入手元とバージョン要件（公式mcp_server統合にはHA core ≥2025.2が必要）を示し、コミュニティ版ha-mcpの方がツール数が多い（80以上）ことを明記しています。なお、SKILL.mdは「優先度を宣言」しているのみでインストール・設定コマンドは含まず、実際に実行可能なMCPコマンドはREADMEにあるcontext7のもののみです。

デプロイパイプラインを厳格な6ステップ（edit→check→commit/push→pull→reload/restart→verify）として固定化し、リモートでのgit pullを本番反映アクションと定義して「ステップ4完了後に初めて反映される」ことを明確化しています。

skills/home-assistant-manager/SKILL.md
Changes are not live until step 4.
動作の仕組み：ユーザーのHA /config自体がgitリポジトリであることを前提とし、ローカルでの編集＋pushはステージングに過ぎず、インスタンス上でのpullによって初めて反映される設計です。汎用的な「ファイル編集」スキルとは異なり、両端の一貫性プロトコルを定めている点が特徴です。

短サイクル用のバイパス：gitをスキップし、単一ファイルをインスタンスの/configへ直接scpした上でreloadを実行するルートを用意。ダッシュボード構築や試行錯誤の多い反復作業に活用し、安定した段階でのみgitへコミットします。

skills/home-assistant-manager/SKILL.md
**Rapid iteration:** skip git and `scp` straight to the instance, then reload
動作の仕組み：「高速パス」と「正式パス」を併用してスピードとトレーサビリティのバランスを取ります。代償としてscpされたファイルはコミットまでバージョン管理外となりますが、作者は「Commit to git only once stable」としてこのトレードオフを明確にしています。

reloadとrestartの選択は感覚ではなく変更タイプに応じたマトリクス表で決定：ドメインエンティティ（automation/script/scene/template/theme）にはreloadを使用し、コアのconfiguration.yaml、新規統合、プラットフォーム型センサー、MQTTプラットフォーム、ダッシュボードレジストリにはrestartを適用します。

skills/home-assistant-manager/SKILL.md
| automations, scripts, scenes, groups, template entities, themes | **reload** the domain (`hass-cli service call automation.reload`, etc.) |
動作の仕組み：HAのホットリロード仕様を実行可能な判定表へと落とし込み、「すべてrestart」によるサービス中断を防ぎます。判定表ではrestartの対象範囲と約30秒のダウンタイムコストも併記されています。

「動くはず」に頼らない検証ループ：reload/restart後に手動で自動化をトリガーして即座にフィードバックを取得し、変更識別名でログをgrepした上で最終的なエンティティ状態を確認。automation.triggerがデフォルトでconditionsをスキップする仕様上の罠も明記しています。

skills/home-assistant-manager/SKILL.md
`hass-cli service call automation.trigger --arguments entity_id=automation.<id>`
動作の仕組み：コマンド直下に「This **bypasses `conditions` by default** — it proves the actions, not the gate.」と記載し、`skip_condition: false`を追加するか、実際のトリガーを用いてトレースを確認するよう求めています。一般的な「テストしてください」ではなく、実際の運用上の落とし穴をルール化しています。

知識の階層化：SKILL.md本体は軽量に保ち（107行、v1.0.0リリース時に627行から106行へスリム化）、自動化とLovelaceの詳細知識は2つの参照用リファレンスファイルに分離。SKILL.mdから必要に応じて段階的にロードする構成を採用しています。

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.
動作の仕組み：ダッシュボードセクションからreference/dashboards.mdへのポインタを設置。v1.0.0のrelease.txtにはSKILL.mdを627行から106行に削減し、重複するデプロイ手順やコマンド記述を整理した経緯が記録されており、この階層化戦略と一致しています。

本文に組み込まれたセキュリティ規約：編集対象を.yaml/.yml/.mdのみに限定し、.envおよびsecrets.yamlの読み書きを明示的に禁止（!secretを使用）。restart実行前にはha core checkの成功を必須とし、危険な変更の前にはha backups newによるスナップショット取得を義務付けています。

skills/home-assistant-manager/SKILL.md
- Only edit `.yaml`/`.yml`/`.md`. Never read/write `.env` or `secrets.yaml`; use `!secret`.
動作の仕組み：認証情報ファイルをエージェントの読み書き対象から能動的に除外する重要な自己制限設計です。バックアップに関する記述「it's cheap: `ssh [email protected] "ha backups new --name pre-<change>"`」が安全なロールバック手段として機能します。

2コア機能

01hass-cli RESTまたはMCP経由でのエンティティ状態取得およびサービス呼び出し
02自動化YAMLの作成：2024.10以降のモダン構文（triggers/conditions/actions、trigger:、action:）を標準とし、永続的なid:およびaliasの設定を必須化
03自動化の実行モード（mode）およびブループリント（use_blueprint）の利用（blueprintsディレクトリの規約とreload要件を含む）
04Jinja2テンプレートの型安全性ルール：比較前の強制キャスト（| int(0) / | float(0)）、起動時Noneを防ぐデフォルト値の設定、欠落したstate_attrのガード処理
05Lovelaceダッシュボード開発：sections/panelビューの選択、tile/heading/Mushroomカードの選定、Jinjaテンプレートカード、タブレット向けグリッドレイアウト
06デプロイとホットリロード：git pullによる本番反映 / scpによる高速転送とドメイン単位のreload、メモリキャッシュ仕様により.storage/lovelace.*の直接編集時にrestartが必要となる仕様の識別
07トラブルシューティング：ログキーワードパターン（Good/Bad）、自動化トレースの解析、よくある落とし穴のクイックリファレンス（症状→原因→修正手順）
08ブラウザを使用したダッシュボード変更の視覚的検証：Claude-in-Chrome経由で認証済みブラウザを操作し、スクリーンショット取得と座標クリックを実行（shadow DOMに起因するアクセシビリティツリーの制限に対応）

3外部依存関係

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

4推奨統制措置と判定根拠

安全運用のための推奨統制措置
Agent 向け
段階的・都度認可、サンドボックス推奨
管理者向け
承認フロー、ロールバック可能、全履歴監査
判定根拠（ファイルパスと抜粋）
  • scripts/: ローカルスクリプトまたはコマンドの実行: ssh [email protected] "ha core check"（設定検証、所要約30〜60秒）
  • 网络端点: 外部ネットワークアクセスの宣言: http://homeassistant.local:8123 — Home Assistant REST API、HASS_SERVER経由のhass-cli
  • 本地工作目录: ファイル読み書きおよび成果物の出力: HAインスタンスの/config配下にある.yaml/.yml（automations.yaml、scripts/scenes/templates、configuration.yaml）
監査ノート： オレンジ（使用時に注意が必要）。判定根拠：① 認証情報および環境変数の実在：SKILL.mdは`[ -n "$HASS_TOKEN" ]`の判定を要求し、READMEでは`export HASS_TOKEN=your_long_lived_access_token`（長期アクセストークン）の設定が求められます。このトークンはHAに対する完全なREST API権限を持ち、ホストのシェル環境上でhass-cliやMCPにより利用されます。② サードパーティ製コンポーネントへの依存：コミュニティ製MCPサーバー`ha-mcp`（SKILL.mdで80以上のツールを持つとして明記）およびcontext7リモートMCP（https://mcp.context7.com/mcp）を利用しており、いずれも本リポジトリ外のリソースです。③ ネットワーク通信が閲覧ではなく運用目的である点：HAホストへのSSH/scpやhomeassistant.local:8123へのRESTリクエストを含み、書き込み操作が実環境のスマートホーム機器に直接作用します（restart、設定変更、自動化のトリガーなど）。誤操作が物理機器に影響を及ぼす可能性があります。緩和要素：リポジトリ内にスクリプトや実行可能ファイルは一切存在せず、TLSの無効化、スクレイピング回避、バッチデータ収集、任意コード実行の余地はありません。さらに作者により「.yaml/.yml/.mdのみを編集対象とする」「`.env`や`secrets.yaml`の読み書きを禁止」「restart前にha core checkを必須化」「危険な変更前にha backups newを実行」「ブラウザ検証で認証情報を入力しない」という厳格な自己制限が組み込まれています。以上より赤（危険）には該当しないものの、フルアクセス権限トークンの取り扱いおよびサードパーティ製MCPへの依存があるため、黄（低リスク）への引き下げは行いません。

5二重目の独立検証

  • [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 的说明自洽，无自相矛盾。

6結論

  • 「安全な本番反映」を標語ではなく実行可能なプロトコルとして定義：validate→push→pull→reload/restart→verifyの6ステップを厳格化し、ステップ4で初めて反映されることを明確化。reload/restart判定表とログ・トレース検証を組み合わせることでHAの障害リスクを最小化します。
  • 3経路の最適選択と失敗パターンの明記：MCPを最優先、hass-cliを次点（環境変数未設定によるlocalhost誤接続の診断を含む）、SSHをバックアップとし、環境が変わっても同一の手順で運用可能です。
  • 抑制された知識の階層構造：106行のメインドキュメントと必要時に読み込む2つのリファレンスで構成。本筋には意思決定ルールと規約のみを残し、詳細な表（構文比較、mode、カードカタログ、落とし穴一覧）を参照側に逃がすことで、網羅性を保ちながらトークン消費を抑制しています。
  • 直感に反する落とし穴を事前にドキュメント化しデバッグ工程を削減：automation.triggerが条件をスキップする仕様、.storage/lovelace.*の直接編集時にrestartが必要な理由（メモリキャッシュ）、mode: singleによる再トリガー無視（人感センサーライトの意図せぬ消灯など）、実環境特有のハマりどころを網羅しています。
  • 能動的な認証情報境界の管理：編集対象を.yaml/.yml/.mdに限定し、.env/secrets.yamlへのアクセスを拒否。ブラウザ検証時にも認証情報を入力せず、ユーザーによる手動認証に委ねることで権限を安全に管理します。
    • 最適な用途： HAの/configをgit管理しており、SSH（またはMCP/hass-cli）アクセスが可能なセルフホストHome Assistantユーザー。特に自動化YAMLの作成、テンプレートの型エラーデバッグ、タブレットや壁掛けダッシュボードの構築を頻繁に行い、変更を確実に検証したい上級者に最適です。また、導入済みHA MCPサーバーと併用し、LLMにHA運用の規約を補完するナレッジ層としても適しています（READMEにて相互補完関係であることが明記されています）。
    不向きな用途： HA初心者には不向きです（SSH鍵認証の設定、git接続された/config、reload/restartおよび.storageの仕様理解を前提としており、ゼロからの構築手順は提供しません）。リモートCLIアクセス環境がなく、HA Web UIのみで操作する完全なGUIユーザー。スキル自体に実行スクリプトやパイプラインが含まれていることを期待する用途（スクリプトは一切含まれず、ホスト環境のツールに依存します）。マルチインスタンス、権限分離、監査ログを必要とするマルチユーザー管理やマネージドサービス環境。
    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
    Agent はこの JSON ガイドから自動的にダウンロードして検証します。
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit 21126796f5.