feat: update AI agent skills as part of poly update

poly update now refreshes the installed skills after the CLI (also when
the CLI is already current). --cli-only and --skills-only narrow it to
one half; --skills-only works on editable installs, where the CLI half
is refused. Skill failures in a combined update warn without failing
the command; in --json mode npx output is captured so stdout stays a
single object.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: Ruari-Phipps

src/poly/cli_commands/skills.py

@@ -53,17 +53,22 @@ def node_gate_reason() -> str | None:
     return None
 
 
-def _run_npx_skills(args: list[str]) -> bool:
+def _run_npx_skills(args: list[str], quiet: bool = False) -> bool:
     """Run ``npx -y skills@<pin> <args>``, streaming output to the terminal.
 
+    Args:
+        args: Arguments for the skills CLI, e.g. ``["update", "-y"]``.
+        quiet: Capture output instead of streaming it — for callers whose own
+            stdout must stay machine-readable (``--json``).
+
     Returns:
         True if the command exited 0. Never raises — failures here must not
         abort the caller's remaining steps.
     """
     command = ["npx", "-y", SKILLS_NPX_PACKAGE, *args]
     logger.debug("Running: %s", " ".join(command))
     try:
-        result = subprocess.run(command, timeout=NPX_TIMEOUT_SECONDS)
+        result = subprocess.run(command, timeout=NPX_TIMEOUT_SECONDS, capture_output=quiet)
     except Exception as e:
         logger.debug("npx skills invocation failed: %s", e)
         return False
@@ -94,13 +99,17 @@ def install_skills(
     return _run_npx_skills(args)
 
 
-def update_skills(global_only: bool = False) -> bool:
+def update_skills(global_only: bool = False, quiet: bool = False) -> bool:
     """Update previously installed skills to their latest versions.
 
+    Args:
+        global_only: Update only user-level skills, not the current project's.
+        quiet: Capture npx output instead of streaming it (for ``--json``).
+
     Returns:
         True on success, False otherwise (never raises).
     """
     args = ["update", "-y"]
     if global_only:
         args.append("--global")
-    return _run_npx_skills(args)
+    return _run_npx_skills(args, quiet=quiet)

src/poly/cli_commands/update.py

@@ -23,6 +23,7 @@
     get_package_version,
     is_newer_version,
 )
+from poly.cli_commands.skills import node_gate_reason, update_skills
 from poly.constants import POLY_HOME_DIR
 from poly.output.json_output import json_print
 
