teach your AI home assistant
WoowTech Skill 手冊

裝一顆 Skill，AI 立刻學會怎麼跟你家 HA 打交道

Skill 是給 AI agent 看的「工作手冊」：一個資料夾、一份 SKILL.md，裝進 Claude Code／OpenClaw／Cursor／Codex 等支援的 harness，AI 遇到對應情況就會照著做。這本手冊挑好 10 顆與 Home Assistant 相關的實用 skills，附 6 大熱門集合型錄、安裝速查、相容性與安全守則。

調查基準：本冊集合規模、星數與維護狀態為 2026-08-20 GitHub 公開快照，會隨時間變動；安裝前建議點進原始 repo 再確認一次。

Skill 是什麼、為什麼要裝

把 Claude／Codex／Gemini／OpenClaw／Hermes 之類的 AI agent 想成很聰明的實習生：任何家用系統都能聊，但「你家 HA 的實體命名、area 規劃、既有 blueprint、Zigbee 拓樸」它一定不會通靈。Skill 就是丟給 AI 的 handover 文件——把「遇到 HA 什麼場景，照什麼步驟做」寫成 Markdown，放到技能資料夾，AI 遇到就會翻出來照做。

  • 裝別人寫好的：HA 管理、ESPHome 韌體、Dashboard 設計、Blueprint 匯入、custom integration 開發——社群已寫好一堆。
  • 之後寫自己的：家裡的獨門流程（洗衣機提醒、能源週報）也能包成 skill，寫法見本冊 SKILL.md 規格 一節。

Skill 跟 Assist 語音助理、Integration、Blueprint 是完全不同的東西——它是加在你用的 AI agent 那一端，不是加在 HA 那一端。HA 你可能一行都不動。

怎麼裝（3 分鐘版）

SKILL.md 這個規格由 Anthropic 發起（anthropics/skills），已被 Claude Code、Codex、Gemini CLI、Cursor、OpenCode、OpenClaw、Hermes 等主流 agent harness 採用。裝法依 harness 不同略有差異，共同步驟是：

  1. 打開你的 agent harness 的 Skills／Plugins 面板

    Claude Code：Settings → Skills；OpenClaw / Hermes：Skills 面板；Codex：~/.codex/skills/ 目錄。

  2. 貼上 package spec，按 Install

    各 harness 支援的寫法略有差異，最常見這幾種：

    # GitHub repo（最常用）
git:github.com/komal-SkyNET/claude-skill-homeassistant

# 釘住版本（tag 或 commit，正式環境建議用）
git:github.com/anthropics/skills@v1.0.0

# npm 套件
npm:@scope/some-skill

# 本地路徑（自己寫的、或從 monorepo clone 下來的子目錄）
~/skills/my-ha-skill

  3. Reload session 驗證

    裝完開新 session（skill 是 session 開始時載入），問它：「目前載入了哪些 skill？」確認有進到清單。

  4. 先讀後用：問 AI 這顆 skill 會做什麼

    裝完別急著讓它跑，先叫 AI 讀 SKILL.md 摘要給你聽——這也是 安全守則 的第一條。

提示：Monorepo（例如 anthropics/skills、tonylofgren/aurora-smart-home）整包裝進去，多數 harness 會遞迴掃描所有 SKILL.md。只想要其中一顆時，clone 下來後用本地路徑指向那個子資料夾——目前 git spec 沒有標準的「只裝子目錄」語法。

精選十顆（HA 視角）

從熱門集合與 HA 專門 repo 裡挑出來、對智慧家庭最對口的實用款。由「最對口／最推薦入門」往下排：

