nddqnddq/home-assistant-toolkit/skills/home-assistant-core/SKILL.md

home-assistant-core

Skill0 starsChanged 8 months agoMITView on GitHub

This skill provides knowledge for interacting with Home Assistant through three API layers: MCP, WebSocket, and REST. Activate this skill when the user mentions Home Assistant, HA, smart home devices, entities, automations, dashboards, HACS, or any HA-related topics. Home Assistant exposes three complementary APIs. Choosing the right one matters — some operations are only available on specific APIs. The HA MCP server provides native Claude integration for: - Reading entity states - Calling services (turn on/off, set position, etc.) -…

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Use MCP tools like mcp__home-assistant__HassTurnOn, mcp__home-assistant__HassLightSet, etc.
line 20
Distinctive:
Use the unified WebSocket client:
line 26
Very specific:
Use MCP: mcp__home-assistant__GetLiveContext or the specific entity MCP tool.
line 64
Very specific:
Use MCP service tools: HassTurnOn, HassTurnOff, HassLightSet, HassSetPosition, etc.
line 67
Very specific:
Use the config flow REST API — see references/config-flows.md.
line 80

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Home Assistant Core Interaction

This skill provides knowledge for interacting with Home Assistant through three API layers: MCP, WebSocket, and REST.

Auto-trigger

Activate this skill when the user mentions Home Assistant, HA, smart home devices, entities, automations, dashboards, HACS, or any HA-related topics.

Three API Layers

Home Assistant exposes three complementary APIs. Choosing the right one matters — some operations are only available on specific APIs.

1. MCP (Model Context Protocol) — Preferred for Entity/Service Operations

The HA MCP server provides native Claude integration for:

Reading entity states
Calling services (turn on/off, set position, etc.)
Getting live context

Use MCP tools like mcp__home-assistant__HassTurnOn, mcp__home-assistant__HassLightSet, etc.

2. WebSocket — Required for Registry/Config Operations

Dashboard config, entity registry, HACS, and Lovelace resources are WebSocket-only. There are no REST endpoints for these.

Use the unified WebSocket client:

source "<plugin_dir>/scripts/read_config.sh"
python3 "<plugin_dir>/scripts/ha_ws.py" --url "$HA_URL" --token "$HA_TOKEN" --operation <op> [--args '<json>']

3. REST API — For Automations and Config Flows

source "<plugin_dir>/scripts/read_config.sh"
curl -s --max-time 10 -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/<endpoint>"

API Routing Matrix

Operation	API	Reason
Entity states	MCP (preferred) or REST	HA MCP handles natively
Service calls (on/off/set)	MCP (preferred) or REST	HA MCP handles natively
Dashboard config read/write	WebSocket ONLY	No REST endpoint exists
Entity registry (hide/rename)	WebSocket ONLY	Not in REST API
HACS operations	WebSocket ONLY	HACS has no REST API
Lovelace resources	WebSocket ONLY	Frontend resource management
Automation config	REST	`/api/config/automation/config/<id>`
Config flows (helpers, templates)	REST	`/api/config/config_entries/flow` multi-step

Available Commands

/ha-setup — Configure connection (URL, token, MCP, WebSocket)
/ha-status — Check all three API connections
/ha-dashboard — Read/write/backup dashboard config (WebSocket)
/ha-entities — List/hide/show/rename entities (WebSocket)
/ha-automation — List/get/update automations (REST)
/ha-hacs — List/info/install HACS packages (WebSocket)

Common Workflows

Check an entity's state

Use MCP: mcp__home-assistant__GetLiveContext or the specific entity MCP tool.

Control a device

Use MCP service tools: HassTurnOn, HassTurnOff, HassLightSet, HassSetPosition, etc.

Modify dashboard

/ha-dashboard backup — always backup first
/ha-dashboard read — get current config
Modify the JSON
/ha-dashboard write — push new config

Hide raw entities after creating template wrappers

/ha-entities hide cover.raw_entity_id
/ha-entities rename cover.managed_entity_id "Friendly Name"

Create template entities (e.g., managed shade covers)

Use the config flow REST API — see references/config-flows.md.

Reference Files

references/api-routing.md — Full decision matrix with examples
references/websocket-api.md — WebSocket connection, auth, all commands
references/rest-api.md — REST endpoints reference
references/config-flows.md — Multi-step config flow patterns
references/troubleshooting.md — Common issues and fixes

Download now (ZIP)

In this repositoryOne other file it gives its agents.
- dashboard-designSkill

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free