homeassistant-ai
diff --git a/‎homeassistant-addon-dev/config.yaml‎
Lines changed: 2 additions & 0 deletions b/‎homeassistant-addon-dev/config.yaml‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎homeassistant-addon-dev/translations/en.yaml‎
Lines changed: 16 additions & 0 deletions b/‎homeassistant-addon-dev/translations/en.yaml‎
Lines changed: 16 additions & 0 deletions
diff --git a/‎homeassistant-addon/config.yaml‎
Lines changed: 2 additions & 0 deletions b/‎homeassistant-addon/config.yaml‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎homeassistant-addon/start.py‎
Lines changed: 15 additions & 0 deletions b/‎homeassistant-addon/start.py‎
Lines changed: 15 additions & 0 deletions
diff --git a/‎homeassistant-addon/translations/en.yaml‎
Lines changed: 16 additions & 0 deletions b/‎homeassistant-addon/translations/en.yaml‎
Lines changed: 16 additions & 0 deletions
diff --git a/‎src/ha_mcp/config.py‎
Lines changed: 18 additions & 0 deletions b/‎src/ha_mcp/config.py‎
Lines changed: 18 additions & 0 deletions
diff --git a/‎src/ha_mcp/server.py‎
Lines changed: 28 additions & 10 deletions b/‎src/ha_mcp/server.py‎
Lines changed: 28 additions & 10 deletions
diff --git a/‎src/ha_mcp/settings_ui.py‎
Lines changed: 4 additions & 0 deletions b/‎src/ha_mcp/settings_ui.py‎
Lines changed: 4 additions & 0 deletions
@@ -39,6 +39,7 @@ options:
   enable_custom_component_integration: false
   enable_code_mode: false
   enable_lite_docstrings: false
+  enable_mandatory_bps: true
   enable_auto_backup: true
   auto_backup_throttle_minutes: 0
   auto_backup_retain_per_entity: 100
@@ -55,6 +56,7 @@ schema:
   enable_yaml_config_editing: bool?
   enable_code_mode: bool?
   enable_lite_docstrings: bool?
+  enable_mandatory_bps: bool?
   enable_filesystem_tools: bool?
   enable_custom_component_integration: bool?
   enable_auto_backup: bool?
 
@@ -127,6 +127,22 @@ configuration:
       features" toggle above (and in the web UI) to be on — otherwise
       this sub-flag is ignored at runtime regardless of its value
       here.
