ha-mcp-dev 7.5.0.dev556__tar.gz → 7.5.0.dev558__tar.gz

{ha_mcp_dev-7.5.0.dev556/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.5.0.dev558}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.5.0.dev556
+Version: 7.5.0.dev558
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-7.5.0.dev556 → ha_mcp_dev-7.5.0.dev558}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.5.0.dev556"
+version = "7.5.0.dev558"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{ha_mcp_dev-7.5.0.dev556 → ha_mcp_dev-7.5.0.dev558}/src/ha_mcp/resources/skills-vendor/.claude-plugin/marketplace.json

@@ -5,13 +5,13 @@
     "email": ""
   },
   "metadata": {
-    "description": "Agent skills for Home Assistant: best practices for automations, helpers, templates, and device control",
+    "description": "Agent skills for Home Assistant: best practices for automations, helpers, templates, device control, and dashboards",
     "version": "0.1.0"
   },
   "plugins": [
     {
       "name": "home-assistant-skills",
-      "description": "Best practices for Home Assistant automations, helpers, scripts, and device controls",
+      "description": "Best practices for Home Assistant automations, helpers, scripts, device controls, and dashboards",
       "source": "./"
     }
   ]

{ha_mcp_dev-7.5.0.dev556 → ha_mcp_dev-7.5.0.dev558}/src/ha_mcp/resources/skills-vendor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "home-assistant-skills",
-  "description": "Agent skills for Home Assistant: best practices for automations, helpers, templates, and device control.",
+  "description": "Agent skills for Home Assistant: best practices for automations, helpers, templates, device control, and dashboards.",
   "version": "0.1.0",
   "repository": "https://github.com/homeassistant-ai/skills",
   "license": "MIT"

ha_mcp_dev-7.5.0.dev558/src/ha_mcp/resources/skills-vendor/.github/pull_request_template.md

@@ -0,0 +1,8 @@
+## What does this PR do?
+
+<!-- Describe what your change does and why. -->
+
+## Checklist
+
+- [ ] Tested with real scenarios (if changing skill content)
+- [ ] `README.md` Skill Contents table updated (if reference files were added or removed)

{ha_mcp_dev-7.5.0.dev556 → ha_mcp_dev-7.5.0.dev558}/src/ha_mcp/resources/skills-vendor/AGENTS.md

@@ -11,6 +11,9 @@ This is a community-contributed collection of **Agent Skills** for Home Assistan
 - `skills/<skill-name>/SKILL.md` — each skill lives in its own folder with a `SKILL.md` file
 - `CONTRIBUTING.md` — skill authoring guidelines and submission workflow
 - `.claude-plugin/plugin.json` — Claude Code plugin metadata
+- `.claude-plugin/marketplace.json` — marketplace metadata for plugin discovery
+- `AGENTS.md` — symlink to `CLAUDE.md` (for agents that use `AGENTS.md` convention)
+- `.github/ISSUE_TEMPLATE/skill-rca.md` — "Report Bad Skill Advice" issue template
 
 ## Skill Format
 
@@ -26,7 +29,7 @@ description: >
 
 Constraints from CONTRIBUTING.md:
 - Max **500 lines** per SKILL.md
-- `metadata.version` must be `0` on new skills (CI assigns real version on merge; do not edit manually)
+- `metadata.version` must be `0` on new skills (do not edit manually)
 - Reference files must be **one level deep** only (e.g. `references/example.yaml`)
 - Use **forward slashes** in all file paths
 - Optional subdirectories: `references/` (additional docs), `scripts/` (utility scripts), `assets/` (static resources)
@@ -41,9 +44,12 @@ Constraints from CONTRIBUTING.md:
 
 ## Validation
 
-CI runs `skills-ref validate` on every PR and push to `main` that touches `skills/**`. To validate locally:
+CI runs two workflows on PRs and pushes to `main`:
+- **validate-skills** — runs `skills-ref validate` on every skill when `skills/**` changes
+- **validate-plugin** — validates `.claude-plugin/` metadata
+
+To validate locally:
 
 ```bash
-pip install skills-ref
-python -m skills_ref.cli validate skills/<skill-name>
+uvx skills-ref validate skills/<skill-name>
 ```

