Teach your AI agent how to work with Home Assistant

What is a skill, and why install one?

Think of an AI agent such as Claude, Codex, Gemini, OpenClaw, or Hermes as a capable new colleague. It can discuss many home systems, but it cannot infer your entity names, area structure, existing Blueprints, or Zigbee topology. A skill is a handover document for the agent: Markdown instructions explaining when and how to perform a particular kind of work.

• Install a community skill: Existing projects cover Home Assistant administration, ESPHome firmware, dashboard design, Blueprint imports, and custom integration development.
• Write your own: Package a household-specific workflow, such as a laundry reminder or weekly energy report. See the SKILL.md specification for a starting point.

A skill is different from an Assist voice assistant, a Home Assistant integration, or a Blueprint. You install it in the AI agent’s environment, not in Home Assistant. Installation alone does not modify Home Assistant, although the skill may direct an authorized agent to do so.

Install a skill in 3 minutes

Anthropic publishes the SKILL.md format in anthropics/skills. SKILL.md-based skills are used with Claude Code, Codex, Gemini CLI, Cursor, OpenCode, OpenClaw, Hermes, and other agent harnesses, but support and installation methods differ. Check the current documentation for your harness, then follow this general process:

1. Open the Skills or Plugins interface

   Depending on the harness, this may be a settings panel, a Skills screen, or a local directory such as ~/.codex/skills/.

2. Enter the package location

   Package syntax is not standardized. These examples show forms that a harness may support; confirm the required syntax in its documentation:

   # GitHub repository (most common)
   git:github.com/komal-SkyNET/claude-skill-homeassistant
   
   # Pin a version (tag or commit; recommended in production)
   git:github.com/anthropics/skills@v1.0.0
   
   # npm package
   npm:@scope/some-skill
   
   # Local path (your own skill or a subdirectory cloned from a monorepo)
   ~/skills/my-ha-skill

3. Start a new session and verify the skill

   Many harnesses load skills when a session starts. Open a new session, ask which skills are loaded, and confirm that the one you installed appears.

4. Review the skill before using it

   Read SKILL.md in the repository yourself. You can also ask the agent to summarize it without running commands, then identify any requested tools, network access, or Home Assistant changes. This is the first safety rule.

10 selected skills for Home Assistant

These practical options come from Home Assistant-specific repositories and broader collections, ordered from the closest fit for Home Assistant beginners. Review each repository, license, dependency, and permission request before installing it.

6 popular collections and catalogs

Start with these repositories when you want to browse individual skills or evaluate a larger collection. Review the contents before installing an entire collection.

git:github.com/anthropics/skills

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

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

git:github.com/kepano/obsidian-skills

git:github.com/mattpocock/skills

# Use as a catalog; installing the entire collection is not recommended
https://github.com/hesreallyhim/awesome-claude-code

For reference, other narrowly focused or less active Home Assistant projects include nolte/claude-home-assistant (Lovelace, Blueprint, ESPHome, and add-on development), dallanwagz/untether (reverse-engineering cloud-dependent Bluetooth Low Energy devices to create local Home Assistant integrations), and smalltv-ultra-skill (GeekMagic SmallTV Ultra firmware development). Their star counts are low, so consider them when you have a specific matching use case and review them carefully.

Compatibility

Claude Code, Codex, Gemini CLI, Cursor, OpenCode, OpenClaw, Hermes, and other agent harnesses can use SKILL.md-style instructions, but their discovery rules, metadata, tools, and installation methods are not identical. Plain Markdown instructions are usually the most portable. A skill may lose functionality when it:

• Depends on harness-specific features, such as hooks, plugin commands, or subagent delegation. The instructions may remain readable even when the automated behavior is unavailable.
• Requires a particular MCP server or SaaS account. A Home Assistant skill that expects ha-mcp-woow or the official MCP Server integration cannot use those tools until you configure the connection and permissions.
• Includes scripts/ that need an unavailable runtime. A script may require a particular Python package or Node version, especially when the agent runs inside a Home Assistant add-on container.

Safety rules

• Read before installing: Inspect SKILL.md and any referenced files or scripts yourself. If you ask an agent to summarize them, explicitly tell it not to execute anything. Identify every requested tool, command, network connection, secret, and configuration change.
• Back up before configuration changes: Skills such as claude-skill-homeassistant and aurora-smart-home may change automations, dashboards, or configuration.yaml. Create and verify a full manual backup under Settings → System → Backups first.
• Test on a separate Home Assistant instance: If your production system is complex, evaluate the skill in a clean test container before granting it access to your household system.
• Pin production versions: Use an @tag or @commit when supported. Review upstream changes before upgrading.
• Limit access to entities: For Assist, open Settings → Voice assistants → Expose and select only the areas and entities you need. Do not expose locks, alarms, or main power controls until you have reviewed the risks and safeguards. This setting does not restrict a coding agent or MCP server, so configure least-privilege access separately for every connection.
• Treat stars as popularity, not proof of safety: Review permissions and behavior even for popular collections, especially skills that include scripts/.

SKILL.md specification at a glance

The example below shows the basic structure of a skill. See anthropics/skills for the full specification.

washer-notify/
├── SKILL.md          ← Required
└── references/       ← Optional supporting files (load only when needed)
    └── ha-service-map.md

# SKILL.md
---
name: washer-notify
description: |
  Use this Skill when the user asks whether the washing machine has finished,
  whether it is time to collect the laundry, or how to automate a laundry
  reminder. Read sensor.washer_power through the Home Assistant API to
  determine whether the machine is running, idle, or finished.
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, ha_config_set_automation, notify_send]
---

# Laundry reminder Skill

When the user asks about the washing machine, first read the past 15 minutes of
history for sensor.washer_power. If power fell from >100W to <5W and remained
there for at least 3 minutes, report that the cycle is complete. If the machine
is still running, estimate the remaining time using the stated 45-minute
average and clearly label the result as an estimate. Respond in English.

If the user requests an automatic reminder, use ha_config_set_automation to
create an automation based on this logic:
- Trigger when sensor.washer_power remains below 5W for 3 minutes.
- Send a notification through notify.mobile_app_myphone.
Use entity_id references and current Home Assistant automation syntax. Show the
user a YAML summary and obtain approval before applying it. Respond in English.

Keep SKILL.md concise. Put supporting material in references/, scripts/, or assets/ so the agent loads it only when needed. For a Home Assistant skill, consider adding a service or action map under references/ for the agent to consult before making a call.

FAQ

Take this handbook with you

This handbook is a self-contained HTML file with embedded icons, so you can download and read it offline. Collection details will become outdated; check the online Resource Hub before making an important decision.

Download this handbook Back to the Resource Hub