+  enable_mandatory_bps:
+    name: Attach best-practice skills on writes
+    description: >-
+      Master switch for the write-tool skill content delivery feature
+      (issue #1182). When enabled (default), the six config write tools
+      (automations, scripts, scenes, helpers, dashboards, raw YAML)
+      attach the canonical Home Assistant best-practice reference files
+      under `skill_content` on every successful write, plus auto-embed
+      any reference sections cited by best-practice warnings. Each tool
+      also exposes a per-call `MandatoryBPS` parameter the agent can
+      set to false on subsequent calls once it has the content. When
+      this master switch is off, NO skill_content goes out regardless
+      of the per-call parameter or BP warnings. Leave on if your LLM
+      benefits from inline guidance; turn off to minimise tokens when
+      using an LLM that has the best-practice files indexed via skills
+      or another retrieval path. Requires restart to take effect.
   enable_filesystem_tools:
     name: Enable filesystem tools (beta)
     description: >-
 
@@ -45,6 +45,7 @@ options:
   enable_tool_search: false
   tool_search_max_results: 5
   enable_tool_security_policies: false
+  enable_mandatory_bps: true
   disabled_tools: ""
   pinned_tools: ""
   enable_auto_backup: true
@@ -57,6 +58,7 @@ schema:
   enable_tool_search: bool?
   tool_search_max_results: int(2,10)?
   enable_tool_security_policies: bool?
+  enable_mandatory_bps: bool?
   disabled_tools: str?
   pinned_tools: str?
   enable_auto_backup: bool?
 
@@ -282,6 +282,7 @@ def main() -> int:
     code_mode_in_config = False  # presence flag
     enable_lite_docstrings = False  # default
     lite_docstrings_in_config = False  # presence flag
+    enable_mandatory_bps = True  # default (issue #1182 — on by default, non-beta)
     # Master beta toggle: present only in the dev addon's schema.
     # Default to False (stable behaviour); when
     # the dev schema-default merges in, ``beta_master_in_config``
@@ -358,6 +359,16 @@ def main() -> int:
             enable_lite_docstrings = (
                 raw_lite_docstrings if isinstance(raw_lite_docstrings, bool) else False
             )
+            raw_mandatory_bps = config.get("enable_mandatory_bps", True)
+            if isinstance(raw_mandatory_bps, bool):
+                enable_mandatory_bps = raw_mandatory_bps
+            else:
+                log_error(
+                    "enable_mandatory_bps must be bool, got "
+                    f"{type(raw_mandatory_bps).__name__}={raw_mandatory_bps!r}; "
+                    "using default True"
+                )
+                enable_mandatory_bps = True
             # Master beta toggle is present in the dev-addon schema.
             # Track presence separately so stable
             # add-on installs (where the key is absent from options.json)
@@ -435,6 +446,10 @@ def main() -> int:
     os.environ["ENABLE_TOOL_SECURITY_POLICIES"] = str(
         enable_tool_security_policies
     ).lower()
+    # ENABLE_MANDATORY_BPS is non-beta and default-ON, so it is written
+    # unconditionally (like the stable core settings above) — never
+    # presence-gated or beta-master-gated like the beta sub-flags below.
+    os.environ["ENABLE_MANDATORY_BPS"] = str(enable_mandatory_bps).lower()
     # Beta sub-flags: only write env vars when the key is actually in
     # the addon's options.json. On stable addon,
     # none of these keys are in schema, so config.get(...) returned
 
@@ -37,6 +37,22 @@ configuration:
       and click Approve before the call proceeds. Per-tool rules with
       optional argument conditions are configured in the Tool Security
       Policies tab. Off by default. Requires restart to take effect.
+  enable_mandatory_bps:
+    name: Attach best-practice skills on writes
+    description: >-
+      Master switch for the write-tool skill content delivery feature
+      (issue #1182). When enabled (default), the six config write tools
+      (automations, scripts, scenes, helpers, dashboards, raw YAML)
+      attach the canonical Home Assistant best-practice reference files
+      under `skill_content` on every successful write, plus auto-embed
+      any reference sections cited by best-practice warnings. Each tool
+      also exposes a per-call `MandatoryBPS` parameter the agent can
+      set to false on subsequent calls once it has the content. When
+      this master switch is off, NO skill_content goes out regardless
+      of the per-call parameter or BP warnings. Leave on if your LLM
+      benefits from inline guidance; turn off to minimise tokens when
+      using an LLM that has the best-practice files indexed via skills
+      or another retrieval path. Requires restart to take effect.
   enable_auto_backup:
     name: Enable auto-backup of edits
     description: >-
 
@@ -144,6 +144,18 @@ class Settings(BaseSettings):
     # env-var users see the trade-off in their logs.
     enable_lite_docstrings: bool = Field(False, alias="ENABLE_LITE_DOCSTRINGS")
 
+    # Mandatory best-practice skills — server-side master switch for the
+    # write-tool skill_content delivery feature (issue #1182). When True
+    # (default), the six write tools (automations / scripts / scenes /
+    # helpers / dashboards / yaml) attach the canonical best-practice
+    # reference files under ``skill_content`` on every successful write,
+    # plus auto-embed any sections cited by best-practice warnings. The
+    # per-call ``MandatoryBPS`` parameter on each tool controls whether
+    # the canonical files ship for that one call. This setting is the
+    # master gate above that — when False, NO skill_content goes out
+    # regardless of the per-call param or BP warnings. Default on.
+    enable_mandatory_bps: bool = Field(True, alias="ENABLE_MANDATORY_BPS")
+
     # Filesystem tools — read/write/delete/list under the HA config dir.
     # Previously gated by a direct ``os.getenv`` call in
     # ``tools/tools_filesystem.py`` so callers (and the settings UI)
@@ -412,6 +424,12 @@ class AdvancedField(NamedTuple):
     FeatureFlagField(
         "enable_tool_security_policies", "ENABLE_TOOL_SECURITY_POLICIES", bool
     ),
+    # Non-beta, default-ON master switch for write-tool skill_content
+    # delivery (#1182). Grouped with the non-beta flags above the beta
+    # run below; intentionally NOT in BETA_FEATURE_FIELDS (it must not be
+    # gated by the beta master) nor in ADVANCED_SETTINGS_FIELDS (registries
+    # are name-disjoint per _validate_registries()).
+    FeatureFlagField("enable_mandatory_bps", "ENABLE_MANDATORY_BPS", bool),
     FeatureFlagField("enable_yaml_config_editing", "ENABLE_YAML_CONFIG_EDITING", bool),
     FeatureFlagField("enable_lite_docstrings", "ENABLE_LITE_DOCSTRINGS", bool),
     FeatureFlagField("enable_filesystem_tools", "HAMCP_ENABLE_FILESYSTEM_TOOLS", bool),
 
@@ -200,10 +200,13 @@ def _get_skills_dir(self) -> Path | None:
 
         Skills are vendored via a git submodule at resources/skills-vendor/.
         The actual skill directories live under the skills/ subdirectory
-        within that repo.
+        within that repo. Delegates to
+        :func:`ha_mcp.utils.skill_loader.get_skills_dir` so the write-tool
+        ``MandatoryBPS`` parameter resolves the same path.
         """
-        skills_dir = Path(__file__).parent / "resources" / "skills-vendor" / "skills"
-        return skills_dir if skills_dir.exists() else None
+        from .utils.skill_loader import get_skills_dir
+
+        return get_skills_dir()
 
     def _build_skills_instructions(self) -> str | None:
         """Build server instructions from bundled skill frontmatter.
@@ -1434,13 +1437,28 @@ def _handle_skill_guide_call(
                 )
             )
 
-        return {
-            "success": True,
-            "skill": skill,
-            "file": file,
-            "uri": f"skill://{skill}/{file}",
-            "content": content,
-        }
+        # Hint goes at the top of the response so the LLM sees it before
+        # parsing the (potentially large) content body. Scoped to the
+        # best-practice skill because that's the one the write-tool
+        # MandatoryBPS param gates; other skills (if any) are unrelated.
+        from .tools.util_helpers import (
+            _HA_BEST_PRACTICES_SKILL_NAME,
+            _SKILL_GUIDE_MANDATORYBPS_HINT,
+        )
+
+        response: dict[str, Any] = {}
+        if skill == _HA_BEST_PRACTICES_SKILL_NAME:
+            response["skill_content_hint"] = _SKILL_GUIDE_MANDATORYBPS_HINT
+        response.update(
+            {
+                "success": True,
+                "skill": skill,
+                "file": file,
+                "uri": f"skill://{skill}/{file}",
+                "content": content,
+            }
+        )
+        return response
 
     # Helper methods required by EnhancedToolsMixin
 
 
@@ -2165,6 +2165,10 @@ def apply_tool_visibility(
     label: "Enable Tool Security Policies",
     help: "Opt-in middleware that gates high-stakes MCP tool calls behind user approval. When enabled, tools that match a rule in the Tool Security Policies tab require you to click Approve in the web UI before they run. Off by default. Per-tool rules with optional argument conditions are configured in the Tool Security Policies tab. Requires restart to take effect.",
   },
+  enable_mandatory_bps: {
+    label: "Attach best-practice skills on writes",
+    help: "Master switch for the write-tool skill content delivery feature (issue #1182). When enabled (default), the six config write tools (automations, scripts, scenes, helpers, dashboards, raw YAML) attach the canonical Home Assistant best-practice reference files under skill_content on every successful write, plus auto-embed any reference sections cited by best-practice warnings. Each tool also exposes a per-call MandatoryBPS parameter the agent can set to false on subsequent calls once it has the content. When this master switch is off, NO skill_content goes out regardless of the per-call parameter or BP warnings. Leave on if your LLM benefits from inline guidance; turn off to minimise tokens when using an LLM that has the best-practice files indexed via skills or another retrieval path. Requires restart to take effect.",
+  },
   // Master beta toggle — gates the 5 sub-flags below at runtime
   // (see config.py:_apply_feature_flag_overrides master gate). UI
   // dims sub-rows when this is off and re-renders live on flip.