komal-SkyNET/claude-skill-homeassistant · 上手攻略

  • 仓库：komal-SkyNET/claude-skill-homeassistant
  • 链接：https://github.com/komal-SkyNET/claude-skill-homeassistant
  • 分类：Claude Code skill / Home Assistant
  • 作者：spark
  • 更新：2026-08-25

是什么

claude-skill-homeassistant 是把 Claude Code 包装成 Home Assistant 配置与自动化专家的一个 skill 仓库，作者 Komal Venkatesh Ganesan，MIT License。仓库同时以两种形态分发：

  • Claude Code skill：skills/home-assistant-manager/SKILL.md 是核心，遵循 Anthropic 官方 Claude skills 规范（YAML frontmatter + name + description + 分节内容 + examples）。
  • Self-hosted plugin marketplace：仓库根目录下 .claude-plugin/ 既有 plugin.json 也有 marketplace.json，可以走 /plugin marketplace add 一行安装。

skill 的定位是"编码工作流与判断经验"：git/scp 双线流程、reload-vs-restart 决策树、validate-before-restart 纪律、verify-from-logs-and-traces 闭环、模板类型安全规则、dashboard 缓存陷阱、现代 automation YAML 语法（2024.10+ 起的 triggers:/conditions:/actions:，以及 action: 而非 service:）。它不是 MCP server —— 它和 MCP 是互补关系（见下）。

⚠️ 本攻略所有安装命令（/plugin marketplace add / /plugin install / pipx install homeassistant-cli / claude mcp add ... context7）、HA 语法版本号（2024.10+）与文件结构均直接取自 GitHub README；当前 HA 版本与 Claude Code plugin 命令未必与本文落盘时一致，使用前请查 Home Assistant 官方 release notes 与 Claude Code 文档。

解决什么问题

Home Assistant 用户用 Claude 改配置时常踩几个坑：

  1. 写出过时的 automation YAML：旧版 trigger: / condition: / service: 写法被 HA 2024.10+ deprecate，LLM 容易按老 prompt 数据生成。
  2. 改完直接重启 HA：dashboard / automation 配置变更大多只需要 reload；盲目 restart 会让家里所有自动化掉线。
  3. 没有验证就 commit：自动化写完没看 trigger 是否真被跳过（automation.trigger-skips-conditions gotcha）、模板类型是否对（str vs int）、Lovelace 是否真注册。
  4. 调试靠猜：日志模式不懂，trace 没拉。
  5. dashboard 适配：不同尺寸平板（7"/11"/13"）的 grid / card 选型没经验。

skill 把这些"程序 + 判断"压成一个 skill，让 Claude 在对话里自动应用：写现代语法、自动判断 reload vs restart、强制 validate 再部署、部署后立刻手动 trigger + 看 logs + 看 traces，全流程跑通才让 commit。

快速安装

准备（前置条件）

  • Claude Code 已安装并登录。
  • Home Assistant 实例开启 SSH；/config 是 git 仓库。
  • 本地：hass-cli + SSH 密钥认证。
  • 环境变量：HASS_SERVER、HASS_TOKEN（long-lived access token）。
# 验证 SSH + HA CLI
ssh root@homeassistant.local "ha core info"

# 装 hass-cli
pipx install homeassistant-cli

# 写环境变量（加到 ~/.bashrc / ~/.zshrc）
export HASS_SERVER=http://homeassistant.local:8123
export HASS_TOKEN=your_long_lived_access_token

# 验证
hass-cli state list

# 让 /config 成 git 仓库
cd /config
git init
git remote add origin your-repo-url

装 skill —— 推荐方式（plugin marketplace）

在 Claude Code 里跑：

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

不需要手动 clone；装完跑 /plugin 确认 home-assistant-manager 在列表里并启用。

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

备选方式 2：curl tarball 解压

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

⚠️ tarball 命令里的 --strip-components=2 直接来自 README；不同 GitHub archive 顶层目录名（<repo>-<branch>）变化时需要调整 2 这个数字，例如 default branch 不再是 main 时 strip 计数可能要改。

可选：接 Context7（HA 官方文档 MCP）

claude mcp add --transport http context7 https://mcp.context7.com/mcp \
  --header "CONTEXT7_API_KEY: your_api_key"

skill 会在需要时优先用 MCP 查 HA 官方文档。

核心用法

skill 装好后无需手动调用，Claude 会在对话上下文涉及 HA 配置时加载并应用。三类典型工作流：

1. 写新自动化（"前门开 5 分钟发通知"）

