feat: drop ENABLE_SKILLS / ENABLE_SKILLS_AS_TOOLS toggles, rename to ha_list_resources / ha_read_resource

The two skills toggles were redundant once homeassistant-ai#960 (web settings UI) shipped:
the original justifications — "avoid local-skill conflicts" (skills served
via skill:// URIs and locally-installed skills under ~/.claude/skills/ live
in separate namespaces) and "don't burn extra context" (resources are not
auto-injected; list_resources only returns metadata) — don't survive
scrutiny. Per-tool visibility is now the single mechanism; users who want
ha_list_resources or ha_read_resource off can disable them from the web
settings UI like any other tool.

Changes:
- Drop enable_skills, enable_skills_as_tools, _skills_dependency validator
  from src/ha_mcp/config.py.
- Always register SkillsDirectoryProvider and the ResourcesAsTools transform
  in server._register_skills(); always include the skills hint in
  _build_skills_instructions and the search-tool description.
- Rename the transform-generated tools list_resources / read_resource to
  ha_list_resources / ha_read_resource via a HaResourcesAsTools subclass
  so they follow the project's ha_<verb>_<noun> convention.
- Surface the renamed pair in the settings UI: extend _get_tool_metadata
  with TRANSFORM_GENERATED_TOOLS stub injection, so users can disable them
  per-tool (FastMCP's local_provider doesn't see transform-appended tools).
- Drop add-on toggles: enable_skills / enable_skills_as_tools removed from
  homeassistant-addon{,-dev}/config.yaml schema + options, the env-var
  setup and the .skills_as_tools_default_migration_v1 migration helper
  removed from homeassistant-addon/start.py, and the supervisor labels
  removed from homeassistant-addon-dev/translations/en.yaml (prod
  translations sync at the next biweekly release).
- Simplify best_practice_checker: drop get_skill_prefix() and its callers;
  always reference skill:// URIs.
