ha-mcp-dev 8.3.0.dev2453__tar.gz → 8.3.0.dev2454__tar.gz

{ha_mcp_dev-8.3.0.dev2453/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.3.0.dev2454}/PKG-INFO

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

{ha_mcp_dev-8.3.0.dev2453 → ha_mcp_dev-8.3.0.dev2454}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.3.0.dev2453"
+version = "8.3.0.dev2454"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

{ha_mcp_dev-8.3.0.dev2453 → ha_mcp_dev-8.3.0.dev2454}/src/ha_mcp/resources/skills-vendor/.claude-plugin/marketplace.json

@@ -5,13 +5,13 @@
     "email": "homeassistant-mcp@qc-h.net"
   },
   "metadata": {
-    "description": "Agent skills for Home Assistant: best practices for automations, helpers, templates, device control, and dashboards",
-    "version": "0.18.0"
+    "description": "Agent skills for Home Assistant: best practices for automations, helpers, templates, scenes, blueprints, device control, dashboards, AppDaemon, and backups",
+    "version": "0.26.0"
   },
   "plugins": [
     {
       "name": "home-assistant-skills",
-      "description": "Best practices for Home Assistant automations, helpers, scripts, device controls, and dashboards",
+      "description": "Best practices for Home Assistant automations, helpers, scripts, scenes, blueprints, device control, dashboards, AppDaemon apps, and backups",
       "source": "./"
     }
   ]

{ha_mcp_dev-8.3.0.dev2453 → ha_mcp_dev-8.3.0.dev2454}/src/ha_mcp/resources/skills-vendor/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "home-assistant-skills",
-  "description": "Agent skills for Home Assistant: best practices for automations, helpers, templates, device control, and dashboards.",
-  "version": "0.18.0",
+  "description": "Agent skills for Home Assistant: best practices for automations, helpers, templates, scenes, blueprints, device control, dashboards, AppDaemon, and backups.",
+  "version": "0.26.0",
   "repository": "https://github.com/homeassistant-ai/skills",
   "license": "MIT"
 }

ha_mcp_dev-8.3.0.dev2454/src/ha_mcp/resources/skills-vendor/.github/ISSUE_TEMPLATE/skill-rca.md

@@ -0,0 +1,112 @@
+---
+name: Report Bad Skill Advice
+about: A skill misled your agent. Have your agent fill out this report so we can fix the skill.
+title: "[RCA] "
+labels: rca
+---
+
+<!--
+HOW TO FILE
+
+For the user: give your agent this template and ask it to fill the report in —
+it holds the full context of what went wrong. The raw file is at
+https://raw.githubusercontent.com/homeassistant-ai/skills/main/.github/ISSUE_TEMPLATE/skill-rca.md
+
+For the agent: write the report in Markdown, then either file it yourself:
+
+  gh issue create --repo homeassistant-ai/skills \
+    --title "[RCA] <skill>: <one-line failure>" \
+    --body-file report.md --label rca
+
+If --label is rejected (it needs triage access), either file through the
+"New issue" web form — the template applies the label for you — or drop the
+flag; the [RCA] title prefix is enough for triage. Without GitHub access at
+all, hand the Markdown back to the user to paste into that form. Paste
+Markdown, not rendered HTML.
+
+INSTRUCTIONS FOR THE AGENT
+
+A skill in this repository misled you, and your user saw the result.
+
+BEFORE FILING:
+- Search existing issues for the same skill and failure. If a matching
+  issue exists, react with thumbs-up or comment with additional context.
+  Open a new issue only when the failure is unreported.
+- Did the skill actually load? If it never triggered, this is a triggering
+  failure, not a content failure: write "Skill did not trigger" in 3a, keep
+  the user's request verbatim apart from redactions (it is the prompt that
+  failed to trigger the skill), and skip 3b and 3c.
+- Did you follow the skill's guidance? If you skipped guidance that would
+  have prevented the failure, that is not a skill bug. Report only what the
+  skill got wrong or left out.
+- Redact before filing: tokens, URLs, IP addresses, email addresses, names,
+  and anything from the user's setup the public need not see — replace each
+  with [REDACTED] and keep the wording otherwise. Show the user the finished
+  report and get an explicit go-ahead before you file it.
+
+Fill out each section below. Quote the skill content that misled you,
+list affected entities and configs, and mark the first failure point.
+
+Write "N/A" for any section that is irrelevant.
+-->
+
+## 1. Context
+
+- **Skill name:**  <!-- e.g. home-assistant-best-practices -->
+- **Skill version:**  <!-- metadata.version in SKILL.md frontmatter; plugin version 0.N.0 is skill version N. If main is ahead, say so — a stale install may already be fixed -->
+- **What the user originally asked you to do:**  <!-- verbatim apart from redactions -->
+
+## 2. Timeline
+
+List each action you took. For each, record what you did, what resulted, and its status (e.g., Success, Failure).
+
+Mark the first failing step with **[GAP]** in the `Status` column.
+
+| Step | Action | Result | Status |
+|------|--------|--------|-----|
+| 1 | | | |
+| 2 | | | |
+| 3 | | | |
+
+<!-- Add or remove rows as needed. -->
+
+## 3. Root Cause
+
+### 3a. What skill instruction did you follow?
+
+<!--
+Quote the SKILL.md passage or reference file section that guided
+your actions. Include the file name and section heading.
+If the skill offered no guidance for this scenario, write:
+"No guidance found in the skill for this scenario."
+If the skill never loaded, write "Skill did not trigger" and skip 3b and 3c.
+-->
+
+### 3b. What did that instruction cause you to do (or not do)?
+
+<!--
+Describe the action or omission that caused the failure,
+and tie it to the skill content you quoted in 3a.
+-->
+
+### 3c. What should the skill have told you instead?
+
+<!--
+Describe the guidance the skill should have included
+to prevent this failure.
+-->
+
+## 4. Impact
+
+<!--
+How bad was it: what the user saw beyond the timeline (silent failures,
+lost data, how long it went unnoticed) and every affected component:
+dashboards, automations, configurations, entities, integrations, etc.
+If the failure affected only the immediate task, say so.
+-->
+
+## 5. Environment
+
+- **Home Assistant version and install type:**  <!-- e.g. 2026.8.1 on Home Assistant OS; or Container, Core, Supervised -->
+- **Agent platform, model, and HA access:**  <!-- e.g. Claude Code with Opus 5 via an MCP server (name and version); Cursor with the REST API; Codex, files only -->
+- **Integration / device type involved:**  <!-- e.g. ZHA, Z2M, IKEA FYRTUR, or N/A -->