{ha_mcp_dev-7.5.0.dev556 → ha_mcp_dev-7.5.0.dev558}/src/ha_mcp/resources/skills-vendor/CLAUDE.md

@@ -11,6 +11,9 @@ This is a community-contributed collection of **Agent Skills** for Home Assistan
 - `skills/<skill-name>/SKILL.md` — each skill lives in its own folder with a `SKILL.md` file
 - `CONTRIBUTING.md` — skill authoring guidelines and submission workflow
 - `.claude-plugin/plugin.json` — Claude Code plugin metadata
+- `.claude-plugin/marketplace.json` — marketplace metadata for plugin discovery
+- `AGENTS.md` — symlink to `CLAUDE.md` (for agents that use `AGENTS.md` convention)
+- `.github/ISSUE_TEMPLATE/skill-rca.md` — "Report Bad Skill Advice" issue template
 
 ## Skill Format
 
@@ -26,7 +29,7 @@ description: >
 
 Constraints from CONTRIBUTING.md:
 - Max **500 lines** per SKILL.md
-- `metadata.version` must be `0` on new skills (CI assigns real version on merge; do not edit manually)
+- `metadata.version` must be `0` on new skills (do not edit manually)
 - Reference files must be **one level deep** only (e.g. `references/example.yaml`)
 - Use **forward slashes** in all file paths
 - Optional subdirectories: `references/` (additional docs), `scripts/` (utility scripts), `assets/` (static resources)
@@ -41,9 +44,12 @@ Constraints from CONTRIBUTING.md:
 
 ## Validation
 
-CI runs `skills-ref validate` on every PR and push to `main` that touches `skills/**`. To validate locally:
+CI runs two workflows on PRs and pushes to `main`:
+- **validate-skills** — runs `skills-ref validate` on every skill when `skills/**` changes
+- **validate-plugin** — validates `.claude-plugin/` metadata
+
+To validate locally:
 
 ```bash
-pip install skills-ref
-python -m skills_ref.cli validate skills/<skill-name>
+uvx skills-ref validate skills/<skill-name>
 ```

{ha_mcp_dev-7.5.0.dev556 → ha_mcp_dev-7.5.0.dev558}/src/ha_mcp/resources/skills-vendor/CONTRIBUTING.md

@@ -50,4 +50,5 @@ The template covers five sections: context, timeline, root cause, impact, and en
 2. Create a folder under `skills/` with your skill name.
 3. Write a `SKILL.md` following the format above.
 4. Test your skill with real scenarios.
-5. Submit a pull request describing what your skill teaches and what problems it solves.
+5. If you added or removed reference files, update the **Skill Contents** table in `README.md`.
+6. Submit a pull request describing what your skill teaches and what problems it solves.

{ha_mcp_dev-7.5.0.dev556 → ha_mcp_dev-7.5.0.dev558}/src/ha_mcp/resources/skills-vendor/README.md

