google-agents-cli 1.10.0__tar.gz → 1.12.0__tar.gz

{google_agents_cli-1.10.0 → google_agents_cli-1.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-agents-cli
-Version: 1.10.0
+Version: 1.12.0
 Summary: Agents CLI — Agent Development Lifecycle toolchain for ADK
 Author-email: Google LLC <agents-cli-dev-pypi@google.com>
 Requires-Python: >=3.11
@@ -117,7 +117,7 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 | Command | What it does |
 |---------|-------------|
 | `agents-cli setup` | Install CLI + skills to coding agents |
-| `agents-cli create <name>` | Create a new agent project |
+| `agents-cli create <name> -y` | Create a new agent project with defaults (`adk_python` template, `agent_runtime` target) |
 | `agents-cli eval run` | Run the agent over the eval dataset and grade the traces |
 | `agents-cli deploy` | Deploy to Google Cloud |
 | `agents-cli publish gemini` | Register with Gemini |
@@ -130,7 +130,7 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 | `agents-cli login` | Authenticate with Google Cloud or AI Studio |
 | `agents-cli login --status` | Show authentication status |
 | **Scaffold** | |
-| `agents-cli create <name>` | Create a new agent project |
+| `agents-cli create <name> -y` | Create a new agent project with defaults (`adk_python` template, `agent_runtime` target) |
 | `agents-cli scaffold enhance` | Add deployment or CI/CD to an existing project |
 | `agents-cli scaffold upgrade` | Upgrade project to a newer agents-cli version |
 | **Develop** | |

{google_agents_cli-1.10.0 → google_agents_cli-1.12.0}/README.md

@@ -76,7 +76,7 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 | Command | What it does |
 |---------|-------------|
 | `agents-cli setup` | Install CLI + skills to coding agents |
-| `agents-cli create <name>` | Create a new agent project |
+| `agents-cli create <name> -y` | Create a new agent project with defaults (`adk_python` template, `agent_runtime` target) |
 | `agents-cli eval run` | Run the agent over the eval dataset and grade the traces |
 | `agents-cli deploy` | Deploy to Google Cloud |
 | `agents-cli publish gemini` | Register with Gemini |
@@ -89,7 +89,7 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 | `agents-cli login` | Authenticate with Google Cloud or AI Studio |
 | `agents-cli login --status` | Show authentication status |
 | **Scaffold** | |
-| `agents-cli create <name>` | Create a new agent project |
+| `agents-cli create <name> -y` | Create a new agent project with defaults (`adk_python` template, `agent_runtime` target) |
 | `agents-cli scaffold enhance` | Add deployment or CI/CD to an existing project |
 | `agents-cli scaffold upgrade` | Upgrade project to a newer agents-cli version |
 | **Develop** | |

{google_agents_cli-1.10.0 → google_agents_cli-1.12.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "google-agents-cli"
-version = "1.10.0"
+version = "1.12.0"
 description = "Agents CLI — Agent Development Lifecycle toolchain for ADK"
 readme = "README.md"
 license = "Apache-2.0"

{google_agents_cli-1.10.0 → google_agents_cli-1.12.0}/src/google/agents/cli/_experiments.py

@@ -28,6 +28,10 @@ class Experiment(NamedTuple):
 _REGISTRY: dict[str, Experiment] = {
     # Hides the `build` command until Go (compiled-language) support launches.
     "build_command": Experiment("build_command", bool, True),
+    # Gate in-progress ADK language support until each language launches.
+    "adk_java": Experiment("adk_java", bool, False),
+    "adk_kotlin": Experiment("adk_kotlin", bool, False),
+    "adk_typescript": Experiment("adk_typescript", bool, False),
 }
 
 

google_agents_cli-1.12.0/src/google/agents/cli/_git.py

@@ -0,0 +1,41 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Checks for values passed to git as arguments.
+
+A value read from a project file or typed by the user can reach git as an
+option (e.g. ``--upload-pack=<cmd>``, which runs a command). Callers check
+values with these before building a git command, and also put ``--`` before
+positional arguments where the git subcommand accepts it.
+"""
+
+import re
+
+# Only a full 40-char SHA is unambiguous. A short/partial hex string could
+# instead be a branch or tag named like hex (e.g. "cafe123").
+_COMMIT_SHA_RE = re.compile(r"[0-9a-f]{40}")
+
+
+def is_commit_sha(value: str) -> bool:
+    """True for a full 40-char lowercase hex commit SHA."""
+    # fullmatch, not match with "$": "$" also matches before a trailing newline.
+    return bool(_COMMIT_SHA_RE.fullmatch(value))
+
+
+def is_option_like(value: str) -> bool:
+    """True when git would read ``value`` as an option rather than an operand.
+
+    No valid git ref name starts with "-".
+    """
+    return value.startswith("-")

google_agents_cli-1.12.0/src/google/agents/cli/_output.py

@@ -0,0 +1,167 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Output helpers for agents CLI."""
+
+import json
+import logging
+import sys
+from typing import Any
+
+import click
+from rich.console import Console as _RichConsole  # noqa: TID251
+from rich.markup import escape
+
+_OWN_LOGGER_NAME = "google.agents.cli"
+_PLAIN_FORMATTER = logging.Formatter()
+
+
+class Console(_RichConsole):
+    """Rich Console configured with project-wide defaults (soft_wrap=True)."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        kwargs.setdefault("soft_wrap", True)
+        super().__init__(*args, **kwargs)
+
+
+def emit(data: dict) -> None:
+    """Write structured data to stdout."""
+    print(json.dumps(data), file=sys.stdout)
+
+
+def print_error(message: str) -> None:
+    """Print an error message to stderr with a red "❌ Error:" prefix."""
+    # escape() so text like "[cyan]" or "[0]" in the message is shown as-is.
+    Console(stderr=True, highlight=False).print(
+        f"[bold red]❌ Error:[/bold red] {escape(message)}"
+    )
+
+
+def print_warning(message: str) -> None:
+    """Print a warning message to stderr with a yellow "⚠️  Warning:" prefix."""
+    Console(stderr=True, highlight=False).print(
+        f"[bold yellow]⚠️  Warning:[/bold yellow] {escape(message)}"
+    )
+
+
+INTERACTIVE_FIX = ("-i, --interactive", "be prompted for each missing value")
+
+
+def auto_approve_fix(default: str) -> tuple[str, str]:
+    """The -y entry for programmatic_mode_error; ``default`` names what -y picks."""
+    return ("-y, --yes", f"accept the defaults ({default})")
+
+
+def programmatic_mode_error(
+    requirement: str, *fixes: tuple[str, str]
+) -> click.UsageError:
+    """Build the error for a value a command can't fill in without prompting.
+
+    ``requirement`` is the subject, e.g. "--agent is required"; each fix is a
+    (flag, description) pair, and an empty flag continues the fix above. Every
+    fix gets its own aligned line: a trailing "pass -i for interactive mode"
+    sentence was easy to miss.
+    """
+    if not fixes:
+        return click.UsageError(f"{requirement} in programmatic mode.")
+    width = max(len(flag) for flag, _ in fixes)
+    lines = "\n".join(f"  {flag:<{width}}  {text}" for flag, text in fixes)
+    return click.UsageError(
+        f"{requirement} in programmatic mode. Rerun with one of:\n{lines}"
+    )
+
+
+def print_debug(message: str) -> None:
+    """Print a debug message to stderr as a dim "Debug: <message>" line."""
+    Console(stderr=True, highlight=False).print(f"Debug: {escape(message)}", style="dim")
+
+
+def print_click_exception(e: click.ClickException) -> None:
+    """Show a ClickException like Click does, but with a red "❌ Error:" prefix."""
+    if isinstance(e, click.UsageError) and e.ctx is not None:
+        hint = ""
+        if e.ctx.command.get_help_option(e.ctx) is not None:
+            hint = f"Try '{e.ctx.command_path} {e.ctx.help_option_names[0]}' for help.\n"
+        click.echo(f"{e.ctx.get_usage()}\n{hint}", err=True, color=e.ctx.color)
+    print_error(e.format_message())
+
+
+def configure_logging(level: int = logging.INFO) -> None:
+    """Send log records to stderr, formatting agents-cli's own records.
+
+    agents-cli's own records are shown from ``level`` up. Records from libraries
+    are shown from WARNING up (or from ``level``, if it is higher), except at
+    DEBUG, where they are shown too. agents-cli's own errors, warnings and debug
+    records get the print_error() / print_warning() / print_debug() format;
+    everything else is printed plain.
+    """
+    root = logging.getLogger()
+    for handler in [h for h in root.handlers if isinstance(h, _CliLogHandler)]:
+        root.removeHandler(handler)
+
+    debug = level <= logging.DEBUG
+    library_level = level if debug else max(level, logging.WARNING)
+    handler = _CliLogHandler()
+    handler.setFormatter(
+        logging.Formatter(logging.BASIC_FORMAT if debug else "%(message)s")
+    )
+    handler.addFilter(lambda r: _is_own_record(r) or r.levelno >= library_level)
+    root.addHandler(handler)
+    root.setLevel(level)
+    # On its first request, google-auth turns off propagation on the "google"
+    # logger unless that logger is already configured
+    # (google.auth._helpers.is_logging_enabled). That would cut every google.*
+    # logger, ours included, off from the handler above. A level counts as
+    # configured. At DEBUG, google-auth then logs its requests; their headers
+    # (with tokens) go in the record's extra fields, which this format doesn't
+    # print.
+    logging.getLogger("google").setLevel(level)
+
+
+class _CliLogHandler(logging.Handler):
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            printer = _OWN_RECORD_PRINTERS.get(record.levelno)
+            if printer and _is_own_record(record):
+                printer(_PLAIN_FORMATTER.format(record))
+            else:
+                # click.echo looks up sys.stderr on every call, so output still
+                # reaches a stream swapped in later (e.g. by CliRunner).
+                click.echo(self.format(record), err=True)
+        except Exception:
+            self.handleError(record)
+
+
+def _is_own_record(record: logging.LogRecord) -> bool:
+    # agents-cli code mostly calls logging.warning() etc. directly, which logs
+    # on the root logger.
+    return (
+        record.name == "root"
+        or record.name == _OWN_LOGGER_NAME
+        or record.name.startswith(_OWN_LOGGER_NAME + ".")
+    )
+
+
+def _print_plain(message: str) -> None:
+    # Our INFO lines stay plain, without the debug-mode "INFO:root:" prefix.
+    click.echo(message, err=True)
+
+
+_OWN_RECORD_PRINTERS = {
+    logging.CRITICAL: print_error,
+    logging.ERROR: print_error,
+    logging.WARNING: print_warning,
+    logging.INFO: _print_plain,
+    logging.DEBUG: print_debug,
+}

{google_agents_cli-1.10.0 → google_agents_cli-1.12.0}/src/google/agents/cli/_project.py

@@ -22,7 +22,7 @@ import re
 import tomllib
 from collections.abc import Mapping
 from dataclasses import dataclass
-from pathlib import Path
+from pathlib import Path, PurePosixPath
 from typing import Any
 
 import click
@@ -32,6 +32,9 @@ import yaml
 # ADK; new projects get the value from their template.
 DEFAULT_FRAMEWORK = "google-adk"
 
+# Base template used when a project does not name one. `adk` is an alias for it.
+DEFAULT_BASE_TEMPLATE = "adk_python"
+
 # Values of create_params.agent_runtime.identity_default.
 AGENT_IDENTITY = "agent_identity"
 SERVICE_ACCOUNT = "service_account"
@@ -43,6 +46,23 @@ NESTED_CREATE_PARAMS = {
     "agent_runtime_identity_default": ("agent_runtime", "identity_default"),
 }
 
+# The create commands shown when a command runs outside a project, indented to
+# sit under a "create a project first:" line.
+CREATE_PROJECT_HINT = (
+    "    agents-cli create my-agent -i    # choose options in prompts\n"
+    "    agents-cli create my-agent -y    # accept the defaults (adk_python template, agent_runtime target)"
+)
+
+
+def agent_package_name(agent_directory: str) -> str:
+    """Return the package name (basename) of ``agent_directory``."""
+    return PurePosixPath(agent_directory).name
+
+
+def agents_root(agent_directory: str) -> str:
+    """Return the parent of ``agent_directory``, ``.`` for a top-level one."""
+    return PurePosixPath(agent_directory).parent.as_posix()
+
 
 @dataclass
 class ProjectConfig:
@@ -53,9 +73,11 @@ class ProjectConfig:
     agent_directory: str = "app"
     is_a2a: bool = False
     region: str = "us-east1"
-    base_template: str = "adk"
+    base_template: str = DEFAULT_BASE_TEMPLATE
     acli_version: str = ""
-    language: str = "python"
+    # The manifest's language as written; None when it has no language key.
+    # Read `language` unless you need to tell "unset" apart from "python".
+    raw_language: str | None = None
     framework: str = DEFAULT_FRAMEWORK
     session_type: str = "none"
     cicd_runner: str = "skip"
@@ -66,6 +88,10 @@ class ProjectConfig:
     # name"; see resolve_root_agent_name.
     root_agent_name: str = ""
 
+    @property
+    def language(self) -> str:
+        return self.raw_language or "python"
+
     @property
     def create_params(self) -> dict[str, Any]:
         return {
@@ -97,7 +123,7 @@ class ProjectConfig:
         cfg.acli_version = (
             data.get("acli_version") or data.get("version") or cfg.acli_version
         )
-        cfg.language = data.get("language", cfg.language)
+        cfg.raw_language = data.get("language")
         cfg.framework = data.get("framework", cfg.framework)
 
         create_params = data.get("create_params")
@@ -146,16 +172,9 @@ def _warn_legacy_config() -> None:
     """Warn about legacy configuration once."""
     global _WARNED_LEGACY_CONFIG
     if not _WARNED_LEGACY_CONFIG:
-        click.secho(
-            "\n⚠️  Legacy configuration detected in pyproject.toml.",
-            fg="yellow",
-            bold=True,
-            err=True,
-        )
-        click.secho(
-            "   Run `agents-cli scaffold upgrade` to migrate to agents-cli-manifest.yaml.\n",
-            fg="yellow",
-            err=True,
+        logging.warning(
+            "Legacy configuration detected in pyproject.toml. Run "
+            "`agents-cli scaffold upgrade` to migrate to agents-cli-manifest.yaml."
         )
         _WARNED_LEGACY_CONFIG = True
 
@@ -257,18 +276,19 @@ def check_cli_version(cfg: ProjectConfig) -> None:
         return
 
     if cli_ver < project_ver:
-        click.echo(
-            f"\n⚠️  Version mismatch: project was scaffolded with agents-cli {acli_version},"
-            f" running {__version__}.\n"
-            f"   Upgrade the CLI: uv tool install google-agents-cli@{acli_version}\n",
-            err=True,
+        logging.warning(
+            "Version mismatch: project was scaffolded with agents-cli %s, running "
+            "%s. Upgrade the CLI: uv tool install google-agents-cli@%s",
+            acli_version,
+            __version__,
+            acli_version,
         )
     elif cli_ver > project_ver:
-        click.echo(
-            f"\n⚠️  Version mismatch: project was scaffolded with agents-cli {acli_version},"
-            f" running {__version__}.\n"
-            "   Upgrade the project: agents-cli scaffold upgrade\n",
-            err=True,
+        logging.warning(
+            "Version mismatch: project was scaffolded with agents-cli %s, running "
+            "%s. Upgrade the project: agents-cli scaffold upgrade",
+            acli_version,
+            __version__,
         )
 
 
@@ -351,7 +371,7 @@ def chdir_project_root(dir: Path | None = None) -> None:
         raise click.ClickException(
             "No agents-cli-manifest.yaml found in the current directory or its parents.\n"
             "  Run this command from your project root, or create a project first:\n"
-            "    agents-cli create my-agent"
+            f"{CREATE_PROJECT_HINT}"
         )
     # Only announce the root when we actually move (i.e. run from a subdir).
     if root.resolve() != Path.cwd().resolve():

{google_agents_cli-1.10.0 → google_agents_cli-1.12.0}/src/google/agents/cli/_remote.py

@@ -20,6 +20,8 @@ how a ``--url`` is classified and what auth token it gets.
 
 from __future__ import annotations
 
+import ipaddress
+import logging
 import re
 from typing import NamedTuple
 from urllib.parse import urlparse, urlsplit, urlunsplit
@@ -155,12 +157,13 @@ def build_remote_headers(
 
     Uses an **access token** for Gemini platform / Agent Runtime URLs and an
     **identity token** (with the service URL as audience) for everything
-    else (Cloud Run, GKE, etc.).
+    else (Cloud Run, GKE, etc.). Loopback URLs (the local dev server) get
+    no token.
     """
     headers: dict[str, str] = {"Content-Type": "application/json"}
     parsed = dict(_parse_header(h) for h in custom_headers)
 
-    if "Authorization" not in parsed:
+    if "Authorization" not in parsed and not _is_loopback_url(url):
         try:
             if is_agent_runtime_url(url):
                 token = get_access_token()
@@ -170,10 +173,20 @@ def build_remote_headers(
                 token = get_id_token(audience)
             headers["Authorization"] = f"Bearer {token}"
         except Exception as exc:
-            click.echo(
-                f"Warning: Could not obtain credentials: {exc}",
-                err=True,
-            )
+            logging.warning("Could not obtain credentials: %s", exc)
 
     headers.update(parsed)
     return headers
+
+
+def _is_loopback_url(url: str) -> bool:
+    host = urlparse(url).hostname or ""
+    # *.localhost always resolves to loopback (RFC 6761).
+    if host == "localhost" or host.endswith(".localhost"):
+        return True
+    try:
+        ip = ipaddress.ip_address(host)
+    except ValueError:
+        return False
+    # 0.0.0.0 / :: is what local servers print as their bind address.
+    return ip.is_loopback or ip.is_unspecified

{google_agents_cli-1.10.0 → google_agents_cli-1.12.0}/src/google/agents/cli/_skills_check.py

@@ -18,10 +18,10 @@ from __future__ import annotations
 
 import logging
 import os
+import subprocess
 import time
 from pathlib import Path
 
-import click
 import yaml
 
 # Pin the skills npm package to avoid executing an unverified version.
@@ -61,16 +61,70 @@ def _parse_skill_version(skill_md: Path) -> str | None:
     return str(version) if version else None
 
 
-def _find_installed_skills() -> dict[str, str]:
+def list_skills_all_scopes() -> list[dict]:
+    """Return ``npx skills list --json`` entries for project and global scope.
+
+    ``skills list`` without ``-g`` only reports project-scoped skills and
+    ``-g`` only reports global ones, so both are queried and merged. Entries
+    that share a path are reported once: run from the home directory, the
+    project store (``~/.agents/skills``) is also the global store.
+
+    Raises ``subprocess.CalledProcessError`` if the project query exits
+    non-zero, or ``ValueError`` if its output is not a JSON list. If only the
+    global query fails, the project entries are returned and a warning is
+    logged.
+    """
+    import json
+
+    from google.agents.cli._runner import run_resolved
+
+    entries: list[dict] = []
+    seen_paths: set[str] = set()
+    # Sequential on purpose: concurrent `npx -y` runs race on the shared npm
+    # cache when the package isn't downloaded yet.
+    for scope_args in ([], ["-g"]):
+        cmd = ["npx", "-y", SKILLS_NPX_PACKAGE, "list", *scope_args, "--json"]
+        try:
+            proc = run_resolved(
+                cmd,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=15,
+            )
+            proc.check_returncode()
+            data = json.loads(proc.stdout)
+            if not isinstance(data, list):
+                raise ValueError(f"expected a JSON list, got {type(data).__name__}")
+        except (subprocess.SubprocessError, ValueError) as e:
+            if not scope_args:
+                raise
+            logging.warning(
+                "Could not list global skills; using project skills only: %s", e
+            )
+            continue
+        for entry in data:
+            path = entry.get("path") if isinstance(entry, dict) else None
+            if path in seen_paths:
+                continue
+            if path:
+                seen_paths.add(path)
+            entries.append(entry)
+    return entries
+
+
+def _find_installed_skills() -> dict[str, str] | None:
     """Return ``{skill_name: version}`` for every installed agents-cli skill.
 
     Fast path (~8 ms): scan ``~/.agents/skills/google-agents-cli-*/SKILL.md``
-    directly.  Falls back to ``npx skills list --json`` (~400 ms+) if
+    directly.  Falls back to ``npx skills list [-g] --json`` (~800 ms+) if
     the well-known directory is empty or missing, which is more robust
     when skills are installed to a non-default location.
-    """
-    import json
 
+    Returns ``None`` if the npx query fails, so callers can tell "no skills
+    installed" apart from "could not check".
+    """
     result: dict[str, str] = {}
 
     # Fast path: well-known global install location
@@ -88,25 +142,15 @@ def _find_installed_skills() -> dict[str, str]:
 
     # Slow path: ask npx skills for actual install locations
     try:
-        from google.agents.cli._runner import run_resolved
-
-        proc = run_resolved(
-            ["npx", "-y", SKILLS_NPX_PACKAGE, "list", "--json"],
-            capture_output=True,
-            text=True,
-            encoding="utf-8",
-            errors="replace",
-            timeout=15,
-        )
-        if proc.returncode != 0:
-            return {}
-        entries = json.loads(proc.stdout)
+        entries = list_skills_all_scopes()
+    except subprocess.CalledProcessError:
+        return None
     except Exception as e:
         # Broad by design: this freshness check runs on every CLI invocation and
-        # must never abort a user's command, so any failure degrades to "no skills
-        # found" rather than propagating.
+        # must never abort a user's command, so any failure degrades to "could
+        # not check" rather than propagating.
         logging.warning("Could not query installed skills via npx: %s", e)
-        return {}
+        return None
 
     for entry in entries:
         if not isinstance(entry, dict):
@@ -132,31 +176,50 @@ def get_installed_skills() -> list[dict] | None:
 
     Returns None if the query fails.
     """
-    import json
-
     try:
-        from google.agents.cli._runner import run_resolved
-
-        result = run_resolved(
-            ["npx", "-y", SKILLS_NPX_PACKAGE, "list", "--json"],
-            capture_output=True,
-            text=True,
-            timeout=15,
-        )
-        if result.returncode != 0:
-            logging.warning(
-                "npx skills list failed (exit %d): %s",
-                result.returncode,
-                result.stderr.strip(),
-            )
-            return None
-        skills = json.loads(result.stdout)
+        skills = list_skills_all_scopes()
         return [s for s in skills if s.get("name", "").startswith("google-agents-cli-")]
+    except subprocess.CalledProcessError as e:
+        logging.warning(
+            "npx skills list failed (exit %d): %s",
+            e.returncode,
+            (e.stderr or "").strip(),
+        )
+        return None
     except Exception as e:
         logging.warning("Could not query installed skills: %s", e)
         return None
 
 
+def find_parent_workspace_skills(start: Path) -> Path | None:
+    """Return the nearest parent of ``start`` with workspace-scope agents-cli skills.
+
+    ``agents-cli setup --workspace`` installs skills relative to the directory it
+    ran in, and coding agents started in a subdirectory (e.g. a project created
+    there) may not load them. Returns ``None`` when ``start`` has its own
+    workspace skills or no parent has any. The home directory is skipped because
+    ``~/.agents/skills`` is the global store, which agents load from anywhere.
+    """
+    start = start.resolve()
+    if _has_workspace_skills(start):
+        return None
+    home = Path.home().resolve()
+    for parent in start.parents:
+        if parent != home and _has_workspace_skills(parent):
+            return parent
+    return None
+
+
+def _has_workspace_skills(directory: Path) -> bool:
+    skills_dir = directory / ".agents" / "skills"
+    try:
+        return any(
+            (d / "SKILL.md").is_file() for d in skills_dir.glob("google-agents-cli-*")
+        )
+    except OSError:
+        return False
+
+
 def _is_ci() -> bool:
     """Return True when running in a CI/automation environment.
 
@@ -202,22 +265,25 @@ def check_skills_version() -> None:
         return
 
     installed = _find_installed_skills()
+    if installed is None:
+        # The query failed: don't record the stamp, so the next command retries.
+        return
+
+    _record_skills_check()
     if not installed:
         return
 
     from google.agents.cli import __version__
 
-    _record_skills_check()
-
     mismatched = {name: ver for name, ver in installed.items() if ver != __version__}
     if not mismatched:
         return
 
     lines = [f"  - {name} (v{ver})" for name, ver in mismatched.items()]
-    click.echo(
-        f"\n⚠️  Skills version mismatch — CLI is v{__version__}, "
-        f"but {len(mismatched)} skill(s) differ:\n"
-        + "\n".join(lines)
-        + "\n   Run 'agents-cli update' to sync.\n",
-        err=True,
+    logging.warning(
+        "Skills version mismatch — CLI is v%s, but %d skill(s) differ:\n%s\n"
+        "Run 'agents-cli update' to sync.",
+        __version__,
+        len(mismatched),
+        "\n".join(lines),
     )