@@ -68,13 +69,15 @@ def add_arguments(cls, subparsers: _SubParsersAction[ArgumentParser], parents: P
             "update",
             parents=[parents.verbose, parents.debug, parents.json],
             formatter_class=RawTextHelpFormatter,
-            help="Update the Poly CLI to the latest version.",
+            help="Update the Poly CLI and its AI agent skills to the latest version.",
             description=(
-                "Update the Poly CLI to the latest version.\n\n"
+                "Update the Poly CLI and its AI agent skills to the latest version.\n\n"
                 "Examples:\n"
                 "  poly update\n"
                 "  poly update --check\n"
                 "  poly update --to 0.52.0\n"
+                "  poly update --cli-only\n"
+                "  poly update --skills-only\n"
                 "\n"
                 "The CLI also notices new releases on its own, at most once every 12\n"
                 "hours. Set POLY_NO_UPDATE_CHECK=1 to silence that; it is already\n"
@@ -96,16 +99,58 @@ def add_arguments(cls, subparsers: _SubParsersAction[ArgumentParser], parents: P
             help="Install a specific version instead of the latest, e.g. --to 0.52.0.",
         )
 
+        scope_group = update_parser.add_mutually_exclusive_group()
+        scope_group.add_argument(
+            "--cli-only",
+            action="store_true",
+            help="Update the CLI only, skipping the AI agent skills.",
+        )
+        scope_group.add_argument(
+            "--skills-only",
+            action="store_true",
+            help="Update the AI agent skills only, skipping the CLI.",
+        )
+
     @classmethod
     def run(cls, args: Namespace) -> None:
         """Run the update command."""
-        cls.update(args.check, args.json, args.to)
+        cls.update(
+            args.check,
+            args.json,
+            args.to,
+            cli_only=args.cli_only,
+            skills_only=args.skills_only,
+        )
 
     @classmethod
-    def update(cls, check: bool, output_json: bool, target_version: str | None = None) -> None:
-        """Update the Poly CLI to the latest version, or to ``target_version`` if given."""
+    def update(
+        cls,
+        check: bool,
+        output_json: bool,
+        target_version: str | None = None,
+        cli_only: bool = False,
+        skills_only: bool = False,
+    ) -> None:
+        """Update the Poly CLI (and its AI agent skills) to the latest version.
+
+        With ``target_version``, install that CLI version instead of the latest.
+        ``cli_only`` and ``skills_only`` narrow the update to one half; the
+        skills half never applies to ``--check``, which is a CLI version check.
+        """
         from poly.output.console import info, success
 
+        if skills_only:
+            # Deliberately not gated on refuse_if_not_upgradable: an editable/dev
+            # install cannot upgrade the CLI in place, but its skills still can be.
+            updated = cls.update_skills_step(output_json, required=True)
+            if output_json:
+                json_print({"success": updated, "skills_updated": updated})
+            elif updated:
+                success("AI agent skills updated.")
+            if not updated:
+                sys.exit(1)
+            return
+
         # Refuse before hitting the network or announcing anything, so an install we
         # cannot upgrade is not told that an update is on the way.
         if cls.refuse_if_not_upgradable(output_json):
@@ -122,8 +167,16 @@ def update(cls, check: bool, output_json: bool, target_version: str | None = Non
         else:
             update_available, target = cls.check_for_updates()
             if not update_available:
+                # The CLI is current, but the skills may not be — the default
+                # update still refreshes them.
+                skills_updated = None
+                if not check and not cli_only:
+                    skills_updated = cls.update_skills_step(output_json, required=False)
                 if output_json:
-                    json_print({"update_available": False, "latest_version": target})
+                    result = {"update_available": False, "latest_version": target}
+                    if skills_updated is not None:
+                        result["skills_updated"] = skills_updated
+                    json_print(result)
                 else:
                     info("Poly CLI is already up to date, no update needed.")
                     info(f"Current version: {get_package_version()}")
@@ -140,11 +193,56 @@ def update(cls, check: bool, output_json: bool, target_version: str | None = Non
             info(f"Updating Poly CLI to version {target}...")
         if not cls.perform_update(output_json, target_version):
             return
+        skills_updated = None
+        if not cli_only:
+            skills_updated = cls.update_skills_step(output_json, required=False)
         if output_json:
-            json_print({"success": True, "latest_version": target})
+            result = {"success": True, "latest_version": target}
+            if skills_updated is not None:
+                result["skills_updated"] = skills_updated
+            json_print(result)
         else:
             success(f"Poly CLI updated to version {target}.")
 
+    @classmethod
+    def update_skills_step(cls, output_json: bool, required: bool) -> bool:
+        """Update installed AI agent skills via the pinned ``npx skills`` package.
+
+        Args:
+            output_json: Keep stdout machine-readable — npx output is captured
+                and no console messages are printed.
+            required: The skills are the whole point of the invocation
+                (``--skills-only``): report failure as an error instead of a
+                warning. Never exits — the caller owns the exit code.
+
+        Returns:
+            True if the skills were updated.
+        """
+        from poly.output.console import error, info, warning
+
+        gate_reason = node_gate_reason()
+        if gate_reason:
+            message = f"Cannot update AI agent skills: {gate_reason}."
+            if output_json:
+                # The caller folds the failure into its own JSON output.
+                logger.debug(message)
+            elif required:
+                error(message)
+            else:
+                warning(f"{message} Skipping.")
+            return False
+
+        if not output_json:
+            info("Updating AI agent skills...")
+        updated = update_skills(quiet=output_json)
+        if not updated and not output_json:
+            message = "AI agent skill update failed."
+            if required:
+                error(message)
+            else:
+                warning(f"{message} Run 'poly update --skills-only' to retry.")
+        return updated
+
     @staticmethod
     def check_for_updates() -> tuple[bool, str]:
         """Check whether a newer Poly CLI release is available on PyPI.

src/poly/tests/cli_test.py

@@ -5223,6 +5223,7 @@ def setUp(self):
         self.check_for_updates = self._patch_command("check_for_updates", (True, "0.54.0"))
         self.check_version_exists = self._patch_command("check_version_exists", True)
         self.perform_update = self._patch_command("perform_update", True)
+        self.update_skills_step = self._patch_command("update_skills_step", True)
         for console_function in ("info", "success"):
             patcher = patch(f"poly.output.console.{console_function}")
             patcher.start()
@@ -5287,6 +5288,69 @@ def test_update_available_installs_latest_with_no_pinned_version(self):
 
         self.perform_update.assert_called_once_with(False, None)
 
+    def test_default_update_also_updates_the_skills(self):
+        """A plain 'poly update' refreshes the AI agent skills after the CLI."""
+        UpdateCommand.update(check=False, output_json=False)
+
+        self.perform_update.assert_called_once()
+        self.update_skills_step.assert_called_once_with(False, required=False)
+
+    def test_cli_only_skips_the_skills(self):
+        """'poly update --cli-only' updates the CLI without touching the skills."""
+        UpdateCommand.update(check=False, output_json=False, cli_only=True)
+
+        self.perform_update.assert_called_once()
+        self.update_skills_step.assert_not_called()
+
+    def test_check_does_not_touch_the_skills(self):
+        """'--check' is a CLI version check; the skills are left alone."""
+        UpdateCommand.update(check=True, output_json=False)
+
+        self.update_skills_step.assert_not_called()
+
+    def test_up_to_date_cli_still_updates_the_skills(self):
+        """Being on the latest CLI version still refreshes the skills."""
+        self.check_for_updates.return_value = (False, "0.53.0")
+
+        UpdateCommand.update(check=False, output_json=False)
+
+        self.perform_update.assert_not_called()
+        self.update_skills_step.assert_called_once_with(False, required=False)
+
+    def test_skills_only_updates_skills_and_nothing_else(self):
+        """'--skills-only' skips the CLI paths entirely, including the upgradable gate."""
+        UpdateCommand.update(check=False, output_json=False, skills_only=True)
+
+        self.refuse_if_not_upgradable.assert_not_called()
+        self.check_for_updates.assert_not_called()
+        self.perform_update.assert_not_called()
+        self.update_skills_step.assert_called_once_with(False, required=True)
+
+    def test_skills_only_failure_exits_non_zero(self):
+        """A failed '--skills-only' run is the whole command failing."""
+        self.update_skills_step.return_value = False
+
+        with self.assertRaises(SystemExit) as raised:
+            UpdateCommand.update(check=False, output_json=False, skills_only=True)
+
+        self.assertEqual(raised.exception.code, 1)
+
+    def test_skills_failure_does_not_fail_a_combined_update(self):
+        """In a default update the skills half is best-effort — no exit, CLI result stands."""
+        self.update_skills_step.return_value = False
+
+        UpdateCommand.update(check=False, output_json=False)
+
+        self.perform_update.assert_called_once()
+
+    def test_cli_only_and_skills_only_are_mutually_exclusive(self):
+        """The parser rejects '--cli-only --skills-only' as contradictory."""
+        cli = AgentStudioCLI()
+        cli.register_commands()
+
+        with self.assertRaises(SystemExit):
+            cli._create_parser().parse_args(["update", "--cli-only", "--skills-only"])
+
     def test_not_upgradable_install_is_refused_before_any_lookup(self):
         """An editable or ephemeral install refuses without consulting PyPI first."""
         self.refuse_if_not_upgradable.return_value = True
@@ -5381,6 +5445,49 @@ def isatty(self) -> bool:
         return self.is_a_tty
 
 
+class UpdateSkillsStepTest(unittest.TestCase):
+    """Tests for UpdateCommand.update_skills_step, the npx-backed skills half."""
+
+    def setUp(self):
+        """Stub the Node gate and the npx runner, and silence console output."""
+        self.node_gate = patch("poly.cli_commands.update.node_gate_reason", return_value=None)
+        self.mock_gate = self.node_gate.start()
+        self.addCleanup(self.node_gate.stop)
+        self.skills_update = patch("poly.cli_commands.update.update_skills", return_value=True)
+        self.mock_update = self.skills_update.start()
+        self.addCleanup(self.skills_update.stop)
+        for console_function in ("info", "error", "warning"):
+            patcher = patch(f"poly.output.console.{console_function}")
+            patcher.start()
+            self.addCleanup(patcher.stop)
+
+    def test_missing_node_skips_without_running_npx(self):
+        """A gated environment reports failure without attempting the update."""
+        self.mock_gate.return_value = "Node.js (with npx) was not found on your PATH"
+
+        self.assertFalse(UpdateCommand.update_skills_step(output_json=False, required=False))
+        self.mock_update.assert_not_called()
+
+    def test_json_mode_runs_npx_quietly(self):
+        """--json output stays a single object: npx output is captured, not streamed."""
+        updated = UpdateCommand.update_skills_step(output_json=True, required=False)
+
+        self.assertTrue(updated)
+        self.mock_update.assert_called_once_with(quiet=True)
+
+    def test_interactive_mode_streams_npx_output(self):
+        """Without --json the npx output is streamed for the user to follow."""
+        UpdateCommand.update_skills_step(output_json=False, required=False)
+
+        self.mock_update.assert_called_once_with(quiet=False)
+
+    def test_failure_returns_false_without_exiting(self):
+        """The step never exits — the caller owns the exit code."""
+        self.mock_update.return_value = False
+
+        self.assertFalse(UpdateCommand.update_skills_step(output_json=False, required=True))
+
+
 class StartupUpdateMessageTest(unittest.TestCase):
     """Tests for display_update_message, the passive check run at the start of every command."""