@@ -9,7 +9,7 @@ This repository provides an Agent Skill for Home Assistant, following the open [
 
 ## Included Skill
 
-**[home-assistant-best-practices](skills/home-assistant-best-practices/):** Native HA constructs over templates, helper selection, automation modes, Zigbee button patterns, device control best practices, and safe refactoring.
+**[home-assistant-best-practices](skills/home-assistant-best-practices/):** Native HA constructs over templates, helper selection, automation modes, Zigbee button patterns, device control best practices, YAML-only integration management, dashboard configuration, and safe refactoring.
 
 ## Installation
 
@@ -34,13 +34,15 @@ Run each command separately inside Claude Code:
 /plugin install home-assistant-skills@homeassistant-ai-skills
 ```
 
-Restart Claude Code after installation for the skill to take effect.
+Run `/reload-plugins` or restart Claude Code for the skill to take effect.
 
 ### Claude Desktop / claude.ai
 
 1. Download or clone this repository
 2. Zip the skill folder: `cd skills && zip -r home-assistant-best-practices.zip home-assistant-best-practices/`
-3. **Settings → Capabilities → Skills → Upload skill** → select the `.zip` file
+3. Upload to:
+   - **Claude Desktop:** Customize (left sidebar) → Skills → + → Create skill
+   - **claude.ai:** [claude.ai/customize/skills](https://claude.ai/customize/skills) → Upload
 
 ## Skill Contents
 
@@ -52,8 +54,12 @@ The `home-assistant-best-practices` skill includes:
 | `references/safe-refactoring.md` | Safe workflow for renaming entities, replacing helpers, restructuring automations |
 | `references/automation-patterns.md` | Native conditions, triggers, waits, automation modes |
 | `references/helper-selection.md` | Built-in helpers vs template sensors (with decision matrix) |
-| `references/template-guidelines.md` | When templates are the right choice |
+| `references/template-guidelines.md` | When to use templates, when to avoid them, and sensor best practices |
+| `references/yaml-only-integrations.md` | YAML-only integration types, post-edit actions (reload vs restart) |
 | `references/device-control.md` | Service calls, entity_id vs device_id, Zigbee buttons |
+| `references/dashboard-guide.md` | Dashboard layout, view types, sections, custom cards, CSS styling |
+| `references/dashboard-cards.md` | Card type lookup and card-specific documentation |
+| `references/domain-docs.md` | Integration and domain documentation for service calls, entity attributes |
 | `references/examples.yaml` | Compound examples combining multiple best practices |
 
 ## Contributing

{ha_mcp_dev-7.5.0.dev556 → ha_mcp_dev-7.5.0.dev558}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/SKILL.md

@@ -18,10 +18,10 @@ description: >
   - Agent modifies entity IDs without checking consumers
   - Agent chooses wrong automation mode (e.g., single for motion lights)
   - Agent hard-codes values or picks raw sensor over derived helper
-  - Agent searches for HA config files on disk or generates YAML snippets
+  - Agent edits `.storage/` files, writes raw YAML, or generates YAML snippets
   - Agent tells user to edit configuration.yaml for UI-configured integrations
 metadata:
-  version: 2
+  version: 5
 ---
 
 # Home Assistant Best Practices
@@ -93,13 +93,21 @@ See `references/device-control.md#zigbee-buttonremote-patterns`.
 | `wait_template: "{{ is_state(...) }}"` | `wait_for_trigger` with state trigger | Event-driven, not polling; waits for *change* (see `references/safe-refactoring.md#trigger-restructuring` for semantic differences) | `references/automation-patterns.md#wait-actions` |
 | `device_id` in triggers | `entity_id` (or `device_ieee` for ZHA) | device_id breaks on re-add | `references/device-control.md#entity-id-vs-device-id` |
 | `mode: single` for motion lights | `mode: restart` | Re-triggers must reset the timer | `references/automation-patterns.md#automation-modes` |
+| `enabled: false` as a top-level key in `automations.yaml` | `automation.turn_off` (temporary) or entity registry disable (permanent) | Not a valid top-level key — rejected during schema validation; automation loads as `unavailable` | `references/automation-patterns.md#disabling-automations` |
 | Template sensor for sum/mean | `min_max` helper | Declarative, handles unavailable states | `references/helper-selection.md#numeric-aggregation` |
 | Template binary sensor with threshold | `threshold` helper | Built-in hysteresis support | `references/helper-selection.md#threshold` |
-| Renaming entity IDs without impact analysis | Follow `references/safe-refactoring.md` workflow | Renames break dashboards, scripts, and scenes silently | `references/safe-refactoring.md#entity-renames` |
+| Renaming entity IDs without impact analysis | Follow `references/safe-refactoring.md` workflow | Renames break dashboards, scripts, scenes, Config-Entry data, and storage dashboards silently | `references/safe-refactoring.md#entity-renames` |
+| Renaming members of Config-Entry-based groups (UI groups) without updating membership | Update group membership via Options Flow after the registry rename | The entity registry rename does not update `options.entities` in the Config Entry — group silently breaks | `references/safe-refactoring.md#config-entry-groups` |
+| Renaming entities used by Config-Entry integrations (Better/Generic Thermostat, Min/Max, Threshold) without patching Config-Entry data | Scan and patch `core.config_entries` `data`+`options` fields | These integrations store entity_ids in Config Entry — not updated by entity registry renames | `references/safe-refactoring.md#config-entry-data--blind-spots-for-entity-registry-renames` |
 | `template:` sensor/binary sensor in YAML | Template Helper (UI or config flow API) | Requires file edit and config reload; harder to manage | `references/template-guidelines.md` |
-| Searching for or reading HA config files on disk | Use the HA REST/WebSocket API to manage config programmatically | HA is a remote system accessed via APIs; config files are not on the local filesystem | — |
+| Editing `.storage/` files or other HA internal state directly | Use the HA REST/WebSocket API to manage state and config entries | `.storage/` files are HA's internal state database; direct edits bypass validation, risk corruption, and can be silently overwritten by HA | — |
+| Writing raw YAML to `configuration.yaml` by hand for YAML-only integrations | Use managed YAML config editing with backup and validation | Unmanaged writes risk syntax errors, have no backup, and skip `check_config` — managed editing provides all three | `references/yaml-only-integrations.md` |
 | Generating YAML snippets for automations/scripts/scenes | Use the HA config API to create automations/scripts programmatically | API calls validate config, avoid syntax errors, and don't require manual file edits or restarts | `references/automation-patterns.md`, `references/examples.yaml` |
 | Telling user to edit `configuration.yaml` for integrations | Direct user to Settings > Devices & Services in the HA UI | Most integrations are UI-configured; YAML integration config is rare and integration-specific | — |
+| Referring to HA "add-ons" | Use the term "Apps" | HA renamed add-ons to Apps in 2026.2 — "Apps are standalone applications that run alongside Home Assistant" | — |
+| `vacuum.send_command` with vendor room IDs | `vacuum.clean_area` with HA `area_id` (if segments are mapped) | Uses native HA areas, works across integrations — but requires segment-to-area mapping in entity settings first | `references/device-control.md#vacuum-control` |
+| Using `color_temp` (mireds) in light service calls | Use `color_temp_kelvin` | The `color_temp` parameter was removed in 2026.3; only Kelvin is supported | `references/device-control.md#lights` |
+| Person/Device Tracker `entered_home`/`left_home` device triggers or `is_home`/`is_not_home` conditions | `state` trigger `to: home` / `to: not_home`, or `state` condition | These were removed in 2026.5 — state triggers and conditions are the correct replacements | `references/automation-patterns.md#presence-and-person-triggers-and-conditions-removed-in-20265` |
 
 ---
 
@@ -109,10 +117,11 @@ Read these when you need detailed information:
 
 | File | When to read | Key sections |
 |------|--------------|--------------|
-| `references/safe-refactoring.md` | Renaming entities, replacing helpers, restructuring automations, or any modification to existing config | `#universal-workflow`, `#entity-renames`, `#helper-replacements`, `#trigger-restructuring` |
-| `references/automation-patterns.md` | Writing triggers, conditions, waits, or choosing automation modes | `#native-conditions`, `#trigger-types`, `#wait-actions`, `#automation-modes`, `#ifthen-vs-choose`, `#trigger-ids` |
-| `references/helper-selection.md` | Deciding whether to use a built-in helper vs template sensor | `#numeric-aggregation`, `#rate-and-change`, `#time-based-tracking`, `#counting-and-timing`, `#scheduling`, `#entity-grouping`, `#decision-matrix` |
+| `references/safe-refactoring.md` | Renaming entities, replacing helpers, restructuring automations, or any modification to existing config | `#universal-workflow`, `#entity-renames`, `#helper-replacements`, `#trigger-restructuring`, `#config-entry-data--blind-spots-for-entity-registry-renames`, `#storage-mode-dashboards-storagelovelace` |
+| `references/automation-patterns.md` | Writing triggers, conditions, waits, or choosing automation modes; disabling automations | `#native-conditions`, `#trigger-types`, `#wait-actions`, `#automation-modes`, `#continue-on-error`, `#repeat-actions`, `#ifthen-vs-choose`, `#trigger-ids`, `#disabling-automations` |
+| `references/helper-selection.md` | Deciding whether to use a built-in helper vs template sensor | `#menu-based-helpers`, `#numeric-aggregation`, `#rate-and-change`, `#time-based-tracking`, `#counting-and-timing`, `#scheduling`, `#entity-grouping`, `#data-smoothing`, `#random-values`, `#climate-control`, `#domain-conversion`, `#template-helpers`, `#decision-matrix` |
 | `references/template-guidelines.md` | Confirming templates ARE appropriate for a use case | `#when-templates-are-appropriate`, `#when-to-avoid-templates`, `#template-sensor-best-practices`, `#common-patterns`, `#error-handling` |
+| `references/yaml-only-integrations.md` | Creating or editing YAML-only integrations that have no config flow (e.g. `command_line`, platform-based `mqtt`, `rest`) | `#yaml-only-integration-types`, `#post-edit-actions` |
 | `references/device-control.md` | Writing service calls, Zigbee button automations, or using target: | `#entity-id-vs-device-id`, `#service-calls-best-practices`, `#zigbee-buttonremote-patterns`, `#domain-specific-patterns` |
 | `references/dashboard-guide.md` | Designing or modifying Lovelace dashboards — layout, view types, sections, custom cards, CSS styling, HACS | `#dashboard-structure`, `#view-types`, `#built-in-cards`, `#features`, `#custom-cards`, `#css-styling`, `#common-pitfalls` |
 | `references/dashboard-cards.md` | Looking up available card types or fetching card-specific documentation | — |

{ha_mcp_dev-7.5.0.dev556 → ha_mcp_dev-7.5.0.dev558}/src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/evals/evals.json

@@ -48,6 +48,54 @@
           "description": "Response does NOT recommend a template sensor (YAML or UI helper) as the primary solution"
         }
       ]