- Tests: replace the obsolete enable_skills* assertions with
  field-removal assertions, drop TestSkillsAsToolsMigration, update
  unit tests for unconditional registration, add e2e coverage that
  ha_list_resources / ha_read_resource appear (and unprefixed names
  don't), add a unit test that _get_tool_metadata injects stubs when
  local_provider omits them.
- README and homeassistant-addon-dev/DOCS.md: remove the toggle rows;
  document the per-tool visibility path.

Migration note: existing users with ENABLE_SKILLS_AS_TOOLS=false lose
the env-var path. Equivalent opt-out is available per-tool in the web
settings UI, documented in DOCS.md and README. Same outcome is
achievable via the alternate mechanism, so this is not a breaking
change per AGENTS.md's definition.

Closes homeassistant-ai#1133

Author: kingpanther13

README.md

@@ -225,12 +225,9 @@ An MCP server can create automations, helpers, and dashboards, but it has no opi
 
 ### Bundled Skills (built-in)
 
-Skills from `homeassistant-ai/skills` are bundled and served as [MCP resources](https://modelcontextprotocol.io/docs/concepts/resources) via `skill://` URIs. Any MCP client that supports resources can discover them automatically — no manual installation needed.
+Skills from `homeassistant-ai/skills` are bundled and served as [MCP resources](https://modelcontextprotocol.io/docs/concepts/resources) via `skill://` URIs. Any MCP client that supports resources can discover them automatically — no manual installation needed. For tool-only clients, the same skills are also exposed as `ha_list_resources` / `ha_read_resource` tools. Resources are not auto-injected into context — clients must explicitly request them, so idle context cost is just the metadata listing.
 
-| Setting | Default | Description |
-|---------|---------|-------------|
-| `ENABLE_SKILLS` | `true` | Serve skills as MCP resources. Resources are not auto-injected into context — clients must explicitly request them. |
-| `ENABLE_SKILLS_AS_TOOLS` | `true` | Expose skills and doc resources via `list_resources`/`read_resource` tools. Resource-capable clients can set to `false` to reduce tool count. |
+If you want to hide either tool from the catalog, disable it from the web settings UI like any other tool.
 
 Skills can still be installed manually for clients that prefer local skill files — see the [skills repo](https://github.com/homeassistant-ai/skills) for instructions.
 

homeassistant-addon-dev/DOCS.md

@@ -14,8 +14,6 @@ The dev add-on uses the same configuration as the stable version. See the main a
 |--------|-------------|---------|
 | `backup_hint` | Backup strength preference | `normal` |
 | `secret_path` | Custom secret path (optional) | auto-generated |
-| `enable_skills` | Serve bundled HA best-practice skills as MCP resources | `true` |
-| `enable_skills_as_tools` | Expose skills via list_resources/read_resource tools | `true` |
 | `enable_tool_search` | Replace full tool catalog with search-based discovery (~46K → ~5K tokens). ⚠️ Do NOT enable for Claude Sonnet/Opus — their built-in tool search conflicts with ha-mcp's. Disable one or the other. | `false` |
 | `enable_yaml_config_editing` *(beta)* | Enables `ha_config_set_yaml` for editing `configuration.yaml` directly. Requires `ha_mcp_tools` custom component. | `false` |
 | `enable_filesystem_tools` *(beta)* | Enables file read/write tools (`ha_list_files`, `ha_read_file`, `ha_write_file`, `ha_delete_file`). Requires `ha_mcp_tools` custom component. | `false` |
@@ -25,6 +23,8 @@ The dev add-on uses the same configuration as the stable version. See the main a
 | `pinned_tools` | Comma-separated list of tool names to pin when tool search is enabled (seed value; web UI is primary) | empty |
 | `verify_ssl` | Verify the HA server's TLS certificate. Disable for self-signed certs or hostname mismatches. Weakens security — leave on unless needed. | `true` |
 
+*Removed in 7.4.x:* `enable_skills` *and* `enable_skills_as_tools`*. Bundled skills are now always served; to hide* `ha_list_resources` *or* `ha_read_resource` *from the catalog, disable them from the Tool Settings Web UI (see below).*
+
 Beta options are hidden under "Show unused optional configuration options" in the add-on Configuration tab. See [beta.md](https://github.com/homeassistant-ai/ha-mcp/blob/master/docs/beta.md) for details.
 
 ## Tool Settings Web UI

homeassistant-addon-dev/config.yaml

@@ -20,8 +20,6 @@ host_network: true
 image: "ghcr.io/homeassistant-ai/ha-mcp-addon-dev-{arch}"
 options:
   backup_hint: "normal"
-  enable_skills: true
-  enable_skills_as_tools: true
   enable_tool_search: false
   enable_yaml_config_editing: false
   tool_search_max_results: 5
@@ -31,8 +29,6 @@ options:
 schema:
   backup_hint: list(strong|normal|weak|auto)
   secret_path: str?
-  enable_skills: bool?
-  enable_skills_as_tools: bool?
   enable_tool_search: bool?
   enable_yaml_config_editing: bool?
   enable_filesystem_tools: bool?

homeassistant-addon-dev/translations/en.yaml

@@ -7,17 +7,6 @@ configuration:
     name: Secret path override
     description: |
       Optional custom HTTP path for the MCP server. Leave empty to use the auto-generated secure path.
-  enable_skills:
-    name: Enable skills
-    description: >-
-      Serve bundled Home Assistant best-practice skills as MCP resources.
-      Skills provide automation patterns, helper selection guides, and device
-      control best practices. Clients must explicitly request them.
-  enable_skills_as_tools:
-    name: Enable skills as tools
-    description: >-
-      Expose skills via list_resources/read_resource tools for MCP clients
-      that don't support resources natively. Adds 3 extra tools.
   enable_tool_search:
     name: Enable tool search
     description: >-

homeassistant-addon/config.yaml

@@ -27,15 +27,11 @@ image: "ghcr.io/homeassistant-ai/ha-mcp-addon-{arch}"
 # from homeassistant-addon-dev/config.yaml without reading that doc first.
 options:
   backup_hint: "normal"
-  enable_skills: true
-  enable_skills_as_tools: true
   enable_tool_search: false
   verify_ssl: true
 schema:
   backup_hint: list(strong|normal|weak|auto)
   secret_path: str?
-  enable_skills: bool?
-  enable_skills_as_tools: bool?
   enable_tool_search: bool?
   verify_ssl: bool?
   advanced_debug_logging: bool?

homeassistant-addon/start.py

@@ -179,86 +179,6 @@ def resolve_bool_option(config: dict[str, Any], key: str, default: bool) -> bool
     return raw if isinstance(raw, bool) else default
 
 
-SKILLS_AS_TOOLS_MIGRATION_MARKER = ".skills_as_tools_default_migration_v1"
-
-
-def migrate_skills_as_tools_default(
-    data_dir: Path,
-    config_file: Path,
-    stored_value: bool,
-    config_read_ok: bool,
-) -> bool:
-    """One-time migration to force enable_skills_as_tools=true for existing users.
-
-    The Pydantic default in src/ha_mcp/config.py was flipped to True in
-    #806, but the add-on's config.yaml was never updated at the same time.
-    For add-on installs the env var is written from options.json before
-    ha-mcp reads its Pydantic settings, so the new Python default never
-    took effect for existing users. This runs exactly once per install
-    (guarded by a marker file in /data) and forces the flag on for users
-    who still have False stored, then persists the new value to
-    options.json so the supervisor UI reflects it. On subsequent boots the
-    marker is present and the stored value is respected, so users who
-    deliberately toggle it off will not be re-forced.
-
-    config_read_ok must be False when the caller could not load
-    options.json (file unreadable or malformed JSON). In that case the
-    marker is not created, so the migration can run again on a later
-    boot once options.json is readable and expose the user's real
-    stored value.
-    """
-    marker = data_dir / SKILLS_AS_TOOLS_MIGRATION_MARKER
-    if marker.exists():
-        return stored_value
-
-    # First run after this update. Force-on + persist only if the user is
-    # currently on False, then create the marker so the migration does
-    # not loop — but skip marker creation when the caller could not
-    # verify the stored value (see config_read_ok in the docstring).
-    if not stored_value:
-        log_info(
-            "One-time migration: forcing enable_skills_as_tools=true. "
-            "The Pydantic default was set to True in #806 but the add-on's "
-            "config.yaml was not updated alongside it, so this value stayed "
-            "False for existing add-on installs. Future user-initiated "
-            "changes to this setting will be respected."
-        )
-        if config_file.exists():
-            try:
-                with open(config_file, encoding="utf-8") as f:
-                    opts = json.load(f)
-                if isinstance(opts, dict):
-                    opts["enable_skills_as_tools"] = True
-                    with open(config_file, "w", encoding="utf-8") as f:
-                        json.dump(opts, f, indent=2)
-                        f.write("\n")
-                    log_info("Persisted enable_skills_as_tools=true to options.json")
-                else:
-                    log_error(
-                        "Cannot persist migration to options.json: top-level "
-                        f"is {type(opts).__name__}, expected dict. Runtime "
-                        "override still applied for this session."
-                    )
-            except (OSError, json.JSONDecodeError) as e:
-                log_error(
-                    f"Failed to persist migration to options.json "
-                    f"(operation: persist_skills_as_tools_migration): {e}. "
-                    "Runtime override still applied for this session."
-                )
-        stored_value = True
-
-    if config_read_ok:
-        try:
-            marker.touch()
-        except OSError as e:
-            log_error(
-                f"Failed to create migration marker "
-                f"(operation: create_skills_as_tools_marker): {e}"
-            )
-
-    return stored_value
-
-
 def main() -> int:
     """Start the Home Assistant MCP Server."""
     log_info("Starting Home Assistant MCP Server...")
@@ -269,8 +189,6 @@ def main() -> int:
     config: dict[str, Any] = {}
     backup_hint = "normal"  # default
     custom_secret_path = ""  # default
-    enable_skills = True  # default
-    enable_skills_as_tools = True  # default
     enable_tool_search = False  # default
     enable_yaml_config_editing = False  # default
     enable_filesystem_tools = False  # default
@@ -280,18 +198,13 @@ def main() -> int:
     pinned_tools_raw = ""  # default
     verify_ssl = True  # default
     advanced_debug_logging = False  # default
-    config_read_ok = True
 
     if config_file.exists():
         try:
             with open(config_file) as f:
                 config = json.load(f)
             backup_hint = config.get("backup_hint", "normal")
             custom_secret_path = config.get("secret_path", "")
-            raw_skills = config.get("enable_skills", True)
-            enable_skills = raw_skills if isinstance(raw_skills, bool) else True
-            raw_skills_as_tools = config.get("enable_skills_as_tools", True)
-            enable_skills_as_tools = raw_skills_as_tools if isinstance(raw_skills_as_tools, bool) else True
             raw_tool_search = config.get("enable_tool_search", False)
             enable_tool_search = raw_tool_search if isinstance(raw_tool_search, bool) else False
             raw_yaml_config = config.get("enable_yaml_config_editing", False)
@@ -310,16 +223,6 @@ def main() -> int:
             advanced_debug_logging = resolve_bool_option(config, "advanced_debug_logging", False)
         except Exception as e:
             log_error(f"Failed to read config: {e}, using defaults")
-            config_read_ok = False
-
-    # One-time migration: add-on users whose stored value is False predate
-    # this release's config.yaml default flip. See migrate_skills_as_tools_default.
-    enable_skills_as_tools = migrate_skills_as_tools_default(
-        data_dir=data_dir,
-        config_file=config_file,
-        stored_value=enable_skills_as_tools,
-        config_read_ok=config_read_ok,
-    )
 
     # Validate Supervisor token (needed for both ha-mcp auth below and the
     # options-persist call right after secret path resolution)
@@ -344,8 +247,6 @@ def main() -> int:
     # Set up environment for ha-mcp
     os.environ["HOMEASSISTANT_URL"] = "http://supervisor/core"
     os.environ["BACKUP_HINT"] = backup_hint
-    os.environ["ENABLE_SKILLS"] = str(enable_skills).lower()
-    os.environ["ENABLE_SKILLS_AS_TOOLS"] = str(enable_skills_as_tools).lower()
     os.environ["ENABLE_TOOL_SEARCH"] = str(enable_tool_search).lower()
     os.environ["ENABLE_YAML_CONFIG_EDITING"] = str(enable_yaml_config_editing).lower()
     os.environ["HAMCP_ENABLE_FILESYSTEM_TOOLS"] = str(enable_filesystem_tools).lower()

src/ha_mcp/config.py

@@ -9,7 +9,7 @@
 from pathlib import Path
 
 from dotenv import load_dotenv
-from pydantic import Field, field_validator, model_validator
+from pydantic import Field, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 from ha_mcp._version import get_version
@@ -92,17 +92,6 @@ class Settings(BaseSettings):
         True, alias="ENABLE_DASHBOARD_PARTIAL_TOOLS"
     )
 
-    # Skills configuration
-    # Serve bundled HA best-practice skills as MCP resources (skill:// URIs).
-    # Resources are not auto-injected — clients must explicitly request them.
-    enable_skills: bool = Field(True, alias="ENABLE_SKILLS")
-
-    # Expose skills and doc resources as tools (list_resources/read_resource)
-    # for clients that don't support MCP resources natively.
-    # Defaults to True so all clients can access documentation and skills.
-    # Resource-capable clients can set to False to reduce tool count.
-    enable_skills_as_tools: bool = Field(True, alias="ENABLE_SKILLS_AS_TOOLS")
-
     # Tool search transform — replaces the full tool catalog with a unified
     # BM25 search tool and categorized call proxies (read/write/delete).
     # Dramatically reduces idle context token usage for LLMs.
@@ -124,18 +113,6 @@ class Settings(BaseSettings):
     # supervisor UI rejects out-of-range values before they reach env vars.
     tool_search_max_results: int = Field(5, ge=2, le=10, alias="TOOL_SEARCH_MAX_RESULTS")
 
-    @model_validator(mode="after")
-    def _skills_dependency(self) -> "Settings":
-        """Auto-enable skills (resources) when skills-as-tools is on.
-
-        skills_as_tools wraps ResourcesAsTools which requires skills to be
-        registered as MCP resources first. Without this, enabling
-        skills_as_tools alone would produce empty list_resources results.
-        """
-        if self.enable_skills_as_tools and not self.enable_skills:
-            self.enable_skills = True
-        return self
-
     @property
     def env_file_name(self) -> str:
         """Get the current environment file name."""