Home Assistant Skill is for readers who already run Home Assistant and want an agent to inspect states and capabilities. Start by reading one sensor and interpreting its response. Installing this skill neither installs Home Assistant nor signs the agent into your home.
Choose the connection first
| Situation | Starting point |
|---|---|
| Native Home Assistant MCP is already connected and its tools cover the query | Use those existing tools after checking their exposed scope |
| You need an exact entity, installed version or action fields | Use this skill's REST read helper |
| You need device/area mappings, automation definitions or Energy statistics | Continue with the repository's optional WebSocket workflows |
Do not add another bridge merely to try the skill. MCP exposure and direct API credentials have different scopes: Assist's exposed-entity list does not restrict a separate REST token. Current HA MCP configuration can expose all LLM APIs and require an administrator; it should not automatically be described as a narrowly scoped connection.
Install for Claude Code
Run these commands in a terminal, not in the chat box. Check that the destination does not already exist. Preserve and review local changes in an existing installation rather than overwriting it. This guide uses upstream 2.2.0 at the following commit so the instructions can be compared with the same files:
git clone https://github.com/anotb/homeassistant-skill.git ~/.claude/skills/homeassistant-skill
git -C ~/.claude/skills/homeassistant-skill checkout 3b5f34a90b927b4ea27a2c3a944c1d69f6e6a923
Open a fresh Claude Code session and confirm it recognizes homeassistant-skill. That directory is specific to Claude Code; follow your client's instructions for other agents. A same-name ClawHub entry exists, but registry versions can differ from GitHub. Check that the installed files contain the helper used here.
The first REST exercise needs Python 3.10+ and no extra Python packages. On Windows, use your working Python 3 command, typically python, and your actual installation path. OpenClaw separately checks curl, jq, HA_URL and HA_TOKEN. Being able to run the Python helper alone does not satisfy those readiness gates.
Prepare an origin, a token and one entity
In your own HA interface, select a temperature or connectivity sensor you are allowed to read and note its exact entity_id. sensor.kitchen_temperature below is a placeholder, not an entity guaranteed to exist. Do not infer IDs from friendly names.
Provide HA_URL and HA_TOKEN through private environment settings in the local process running the agent or script. HA_URL is a trusted base origin such as https://ha.example.com:8123, without /api, /api/mcp or a login-page path. Replace that example. Use verified HTTPS remotely; local HTTP does not encrypt the token. Do not expose a private instance to the internet for this exercise.
Use an existing authorized access token, not a browser password. A signed-in browser does not provision the CLI environment. If you have no token, use your own HA profile → Security → Long-lived access tokens to create and securely save one. This establishes persistent access, so confirm the account and purpose first. Keep tokens out of chat, command arguments and repositories. The agent must inherit the same environment; setting variables in a different terminal tab is insufficient.
One way to provide an existing token in a Bash terminal is below. Replace the origin first; the second command privately prompts for the token without echoing it. Do not use shell tracing. Start Claude Code from that same terminal afterward, or run the helper directly there. These are not PowerShell commands.
export HA_URL='https://ha.example.com:8123'
read -r -s -p 'Existing HA token: ' HA_TOKEN
export HA_TOKEN
The token retains its HA account's authority. The reader's local command allowlist does not turn it into a server-enforced read-only credential.
First task: read one sensor
From the local skill directory, check connectivity before reading the selected state:
cd ~/.claude/skills/homeassistant-skill
python3 scripts/ha_read.py get /api/
python3 scripts/ha_read.py profile
python3 scripts/ha_read.py get /api/states/sensor.kitchen_temperature
Replace the entity in the third command. Execute in order and stop on an error; a 401 is not evidence that a device is offline. profile reports the installed version, units, components and action names while omitting some household details from full configuration. The entity request returns a state object. Raw output can still contain private attributes, so keep it local.
In a Claude Code session with the skill loaded and the same environment, you can use this designed exercise prompt. It is not a report of a device test performed by this site:
Use homeassistant-skill to read only sensor.kitchen_temperature.
Check the existing connection and installed version, then use the read-only REST helper.
Report the entity ID, raw state, unit and update time; identify missing fields.
Preserve unknown and unavailable states and explain the distinction.
Do not control devices, run automations, change configuration or create credentials.
Never output the token.
Check the result
Compare the report with the selected entity in HA: the ID should match, the unit should come from its attributes, and the timestamp should be plausible. State values are generally strings. Interpret a value as a temperature or power reading only when its contents and unit support that interpretation. unknown means the value is unknown; unavailable means it is currently unavailable. Neither means zero or off. HTTP 200 establishes that the query returned, not that the sensor reading is fresh.
The first task is complete when you can say what this one entity reports and what remains uncertain. It does not require a whole-home scan or a repair. For a separately chosen availability overview, python3 scripts/ha_read.py health reads all states and lists unknown/unavailable entities. That is broader than this exercise.
Troubleshoot the specific failure
| Symptom | Next check |
|---|---|
| Missing HA_URL/HA_TOKEN | Set them in the process that actually runs the task; do not print secrets to diagnose inheritance |
| 401 | Check token validity and completeness locally; a browser address-bar visit does not add a Bearer header |
| 403 | The account lacks permission; stop rather than upgrading its role automatically |
| 404 | Check the base origin and exact entity ID before blaming hardware |
| Redirect refused or HTML response | Confirm the final trusted origin and proxy/login routing; keep TLS verification enabled |
| Timeout or connection failure | Check reachability and certificates from the agent's machine; the helper does not automatically retry |
| Requested action is not exposed | Check the actual installation and integration schema; unsupported is not an empty successful result |
Older community questions illustrate the distinction between browser login and authenticated API requests. They are not evidence of a newly confirmed defect in this skill release.
Continue beyond the first read
python3 scripts/ha_read.py action-schema light.turn_on reads the action definition without switching a light on. A discoverable schema is not permission to execute it. For registries and automation definitions, follow the repository's modern-workflows guide and install its optional WebSocket dependency locally. None of that is required for the REST exercise.
Locks, alarms, garage doors and scripts or scenes with indirect effects need clear targets and authorization. Do not POST to /api/states as a substitute for controlling hardware. After an authorized service call, verify the target state rather than treating request success as physical completion.
The skill is MIT-licensed. Agent/model usage and remote-access services may have separate costs, and household data processed by an agent follows that service's policies. This guide reviews the 2.2.0 instructions and helper interface; it has not connected to a home or verified physical device control. The first read is an exercise for checking your own environment.