+    },
+    {
+      "id": 4,
+      "eval_name": "arrive-home-automation",
+      "prompt": "create an automation that turns on the lights when I get home",
+      "expected_output": "Uses state trigger with to: home on a person entity. Does NOT use the removed entered_home device trigger type.",
+      "assertions": [
+        {
+          "id": "uses_state_trigger",
+          "description": "Response uses a state trigger (trigger: state) on a person or device_tracker entity, to: home"
+        },
+        {
+          "id": "no_entered_home_trigger",
+          "description": "Response does NOT use the entered_home device trigger type (removed in 2026.5)"
+        }
+      ]
+    },
+    {
+      "id": 5,
+      "eval_name": "timer-finished-automation",
+      "prompt": "make an automation that announces on my speaker when my kitchen timer finishes",
+      "expected_output": "Uses timer.finished event trigger. Does NOT use a polling template or state trigger workaround.",
+      "assertions": [
+        {
+          "id": "uses_timer_finished_event",
+          "description": "Response uses event trigger with event_type: timer.finished (or purpose-specific timer trigger)"
+        },
+        {
+          "id": "no_polling_workaround",
+          "description": "Response does NOT suggest polling or a wait_template workaround for detecting timer completion"
+        }
+      ]
+    },
+    {
+      "id": 6,
+      "eval_name": "assist-shortcut-card",
+      "prompt": "add a card to my dashboard to quickly launch Assist",
+      "expected_output": "Recommends the shortcut card (new in 2026.5) for launching Assist from a dashboard.",
+      "assertions": [
+        {
+          "id": "recommends_shortcut_card",
+          "description": "Response recommends the shortcut card type for launching Assist"
+        },
+        {
+          "id": "not_just_button_card",
+          "description": "Response does not exclusively recommend a button card with tap_action when shortcut is more appropriate"
+        }
+      ]
     }
   ]
 }