skill 引导 Claude 走：

  1. 写现代 YAML（triggers: / conditions: / actions: + action: 替代 service:）。
  2. scp 部署 → 立即可测。
  3. reload automations（不需要 restart）。
  4. 手动 trigger。
  5. 检查 logs / traces。
  6. 确认通知送达后 git commit。

2. 写 11 寸平板 dashboard

skill 让 Claude 用 3 列 grid + Mushroom card 做触控友好布局，按设备类型选 Tile / Template / Auto-entities，写 lovelace_dashboards 注册项 + .storage/<dashboard>.json，scp 部署，浏览器刷新即生效（dashboard 永远不重启 HA）。

3. 调试模板错误（"TypeError: str vs int"）

skill 让 Claude 先查 logs → 定位模板错误（缺 | int filter）→ 改语法 → scp 部署 → 手动 trigger → 复检 logs → git commit。

模板示例（Jinja2）

skill 内置常见模板片段，按需加载 reference/automations.md / reference/dashboards.md：

{# 门 / 窗数量统计 + 颜色编码 #}
{% set ns = namespace(open=0) %}
{% for s in states.binary_sensor | selectattr('attributes.device_class', 'defined')
   | selectattr('state', 'eq', 'on') %}
  {% if 'door' in s.attributes.device_class or 'window' in s.attributes.device_class %}
    {% set ns.open = ns.open + 1 %}
  {% endif %}
{% endfor %}
{{ ns.open }}

升级 / 更新

/plugin marketplace update claude-skill-homeassistant
/plugin update home-assistant-manager

典型适用场景

  • 家里有 HA 实例、又想用 LLM 帮忙写 / 改配置 / 调试的人。
  • 墙挂平板做控制面板：skill 提供 7" / 11" / 13" 适配经验。
  • 多设备家庭：门 / 窗 / 灯 / 温控 / 媒体中心统一改写。
  • 调试自动化莫名其妙不触发（trigger-skips-conditions gotcha）：skill 强制走 trigger + trace + log 三件套。
  • 想给团队 / 家庭成员"半托管"HA：Claude 处理 90% 改动，人只 review commit。

坑与注意

  • skill ≠ MCP：skill 教 Claude 怎么写 / 改 / 验证你的 /config；MCP server（如官方 mcp_server integration / 社区 ha-mcp）给 Claude 在线工具（读 entity state / call service / 控制灯）。两者组合最强：MCP 提供状态查询，skill 提供写作流程与判断。
  • 没装 MCP 也能用：fallback 到 SSH + hass-cli；只是少了实时状态查询。
  • 必须跑在 HA 配置 git 仓库根目录：skill 假设 /config 有 .git，否则 scp 流程之外没法做"稳定版本化"。
  • HA 版本 ≥ 2024.10：skill 默认写新语法（triggers: / action: 等）。如果你在跑更老的 HA，要么升级 HA 要么手动改写。
  • 授权风险：HASS_TOKEN 是 long-lived access token，等同 HA 管理员权限；不要 commit 到 git / 不要贴公共频道。
  • dashboard 部署不要重启 HA：skill 强制 scp + 浏览器刷新；不要误用 ha core restart 触发家庭自动化全断。
  • automation.trigger-skips-conditions gotcha：HA 中 trigger 触发会跳过 conditions 直接执行 actions；skill 强制查 trace 确认行为。
  • ⚠️ 命令 / 版本核验状态：/plugin marketplace add / /plugin install 是 Claude Code 当前文档命令；HA 现代语法版本（"2024.10+"）来自 README；Claude Code plugin schema 与 Context7 MCP endpoint 未在本攻略独立对照官方文档 —— 升级前请查 Claude Code + HA 官方 release notes。

与同类对比

  • Anthropic 官方 skills 仓库（anthropics/skills）：通用规范与样例 skill；本仓库是垂直领域（HA）的实现范例。
  • HA 官方 MCP mcp_server integration / 社区 ha-mcp：提供"读 state / call service"工具，不教 Claude 写配置；本 skill 教写配置，不直接调设备。
  • 手写 prompt + 通用 LLM：容易写出过时语法、不做 validate、reload vs restart 凭感觉；skill 把这些 procedure 编码进去。
  • VS Code HA 扩展 / Home Assistant Community Add-ons：GUI 编辑器流派，专注代码补全与本地调试；本 skill 是"对话式"工作流。
  • 裸 ssh + 手敲 YAML：零依赖，但每次都要自己记得 reload vs restart / 验证 trace。

一句话推荐

已经在用 Claude 改 HA 配置、又常被"语法过时 / 凭感觉 restart / 写完不验证"坑的人 —— 装上 home-assistant-manager skill，让 Claude 强制走"scp → reload（不 restart）→ trigger → log → commit"流程。