Skill它幫你做什麼安裝 spec
claude-skill-homeassistant
≈791★		 目前 HA 專用 skill 之王：寫／改 automation、blueprint、dashboard，管 add-ons，讀 log，跑 template 測試。最對口也最高風險——會動線上 HA 設定，先在測試機／備份後驗證。 git:github.com/komal-SkyNET/claude-skill-homeassistant
homeassistant-claude-kit
≈118★		 AI-guided 全套包：automation 樣板、行動優先 React dashboard 模板、Claude Code skills 管 config。適合想有「一站式體驗」而不是自己拼湊的用戶。 git:github.com/dcb/homeassistant-claude-kit
aurora-smart-home
≈102★		 整個智慧家庭的 skill 集合：Home Assistant、ESPHome、Node-RED、custom integration、dashboard、甚至硬體 PCB。想同時管 HA + ESPHome 韌體的必裝。 git:github.com/tonylofgren/aurora-smart-home
docx / pdf / pptx / xlsx
official		 官方文件四件套。對 HA 家庭來說：能源分析輸出 Excel、家電保固清單存 PDF、家庭週報生成 Word、社區發表用 PPTX。 git:github.com/anthropics/skills
skill-creator
official		 讓 AI 幫你把家裡的獨門流程（洗衣提醒、能源週報、換濾網警報）包成新 skill——AI 教 AI，比自己讀 spec 快多了。 git:github.com/anthropics/skills
claude-homeassistant-plugins
≈26★		 HA plugins / skills / agents marketplace，含 MCP hook 與多個對應的 skill 目錄，適合當「HA plugin 開發套件」用。 git:github.com/ESJavadex/claude-homeassistant-plugins
ha-nova
≈21★		 Lean relay + LLM skills 給 Claude Code／Codex／OpenCode 用，把 HA API 呼叫抽成薄層。跨 agent 想共用一份 HA skill 選這個。 git:github.com/markusleben/ha-nova
HA_Bubble_Skill
≈13★		 Dashboard 專用：Bubble Card／Streamline Card／Sidebar Card／Mushroom 的建構 skill，含 WCAG 色彩檢查與整套故障排除。要做漂亮儀表板必裝。 git:github.com/johnnyh1975/HA_Bubble_Skill
grill-me
from mattpocock/skills		 動工前被 AI 連環拷問，把「我要重寫全屋 automation」這種大工程的需求問到清楚才開工。純 Markdown，跨 agent 通用。 git:github.com/mattpocock/skills
defuddle
from kepano/obsidian-skills · ≈4.7 萬★		 把網頁擷取成乾淨 Markdown——家電說明書、HA 社群解法、YouTube 逐字稿存進家庭知識庫必備。省 token 又乾淨。 git:github.com/kepano/obsidian-skills

六大熱門集合型錄

想一次裝一整包、或自己逛著挑，從這六個入口開始：

anthropics/skills

官方示範＋規格所在地 · ≈17 萬★ · 極活躍

Agent Skills 規格與官方 template 的家。19 顆 skill 含文件四件套（docx/pdf/pptx/xlsx）、canvas-design、mcp-builder、skill-creator。HA 家庭第一包就裝這個。

git:github.com/anthropics/skills

注意：文件四件套為 source-available 非開源；部分 skill 附 scripts 需要 Python／JS 環境。

tonylofgren/aurora-smart-home

HA 智慧家庭專門集合 · ≈102★ · 對口

目前最完整的智慧家庭多 skill 集合：home-assistant、esphome、node-red、ha-dashboard-design、ha-integration-dev、hacs、fab-ready hardware 設計。

git:github.com/tonylofgren/aurora-smart-home

注意：星數少＝審閱的人少，它會指導 agent 改你的 HA 設定——匯入前自己把 SKILL.md 讀一遍。

komal-SkyNET/claude-skill-homeassistant

HA 專用單一 skill · ≈791★ · 極活躍

單一 skill 但功能最完整的 HA 管家 agent。README 有教怎麼跟 Claude Code 對話直接改 HA 設定、拉 log、跑 template 測試、加自動化。

git:github.com/komal-SkyNET/claude-skill-homeassistant

建議先在測試 HA 或做完備份後再用；正式環境釘 @tag。

kepano/obsidian-skills

筆記／家庭知識庫 · ≈4.7 萬★ · Obsidian CEO 出品

