القائمة
Use when planning multi-call ha-mcp workflows or when token usage matters. Examples: "query 50 entities", "batch-update labels", "reduce response size", "avoid unnecessary API calls".
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Use when editing an existing automation, script, scene, or dashboard with `action: patch`. Examples: "add a trigger", "replace a dashboard card", "remove a condition", "change automation mode", "add delay to trigger".
Use when a ha-mcp call returns an unexpected result, error, or behaves differently than expected. Examples: "scene not appearing after create", "helper entity_id is wrong", "patch failing with missing config", "automation ID mismatch".
Use when choosing which ha-mcp tool or action to call. Examples: "How do I list entities?", "create a helper", "turn on a light", "find devices in kitchen", "which action should I use?".
Use when working with Home Assistant via the ha-mcp MCP server. Examples: "create automation", "toggle light", "list entities in living room", "patch dashboard", "create helper", "query sensors".
| name | ha-mcp-efficiency |
| description | Use when planning multi-call ha-mcp workflows or when token usage matters. Examples: "query 50 entities", "batch-update labels", "reduce response size", "avoid unnecessary API calls". |
format=natural is the default. Never override it unless the caller will programmatically parse JSON.
format=json for most responses.format=json only when piping output to another tool or doing machine parsing.Never loop get_state N times. One query_entities call replaces all of them.
| Scenario | Mode | Key params |
|---|---|---|
| Browse entities by domain, area, or state | current | domain, area_id, state_filter |
| Find unavailable / unknown / stale entities | health | categories, include_disabled |
| Who's home? Device trackers / persons | presence | (none extra) |
| Sensor readings over a time range | history | entity_ids, start_time, end_time |
| Min/max/mean aggregated stats | statistics | statistic_ids, period |
| What entity domains exist in this HA instance? | domains | (none) |
For partial changes to automations, scripts, scenes, or dashboards:
| Change type | Use | Why |
|---|---|---|
| 1-3 field changes | patch | Sends only ops, not full config |
| Adding / removing array elements | patch | Semantic ops handle position automatically |
| Full config rewrite / major restructure | update | Simpler when structure changes significantly |
| Operation | Populates Config? | Token cost | Use for |
|---|---|---|---|
list | No | Low | Discovery, count, quick scan |
get | Yes | Medium | Before update/patch, full details |
get_details (helper) | Yes | Medium | Full helper config |
Rule: Never patch after a list. Always get first.
After any mutation (create, update, delete, patch, call_service):
State changes: entity: old → new or a timeout warning.get_state manually after a mutation — that duplicates server-side polling and adds latency.When updating labels or aliases, use modes to avoid sending the full current list:
| mode | Behavior | When to use |
|---|---|---|
add | Appends new items, deduplicates (default) | Adding one label without touching others |
remove | Subtracts listed items | Removing a specific label |
replace | Full replacement | Setting the exact final list |
label_mode / alias_mode apply only to update actions on manage_entity, manage_device, manage_area, manage_floor.
If HA_CACHE_ENABLED=true, registry reads (get_registry, manage_*:list) are cached server-side with per-type TTLs (10-60 min). Cache is automatically invalidated after create/update/delete mutations on the same registry type. Do not add client-side caching — the server already prevents thundering-herd via singleflight.
CLAUDE.md sections "Post-Mutation Async Confirmation (Smart Wait)", "Configuration Priority", "Consolidated Tools".