{ha_mcp_dev-8.3.0.dev2453 → ha_mcp_dev-8.3.0.dev2454}/src/ha_mcp/resources/skills-vendor/.github/pull_request_template.md

@@ -6,3 +6,4 @@
 
 - [ ] Tested with real scenarios (if changing skill content)
 - [ ] `README.md` Skill Contents table updated (if reference files were added or removed)
+- [ ] Row descriptions and the **Included Skill** summary still match what the files cover (if a reference file's scope changed)

ha_mcp_dev-8.3.0.dev2454/src/ha_mcp/resources/skills-vendor/AGENTS.md

@@ -0,0 +1,99 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repo Layout
+
+Eval cases live in a top-level `evals/<case>/case.yaml`, **not** under `skills/`. `claude
+plugin eval` rejects any eval directory whose first segment names a loaded component directory
+(`commands`, `skills`, `agents`, `hooks`, `themes`, `output-styles`, `monitors`, `workflows`,
+`bin`) — and rejects it *softly*: it warns, falls back to the default `evals/`, and finds
+nothing, so cases in the wrong place silently never run. `evals/` at the plugin root is the
+default and needs no `experimental.evals` key.
+
+**SKILL.md is in context on every trigger; `references/` load only when read.** That is why
+SKILL.md body size is capped and why domain-niche content belongs in a reference file behind
+a single routing row, not in the always-loaded table.
+
+## Skill Format
+
+Every skill is a `SKILL.md` with `name`/`description` frontmatter. Full authoring constraints: `CONTRIBUTING.md`. The one CI cannot catch:
+- `metadata.version` must be `"0"` on new skills — do not edit manually; CI assigns the real version on merge and syncs it into `.claude-plugin/plugin.json` (`.version`) and `.claude-plugin/marketplace.json` (`.metadata.version`) — three files, one source of truth
+- `description` is capped at 1024 chars and runs close to it — measure the parsed length before adding trigger/symptom bullets: `uvx --from skills-ref agentskills read-properties skills/<skill-name> | jq '.description | length'`
+
+## Skill Authoring Principles
+
+The wording of these content-quality principles is mirrored in `CONTRIBUTING.md`
+(contributors); each file also carries guidance the other omits. When you change a shared
+principle, change both — they have drifted before.
+
+- **Context window conservation** — keep what is HA-specific, cut general programming advice; the test is the content itself, not whether a given model already knows it (skills run on frontier and small local models alike)
+- **Conciseness** — provide patterns and quick-reference tables, not tutorials
+- **Consistent terminology** — one term per concept throughout a skill; contrasting code blocks are `# WRONG — why` / `# RIGHT — why` (emoji only in table status columns). A renamed HA term uses the new name and cites the old one with its version ("named Developer Tools before 2026.8") — never a bare swap, since readers on older releases still see the old label
+- **Symptom-based triggering** — the `description` frontmatter should describe observable agent behaviors that signal the skill is needed
+- **No tool names** — reference HA REST APIs and concepts, never specific MCP tool names (e.g. `ha_rename_entity`); tool names vary by agent setup
+
+## Validation
+
+To validate locally:
+
+```bash
+uvx --from skills-ref agentskills validate skills/<skill-name>
+```
+
+Four more checks gate a merge. `agnix` and `lychee` run as release binaries pinned in
+`.github/workflows/` — install those versions (lychee's release tag is `lychee-vX.Y.Z`, not
+`vX.Y.Z`); `claude plugin validate` ships with the Claude Code CLI; the eval-case checker is
+in-repo and needs only PyYAML:
+
+```bash
+agnix skills/ --target claude-code                              # spec conformance
+lychee --offline --include-fragments --no-progress './**/*.md'  # local links + #anchors
+claude plugin validate .                                        # plugin manifests
+python scripts/check_eval_cases.py                              # evals/<case>/case.yaml
+```
+
+agnix catches what skills-ref's unenforced `metadata: dict[str, str]` annotation lets pass —
+e.g. an unquoted integer version, which strict clients refuse. In CI (`links.yml`) lychee runs
+that same local check on PRs touching `.md`/`.yaml`, plus external URLs weekly, dot-directories
+excluded; it cannot see references written as inline code. `check_eval_cases.py` validates the
+shape of eval cases against the `claude plugin eval` 1.1 schema — that command is gated behind
+early access, so its own parser never runs here; the schema is transcribed by hand and needs
+re-deriving if `schema_version` moves. It checks structure only and never runs a case. Regex
+graders are compiled with `node`, not Python `re`: the two disagree (`re` rejects JS-valid
+`(?<name>x)` and accepts Python-only `(?P<name>x)`), and without `node` that check is skipped
+with a warning rather than failed.
+
+Four things nothing checks, so all four stay review items: that every reference file is
+still routed from SKILL.md, that `references/examples.yaml` still parses, that an eval
+grader still means what it was written to mean, and that the descriptions in SKILL.md's
+reference table and README's **Skill Contents** table still match what the files cover.
+The last one drifts silently — link checking keeps the *file list* honest while the prose
+beside it goes stale, so a row can point at the right file and still describe an older
+version of it.
+
+To check that a prompt actually triggers the skill (the eval suite cannot run yet), run it in
+a fresh session from an empty directory and look for the `Skill` call in the stream:
+
+```bash
+claude -p "<prompt>" --plugin-dir <repo-root> --output-format stream-json --verbose --max-turns 1 --allowedTools Skill
+```
+
+`--max-turns 1` is enough — the call appears in the first response — so a check is one API
+call (~25k tokens of system prompt and skill descriptions; `--model haiku` is the cheapest and
+also the stricter test). `--plugin-dir` tests the working tree, not the installed plugin,
+which may be releases behind. Disable other plugins for the run (`--settings` with an
+`enabledPlugins` map): a plugin hook that orders skill use makes any prompt pass. The `Base
+directory for this skill:` line in the output confirms which copy loaded. From inside a
+Claude Code session, prefix `env -u CLAUDECODE` or the nested `claude` refuses to start.
+
+## Reviewing Skill PRs
+
+- Judge prose as agent-consumed context, not human docs — the Skill Authoring Principles above are the review bar (e.g. an operator→result lookup table beats narrative bullets, because agents land here holding one case to resolve)
+- Skills make version-pinned claims about HA behavior — verify against source at the current tag (`gh api repos/home-assistant/core/releases --jq '.[0].tag_name'`): `gh api repos/home-assistant/core/contents/<path>?ref=<tag> --jq .content | base64 -d`
+- Purpose-specific trigger/condition keys aren't enumerable from core source — list them from the docs repo: `gh api "repos/home-assistant/home-assistant.io/contents/source/_triggers?ref=current" --jq '.[].name'` (also `_conditions`, `_actions`)
+- UI renames, terminology, and default changes appear only in release blog posts, not core source: `source/_posts/<date>-release-<version>.markdown` in the docs repo (e.g. `2026-08-05-release-20268.markdown`). Use `gh api` — plain `curl` is sandboxed here and returns empty
+- **The blog says *what* changed, not *which version* it landed in.** Its prose often implies a feature pre-existed ("X now has conditions to match its triggers") when the whole component is new. Date a feature by fetching its path at the *previous* tag — a 404 at the previous tag that exists at the current one means the whole thing is new
+- Community PRs come from forks: base-repo `?ref=<pr-branch>` 404s; get the fork with `gh pr view <pr> --json headRepository` and fetch files from there
+- Helper claims need **both** `config_flow.py` (flow submission) and the platform file's `PLATFORM_SCHEMA` (YAML) — they diverge in key names, value types, and which keys exist. Traps: `vol.Required(` usually puts the `CONF_*` on the *next* line, so grep drops fields and mis-attributes Required/Optional; resolve `CONF_*` to its string (`CONF_ROUND_DIGITS` is `"round"` in derivative, `"round_digits"` in min_max); `options_flow`-only fields are rejected at creation
+- Verifying a claim confirms what it says, not whether it over-generalizes. Add a pass that tries to disprove ("which helpers does this NOT hold for?"), mechanically where possible — e.g. diff the two schemas' key sets in a script

ha_mcp_dev-8.3.0.dev2454/src/ha_mcp/resources/skills-vendor/CLAUDE.md

@@ -0,0 +1,99 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repo Layout
+
+Eval cases live in a top-level `evals/<case>/case.yaml`, **not** under `skills/`. `claude
+plugin eval` rejects any eval directory whose first segment names a loaded component directory
+(`commands`, `skills`, `agents`, `hooks`, `themes`, `output-styles`, `monitors`, `workflows`,
+`bin`) — and rejects it *softly*: it warns, falls back to the default `evals/`, and finds
+nothing, so cases in the wrong place silently never run. `evals/` at the plugin root is the
+default and needs no `experimental.evals` key.
+
+**SKILL.md is in context on every trigger; `references/` load only when read.** That is why
+SKILL.md body size is capped and why domain-niche content belongs in a reference file behind
+a single routing row, not in the always-loaded table.
+
+## Skill Format
+
+Every skill is a `SKILL.md` with `name`/`description` frontmatter. Full authoring constraints: `CONTRIBUTING.md`. The one CI cannot catch:
+- `metadata.version` must be `"0"` on new skills — do not edit manually; CI assigns the real version on merge and syncs it into `.claude-plugin/plugin.json` (`.version`) and `.claude-plugin/marketplace.json` (`.metadata.version`) — three files, one source of truth
+- `description` is capped at 1024 chars and runs close to it — measure the parsed length before adding trigger/symptom bullets: `uvx --from skills-ref agentskills read-properties skills/<skill-name> | jq '.description | length'`
+
+## Skill Authoring Principles
+
+The wording of these content-quality principles is mirrored in `CONTRIBUTING.md`
+(contributors); each file also carries guidance the other omits. When you change a shared
+principle, change both — they have drifted before.
+
+- **Context window conservation** — keep what is HA-specific, cut general programming advice; the test is the content itself, not whether a given model already knows it (skills run on frontier and small local models alike)
+- **Conciseness** — provide patterns and quick-reference tables, not tutorials
+- **Consistent terminology** — one term per concept throughout a skill; contrasting code blocks are `# WRONG — why` / `# RIGHT — why` (emoji only in table status columns). A renamed HA term uses the new name and cites the old one with its version ("named Developer Tools before 2026.8") — never a bare swap, since readers on older releases still see the old label
+- **Symptom-based triggering** — the `description` frontmatter should describe observable agent behaviors that signal the skill is needed
+- **No tool names** — reference HA REST APIs and concepts, never specific MCP tool names (e.g. `ha_rename_entity`); tool names vary by agent setup
+
+## Validation
+
+To validate locally:
+
+```bash
+uvx --from skills-ref agentskills validate skills/<skill-name>
+```
+
+Four more checks gate a merge. `agnix` and `lychee` run as release binaries pinned in
+`.github/workflows/` — install those versions (lychee's release tag is `lychee-vX.Y.Z`, not
+`vX.Y.Z`); `claude plugin validate` ships with the Claude Code CLI; the eval-case checker is
+in-repo and needs only PyYAML:
+
+```bash
+agnix skills/ --target claude-code                              # spec conformance
+lychee --offline --include-fragments --no-progress './**/*.md'  # local links + #anchors
+claude plugin validate .                                        # plugin manifests
+python scripts/check_eval_cases.py                              # evals/<case>/case.yaml
+```
+
+agnix catches what skills-ref's unenforced `metadata: dict[str, str]` annotation lets pass —
+e.g. an unquoted integer version, which strict clients refuse. In CI (`links.yml`) lychee runs
+that same local check on PRs touching `.md`/`.yaml`, plus external URLs weekly, dot-directories
+excluded; it cannot see references written as inline code. `check_eval_cases.py` validates the
+shape of eval cases against the `claude plugin eval` 1.1 schema — that command is gated behind
+early access, so its own parser never runs here; the schema is transcribed by hand and needs
+re-deriving if `schema_version` moves. It checks structure only and never runs a case. Regex
+graders are compiled with `node`, not Python `re`: the two disagree (`re` rejects JS-valid
+`(?<name>x)` and accepts Python-only `(?P<name>x)`), and without `node` that check is skipped
+with a warning rather than failed.
+
+Four things nothing checks, so all four stay review items: that every reference file is
+still routed from SKILL.md, that `references/examples.yaml` still parses, that an eval
+grader still means what it was written to mean, and that the descriptions in SKILL.md's
+reference table and README's **Skill Contents** table still match what the files cover.
+The last one drifts silently — link checking keeps the *file list* honest while the prose
+beside it goes stale, so a row can point at the right file and still describe an older
+version of it.
+
+To check that a prompt actually triggers the skill (the eval suite cannot run yet), run it in
+a fresh session from an empty directory and look for the `Skill` call in the stream:
+
+```bash
+claude -p "<prompt>" --plugin-dir <repo-root> --output-format stream-json --verbose --max-turns 1 --allowedTools Skill
+```
+
+`--max-turns 1` is enough — the call appears in the first response — so a check is one API
+call (~25k tokens of system prompt and skill descriptions; `--model haiku` is the cheapest and
+also the stricter test). `--plugin-dir` tests the working tree, not the installed plugin,
+which may be releases behind. Disable other plugins for the run (`--settings` with an
+`enabledPlugins` map): a plugin hook that orders skill use makes any prompt pass. The `Base
+directory for this skill:` line in the output confirms which copy loaded. From inside a
+Claude Code session, prefix `env -u CLAUDECODE` or the nested `claude` refuses to start.
+
+## Reviewing Skill PRs
+
+- Judge prose as agent-consumed context, not human docs — the Skill Authoring Principles above are the review bar (e.g. an operator→result lookup table beats narrative bullets, because agents land here holding one case to resolve)
+- Skills make version-pinned claims about HA behavior — verify against source at the current tag (`gh api repos/home-assistant/core/releases --jq '.[0].tag_name'`): `gh api repos/home-assistant/core/contents/<path>?ref=<tag> --jq .content | base64 -d`
+- Purpose-specific trigger/condition keys aren't enumerable from core source — list them from the docs repo: `gh api "repos/home-assistant/home-assistant.io/contents/source/_triggers?ref=current" --jq '.[].name'` (also `_conditions`, `_actions`)
+- UI renames, terminology, and default changes appear only in release blog posts, not core source: `source/_posts/<date>-release-<version>.markdown` in the docs repo (e.g. `2026-08-05-release-20268.markdown`). Use `gh api` — plain `curl` is sandboxed here and returns empty
+- **The blog says *what* changed, not *which version* it landed in.** Its prose often implies a feature pre-existed ("X now has conditions to match its triggers") when the whole component is new. Date a feature by fetching its path at the *previous* tag — a 404 at the previous tag that exists at the current one means the whole thing is new
+- Community PRs come from forks: base-repo `?ref=<pr-branch>` 404s; get the fork with `gh pr view <pr> --json headRepository` and fetch files from there
+- Helper claims need **both** `config_flow.py` (flow submission) and the platform file's `PLATFORM_SCHEMA` (YAML) — they diverge in key names, value types, and which keys exist. Traps: `vol.Required(` usually puts the `CONF_*` on the *next* line, so grep drops fields and mis-attributes Required/Optional; resolve `CONF_*` to its string (`CONF_ROUND_DIGITS` is `"round"` in derivative, `"round_digits"` in min_max); `options_flow`-only fields are rejected at creation
+- Verifying a claim confirms what it says, not whether it over-generalizes. Add a pass that tries to disprove ("which helpers does this NOT hold for?"), mechanically where possible — e.g. diff the two schemas' key sets in a script

ha_mcp_dev-8.3.0.dev2454/src/ha_mcp/resources/skills-vendor/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing
+
+Skills for this repository follow the [Agent Skills open standard](https://agentskills.io). See the [specification](https://agentskills.io/specification) for the full format reference.
+
+## Skill Format
+
+Structure each skill as a folder under `skills/` with a `SKILL.md` file:
+
+```
+skills/
+  your-skill-name/
+    SKILL.md              # Required
+    references/           # Optional: additional docs loaded on demand
+    scripts/              # Optional: utility scripts
+    assets/               # Optional: static resources (templates, data files)
+```
+
+### SKILL.md requirements
+
+- **YAML frontmatter** with `name` (letters, numbers, hyphens only; 64 chars max) and `description` (1024 chars max).
+- **`metadata.version`** a monotonically incrementing integer written as a string (e.g. `"1"`) — the spec requires metadata values to be strings. Set to `0` when creating a new skill — CI assigns the real version automatically on merge. Do not edit this field manually.
+- **`description`** in third person. Describe what the skill does and when to use it. Include keywords that help agents match tasks. Don't summarize the skill's workflow. Err toward over-triggering rather than under-triggering — a skill that loads when marginally relevant costs tokens; one that fails to load costs a wrong answer. Explicit `TRIGGER THIS SKILL WHEN` and `SYMPTOMS` sections listing observable agent behaviours match better than prose.
+- **Body** under 500 lines. Split into reference files if approaching this limit.
+- **Reference files** one level deep from SKILL.md—no nested references.
+- **Cross-reference them with markdown links**, not inline code — CI validates both the path and the `#anchor`. Links resolve relative to the containing file, so inside `references/` a sibling is `x.md`, not `references/x.md`.
+- **Forward slashes** in all file paths.
+- **Bundled scripts**, if any, must be introduced by SKILL.md — when to reach for them and how to invoke them. An unreferenced script is dead weight the agent never finds.
+
+See Anthropic's [skill authoring best practices](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills/best-practices) for additional guidance.
+
+## Guiding Principles
+
+**The context window is a public good.** Every line is loaded on every invocation, by every agent. Challenge each paragraph: does its token cost justify its value?
+
+**Domain-specific, not general.** The test is whether the knowledge is Home Assistant-specific — *not* whether a model already knows it. These skills install into agents ranging from frontier models to small local ones, so "the model knows this" is not something a reviewer can evaluate, and it is the wrong question anyway. Keep HA behaviour, version-pinned changes, and anywhere HA diverges from what the general syntax implies (`state_attr` returning `None` rather than an undefined, the `unavailable`/`unknown` sentinel states). Cut general programming tutorials, and text that only restates an identifier.
+
+**Concise over verbose.** Provide patterns and quick-reference tables, not narrative explanations.
+
+**Consistent terminology.** Choose one term for each concept and stick to it throughout the skill. Contrasting code blocks are marked `# WRONG — why` and `# RIGHT — why`, in that order; do not introduce AVOID/CORRECT, BAD/GOOD, or ❌/✅ variants. Reserve ❌/✅ for table status columns.
+
+**Renamed HA terms keep a pointer to the old name.** When HA renames something user-facing, use the new term and note the old one with the version it changed in — `**Tools → Events** (named **Developer Tools** before 2026.8)`. Readers on older releases still see the old label in their UI, so a bare swap strands them. This has come up three times in two years: services → actions (2024.8), add-ons → Apps (2026.2), Developer Tools → Tools (2026.8).
+
+**Explain the *why*, not bare commands.** A rule an agent understands survives paraphrase and transfers to the next case; a bare MUST/NEVER gets dropped the moment the situation differs slightly. Give the mechanism — *`device_id` breaks on re-add* beats *never use `device_id`*.
+
+**Don't couple skills to specific tool names.** Reference HA concepts and REST APIs instead of naming specific MCP tools (e.g. `ha_rename_entity`, `ha_get_integration`). Tool names change and not all agents have the same toolset; the underlying HA APIs and concepts are stable.
+
+**No opinionated conventions.** Skills in this repo are applied to any HA installation. Naming conventions, code style preferences, and other user-space opinions belong in a personal skill or instance-level `CLAUDE.md`, not here. Only include guidance that reflects official HA behaviour or well-established community consensus.
+
+## Reporting Skill Problems
+
+When a skill misleads your agent — broken dashboards, failed automations, wrong configurations — first search existing issues for the same skill and failure. If a matching issue exists, react with thumbs-up or comment with additional context. Otherwise, open a new issue with the **Report Bad Skill Advice** template. Let the agent fill it out — it holds the full context and can trace the failure to its source in the skill.
+
+The template covers five sections: context, timeline, root cause, impact, and environment. A thorough report gives maintainers everything they need to fix the skill in one pass.
+
+## Submitting a Skill
+
+1. Fork this repository.
+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. If you added or removed reference files, link them from `SKILL.md`'s reference table and update the **Skill Contents** table in `README.md`. CI checks that links resolve, but nothing detects a reference file that nothing links to.
+6. If you materially changed what a reference file *covers* — a new section, a scope the old description no longer implies — update its row in both `SKILL.md`'s reference table and `README.md`'s **Skill Contents** table, and the coverage summary under **Included Skill**. The file list staying correct is not the same as the descriptions staying correct: nothing checks the descriptions, and they are what routes a reader to the right file.
+7. Submit a pull request describing what your skill teaches and what problems it solves.

ha_mcp_dev-8.3.0.dev2454/src/ha_mcp/resources/skills-vendor/README.md

@@ -0,0 +1,117 @@
+# Home Assistant Agent Skills
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Agent Skills](https://img.shields.io/badge/Agent_Skills-agentskills.io-blue)](https://agentskills.io)
+
+An **Agent Skill** is a portable Markdown knowledge pack that teaches AI coding agents best practices for a specific technology. This repository provides one for Home Assistant, following the open [Agent Skills standard](https://agentskills.io/specification). Install it and your agent applies Home Assistant best practices in every session.
+
+## Included Skill
+
+**[home-assistant-best-practices](skills/home-assistant-best-practices/)** — a decision workflow and anti-pattern table in `SKILL.md`, backed by reference files the agent loads on demand. It covers:
+
+- **Authoring** — native triggers and conditions over templates, helper selection, automation modes, device control and button/remote patterns, scenes, blueprints
+- **Dashboards** — layout, views, cards, badges, custom cards
+- **Operations** — YAML-only integration management, backups and recovery, safe refactoring of existing config
+- **AppDaemon** — when to use it over native HA, and how to structure apps
+
+Agents make a predictable set of mistakes with Home Assistant config — Jinja templates where a native trigger, condition, or helper exists, `device_id` where `entity_id` belongs, `mode: single` on a motion light, renames that silently break dashboards and scripts — and the anti-pattern table names each one with its fix. A typical entry:
+
+```yaml
+# Without the skill — template condition: a typo or wrong entity ID surfaces only when it runs
+condition: template
+value_template: "{{ states('sensor.living_room_temperature') | float > 25 }}"
+
+# With the skill — native condition: config validated when the automation loads
+condition: numeric_state
+entity_id: sensor.living_room_temperature
+above: 25
+```
+
+See [Skill Contents](#skill-contents) for the file-by-file map.
+
+## Installation
+
+### Agent Skills installer
+
+Requires [Node.js 22.20+](https://nodejs.org/).
+
+```bash
+npx skills add homeassistant-ai/skills
+```
+
+Works with AI coding agents that support the [Agent Skills standard](https://agentskills.io): Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and 70+ others. To update: `npx skills update`
+
+### Claude Code plugin
+
+Claude Code also accepts the installer above, which places the skill files in your `.claude/skills/` directory. The commands below install it as a plugin instead, kept in Claude Code's own plugin cache.
+
+Run each command separately inside Claude Code:
+
+```
+/plugin marketplace add homeassistant-ai/skills
+```
+```
+/plugin install home-assistant-skills@home-assistant-skills
+```
+
+Run `/reload-plugins` or restart Claude Code for the skill to take effect.
+
+Auto-update is off by default for third-party marketplaces. To turn it on, run `/plugin`, open **Marketplaces**, choose `home-assistant-skills`, and select **Enable auto-update**. To update by hand instead, run `claude plugin update home-assistant-skills` from a shell, then `/reload-plugins`.
+
+### Claude Desktop / claude.ai
+
+Both apps share the same Customize UI, reached via the left sidebar (Claude Desktop) or [claude.ai/customize](https://claude.ai/customize) (browser).
+
+1. Enable code execution: Settings → Capabilities → turn on **Cloud code execution and file creation** (required for skills)
+2. Customize → Plugins → Add → Add marketplace → Add from a repository
+3. Select or enter `homeassistant-ai/skills` (or the full URL, `https://github.com/homeassistant-ai/skills`) → Sync
+
+This installs the skill as a plugin synced from this repo — no download or zip needed. **Sync automatically** is on by default, so later updates arrive on their own.
+
+<details>
+<summary>Alternative: upload the skill manually as a zip</summary>
+
+1. Enable code execution: Settings → Capabilities → turn on **Cloud code execution and file creation** (required for skills)
+2. Download or clone this repository
+3. Zip the skill folder: `cd skills && zip -r home-assistant-best-practices.zip home-assistant-best-practices/`
+4. Customize → Skills → Add → Upload a skill
+
+</details>
+
+## Usage
+
+Once installed, the skill loads on its own whenever the agent works on automations, scripts, scenes, helpers, dashboards, blueprints, or backups — it needs no explicit invocation. Try:
+
+> Create an automation that turns on the hallway light when motion is detected and turns it off five minutes after the motion stops.
+
+## Skill Contents
+
+The `home-assistant-best-practices` skill includes:
+
+| File | Purpose |
+|------|---------|
+| [`SKILL.md`](skills/home-assistant-best-practices/SKILL.md) | Decision workflow, anti-pattern table, and pointers to the reference files below |
+| [`references/safe-refactoring.md`](skills/home-assistant-best-practices/references/safe-refactoring.md) | Safe workflow for renaming entities, replacing helpers, restructuring automations; config-entry and storage-dashboard blind spots |
+| [`references/automation-patterns.md`](skills/home-assistant-best-practices/references/automation-patterns.md) | Purpose-specific and native triggers/conditions, waits, variables, automation modes, control flow (choose, repeat, parallel), disabling automations |
+| [`references/helper-selection.md`](skills/home-assistant-best-practices/references/helper-selection.md) | Built-in helpers vs template sensors (with decision matrix) |
+| [`references/template-guidelines.md`](skills/home-assistant-best-practices/references/template-guidelines.md) | When to use templates, when to avoid them, template sensor best practices, reusable `custom_templates` macros |
+| [`references/yaml-only-integrations.md`](skills/home-assistant-best-practices/references/yaml-only-integrations.md) | YAML-only integration types, post-edit actions (reload vs restart) |
+| [`references/device-control.md`](skills/home-assistant-best-practices/references/device-control.md) | Actions and targeting, entity_id vs device_id, buttons and remotes, domain-specific patterns |
+| [`references/scenes.md`](skills/home-assistant-best-practices/references/scenes.md) | Scene authoring: config shape, snapshot/restore, snapshot-vs-script distinction |
+| [`references/dashboard-guide.md`](skills/home-assistant-best-practices/references/dashboard-guide.md) | Dashboard layout, view types, strategies, sections, cards, badges, custom cards, CSS styling, HACS |
+| [`references/dashboard-cards.md`](skills/home-assistant-best-practices/references/dashboard-cards.md) | Card type lookup and card-specific documentation |
+| [`references/domain-docs.md`](skills/home-assistant-best-practices/references/domain-docs.md) | Integration and domain documentation (actions, entity attributes); doc pages for specific triggers, conditions, and actions |
+| [`references/examples.yaml`](skills/home-assistant-best-practices/references/examples.yaml) | Compound examples combining multiple best practices |
+| [`references/appdaemon.md`](skills/home-assistant-best-practices/references/appdaemon.md) | AppDaemon apps: when to use vs. native HA, app structure, actions, scheduling, error handling, safe refactoring impact |
+| [`references/blueprint-guide.md`](skills/home-assistant-best-practices/references/blueprint-guide.md) | Blueprint authoring: metadata & `source_url`, inputs & selectors, `target` vs `entity`, defaults, `!input` templating, versioning |
+| [`references/backups.md`](skills/home-assistant-best-practices/references/backups.md) | Full instance backups vs rolling one object back, when an operation needs a backup first, what an archive contains, encryption keys, restore verification, backup deletion |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on writing and submitting skills.
+
+Skill misled your agent? Open an issue with the [Report Bad Skill Advice](https://github.com/homeassistant-ai/skills/issues/new?template=skill-rca.md) template and let the agent fill it in — it holds the context to trace the failure to its source in the skill.
+
+## License
+
+MIT

ha_mcp_dev-8.3.0.dev2454/src/ha_mcp/resources/skills-vendor/evals/area-target-over-entity-list/case.yaml

@@ -0,0 +1,49 @@
+schema_version: "1.1"
+name: area-target-over-entity-list
+description: >
+  The user states the maintenance requirement outright — they keep adding
+  sensors. An area or floor target follows membership; an enumerated entity list
+  does not.
+tags: [automations, triggers]
+
+execution:
+  prompt: >-
+    send me a phone notification if any motion sensor downstairs picks something up
+    while we're away. I keep adding sensors down there so I don't want to keep
+    editing this
+  allowed_tools: []
+  max_turns: 10
+  timeout_seconds: 300
+runs: 3
+
+graders:
+  - type: tool_used
+    name: skill-fired
+    tool: Skill
+    input_match: '"skill"\s*:\s*"(?:[\w-]+:)?home-assistant-best-practices"'
+    min: 1
+
+  - type: llm
+    name: uses-area-or-floor-target
+    criteria: >-
+      The trigger targets an area, floor, or label rather than a hardcoded list of
+      sensor entity IDs.
+
+      FAIL if the automation enumerates `binary_sensor.*` entity IDs.
+
+  - type: llm
+    name: uses-purpose-specific-trigger
+    criteria: >-
+      The response uses a purpose-specific motion trigger rather than a generic
+      `trigger: state` block over a list of entities.
+
+  - type: llm
+    name: addresses-the-maintenance-ask
+    criteria: >-
+      The response explains that sensors added to the area later are picked up
+      without editing the automation — answering the user's stated reason for
+      asking.
+
+expected_outcome: >-
+  A purpose-specific motion trigger with an area/floor target, plus an explanation
+  that new sensors are picked up automatically.

ha_mcp_dev-8.3.0.dev2454/src/ha_mcp/resources/skills-vendor/evals/arrive-home-automation/case.yaml

@@ -0,0 +1,41 @@
+schema_version: "1.1"
+name: arrive-home-automation
+description: >
+  The obvious presence automation. Guards against the `entered_home` device
+  trigger type, removed in 2026.5, which pre-2026.5 training data still suggests.
+tags: [automations, triggers]
+
+execution:
+  prompt: create an automation that turns on the lights when I get home
+  allowed_tools: []
+  max_turns: 10
+  timeout_seconds: 300
+runs: 3
+
+graders:
+  - type: tool_used
+    name: skill-fired
+    tool: Skill
+    input_match: '"skill"\s*:\s*"(?:[\w-]+:)?home-assistant-best-practices"'
+    min: 1
+
+  - type: llm
+    name: uses-state-trigger
+    criteria: >-
+      The automation triggers on a state change of a `person.*` or
+      `device_tracker.*` entity with `to: home` (a `trigger: state` block, or a
+      purpose-specific presence trigger that targets a person entity).
+
+  - type: llm
+    name: no-entered-home-trigger
+    criteria: >-
+      The automation does NOT use the `entered_home` device trigger type, which was
+      removed in Home Assistant 2026.5.
+
+      Judge the automation the response tells the user to create. PASS if
+      `entered_home` appears only in prose explaining that it was removed and must
+      not be used. FAIL if it appears in a trigger block the user is told to use.
+
+expected_outcome: >-
+  A state trigger on a person or device_tracker entity with `to: home`. No
+  `entered_home` device trigger.