5 顆：obsidian-markdown、bases、json-canvas、obsidian-cli、defuddle。用 Obsidian 做家庭知識庫必裝；defuddle 不用 Obsidian 也超好用。

git:github.com/kepano/obsidian-skills

obsidian-cli 需本機裝 CLI；HA add-on 容器內以 vault 資料夾操作為主。

mattpocock/skills

Real Engineers 用 · ≈22 萬★ · 極活躍

grill-me、tdd、diagnosing-bugs、handoff、teach——工程向為主，但 grill-me／handoff 對「重寫家裡全套 automation」「換代新家配置 HA」這種規劃型任務都超好用。純 Markdown、跨 agent 可用。

git:github.com/mattpocock/skills

hesreallyhim/awesome-claude-code

策展入口 · ≈5.3 萬★

Claude Code 生態圈的 awesome list：skills、agents、狀態列、developer tooling、plugins 都有。當目錄逛，看到對眼的再點進去裝原始 repo。

# 當清單用，不建議整包安裝
https://github.com/hesreallyhim/awesome-claude-code

品質參差，逐顆檢視再裝。

備查（HA 相關但範圍小或活躍度低）：nolte/claude-home-assistant（HA 開發向，含 Lovelace／blueprint／ESPHome／add-on skills）、dallanwagz/untether（把雲端 BLE 裝置反向工程為本地 HA integration）、smalltv-ultra-skill（GeekMagic SmallTV Ultra 韌體開發）——星數少，適合有明確場景時再看。

相容性須知

SKILL.md 規格已被 Claude Code、Codex、Gemini CLI、Cursor、OpenCode、OpenClaw、Hermes 等主流 agent harness 採用；純 Markdown 的 skill 幾乎到處能跑。會「退化」的只有三種情況：

  • 依賴 Claude Code 專屬機制（hooks、plugin 指令、subagent 派工）——skill 本文仍可讀，但自動觸發行為可能不完整。
  • 依賴特定 MCP／SaaS 帳號——例如 HA 相關 skill 多半假設你有配好 ha-mcp-woow 或官方 MCP Server integration；沒接就沒用。
  • scripts/ 需要容器內沒有的 runtime——若在 HA add-on 容器內跑 agent，Python 套件、Node 版本要對得上，純 Markdown skill 相容性最好。
觀念：挑 skill 的第一準則不是星數，是「它假設的環境你有沒有」。對 HA 相關 skill 尤其重要——多數假設你已經有 HA + MCP + 對應 integration。

安全守則

注意：Skill 的本質是「餵給 agent 的指令」。裝第三方 skill＝讓一段陌生文字指揮你家的 AI 去動你家的 HA。
  • 先讀後裝：安裝前把 SKILL.md 打開讀一遍，或叫 AI 先讀給你聽：「先讀這顆 skill 的 SKILL.md 內容，告訴我它會做什麼、有沒有動我家 HA config 的風險，我同意再裝。」
  • 會動 HA config 的先做完整備份：像 claude-skill-homeassistant、aurora-smart-home 這類會直接改 automation／dashboard／configuration.yaml 的，先按 Settings → Backups 手動備份——搞砸還能還原。
  • 先在測試 HA 實例驗證：如果家裡的 HA 已經很複雜，強烈建議另開一個乾淨的 HA container 當測試機，skill 動作驗證過再放到正式機。
  • 正式環境釘版本：用 @tag 或 @commit 釘住，避免上游改內容你無感升級。
  • 暴露給 AI 的實體要挑：Settings → Voice Assistants → Expose 只勾必要的區域／實體。門鎖、警報、電源總開關這類「操作無法回復」的先別給。
  • 星數＝人氣，不＝安全：熱門集合一樣要看它拿什麼權限做什麼事——尤其是有 scripts/ 的 skill。

SKILL.md 規格速查

一顆 skill 的最小骨架（詳細規格見 anthropics/skills）：

washer-notify/
├── SKILL.md          ← 唯一必要檔案
└── references/       ← 選用附件（AI 用到才讀）
    └── ha-service-map.md

# SKILL.md 內容
---
name: washer-notify
description: |
  當使用者問「洗衣機洗完了嗎」「該收衣服了嗎」，或提到
  自動化洗衣機提醒時觸發。可透過 HA API 讀取
  sensor.washer_power 判斷是否處於運轉/待機/完成狀態。
license: MIT
compatibility:
  agents: [claude-code, opencode, openclaw, hermes]
  mcp: [ha-mcp-woow, home-assistant/mcp-server]
allowed-tools: [ha_get_state, ha_get_history, notify_send]
---

# 洗衣機提醒 skill

當使用者提到洗衣機時，先讀 sensor.washer_power 過去 15 分鐘的
歷史：如果從 >100W 掉到 <5W 並持續 3 分鐘以上，回覆「洗完了」；
還在運轉則回覆預估剩餘時間（依平均運轉 45 分鐘估算）。

若使用者要求自動提醒，用 ha_config_set_automation 建一條：
trigger: sensor.washer_power < 5W 持續 3 分鐘
action: notify.mobile_app_myphone
先給使用者 YAML 摘要，同意再套用。
欄位必填說明
name是小寫英數與連字號，1–64 字元。
description是做什麼＋何時用。AI 靠這行決定要不要載入——把使用者會講的話寫進去。
license否建議寫，讓別人知道能不能改。
compatibility否標注支援的 agent／MCP，跨 harness 分享時很有用。
allowed-tools否限制 skill 只能呼叫哪些工具，安全防線。

慣例：SKILL.md 保持精簡，附件放 references/、scripts/、assets/，AI 需要才讀，避免吃爆 context。HA 相關 skill 建議在 references/ 放一份「service 對照表」，AI 呼叫前先查。

常見問題

裝了但完全沒反應？
先開新 session（skill 是 session 開始時載入）。再問 AI「目前載入了哪些 skill？」確認有進清單；有進但不觸發，多半是 description 沒涵蓋你的講法——直接點名：「用 claude-skill-homeassistant 幫我做這件事」。
Skill 跟 HA 的 Blueprint、Integration、Assist 差在哪？
位置不同：Skill 加在你用的 AI agent 那一端（Claude Code／OpenClaw／...），HA 一行都不動。Blueprint／Integration／Assist 都是加在 HA 那一端。Skill 教「AI 怎麼跟 HA 打交道」，Blueprint 教「HA 怎麼自己處理事件」——兩者不衝突，可以疊。
Skill 裝太多會怎樣？
每顆 skill 的名稱與描述會佔 system prompt 的 context，裝幾十包會讓 AI 分心也變貴。原則：常用的留著（HA 相關的 3–5 顆＋官方文件套），試玩過不用的就移除。
可以只裝 monorepo 裡其中一顆嗎？例如只要 aurora-smart-home 裡的 esphome？
git spec 目前沒有標準子目錄語法。實務做法：clone 到本機，把想要的那個子資料夾（含 SKILL.md）放到 harness 的 skills 目錄（Claude Code 是 ~/.claude/skills/），或用本地路徑安裝。
會 skill 動壞我的 HA 嗎？怎麼救？
會，尤其是有 ha_config_set_* 權限的 skill。所以安全守則第 2 條寫「先做完整備份」——搞砸就 Settings → Backups → Restore 回去。若已經沒備份、正式機被改壞，看 configuration.yaml 的 git／snapshot 版本；HA Green／Yellow 出廠的 WoowTech 機種有每日自動快照。
怎麼自己寫一顆 HA skill？
最快：裝 skill-creator（anthropics/skills 內），叫它「幫我把『家庭週報產出流程』寫成 skill」，你邊描述邊改，10 分鐘出雛型。或依 SKILL.md 規格 節裡的範例自己起頭。

把這本帶走

整本是自包含單檔 HTML，圖示全部內嵌，下載後離線可開。集合資訊會過期，重要決定前回資源總覽看線上版。

下載本冊 HTML 回資源總覽