refactor: skills accepts 'all' sentinel; [] no longer means everything

API design refinement: skills is now the one place to enable skills
(users should not put 'Skill' in allowed_tools directly).

  None       - skills off (default)
  'all'      - every discovered skill
  [name,...] - named subset only
  []         - degenerate subset; setting_sources still defaults but no
               Skill entries are added (natural list semantics)

Type widened to list[str] | Literal['all'] | None. Transport, query
init, docstring, and tests updated.

Author: jsham042

src/claude_agent_sdk/_internal/query.py

@@ -6,7 +6,7 @@
 import os
 from collections.abc import AsyncIterable, AsyncIterator, Awaitable, Callable
 from contextlib import suppress
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Literal
 
 import anyio
 from mcp.types import (
@@ -77,7 +77,7 @@ def __init__(
         initialize_timeout: float = 60.0,
         agents: dict[str, dict[str, Any]] | None = None,
         exclude_dynamic_sections: bool | None = None,
-        skills: list[str] | None = None,
+        skills: list[str] | Literal["all"] | None = None,
     ):
         """Initialize Query with transport and callbacks.
 

src/claude_agent_sdk/_internal/transport/subprocess_cli.py

@@ -167,11 +167,11 @@ def _apply_skills_defaults(
     ) -> tuple[list[str], list[str] | None]:
         """Compute effective allowed_tools and setting_sources for skills.
 
-        If ``options.skills`` is not None, injects the ``Skill`` tool (or
-        ``Skill(name)`` entries) into allowed_tools and defaults
-        setting_sources to ``["user", "project"]`` when unset, so that the
-        CLI discovers installed skills without the caller having to wire up
-        both options manually.
+        When ``options.skills`` is ``"all"``, injects the bare ``Skill`` tool;
+        when it is a list, injects ``Skill(name)`` for each entry. In either
+        case ``setting_sources`` defaults to ``["user", "project"]`` when
+        unset so the CLI discovers installed skills without the caller having
+        to wire up both options manually. ``None`` is a no-op.
 
         Does not mutate the original options object.
         """
@@ -186,7 +186,7 @@ def _apply_skills_defaults(
         if skills is None:
             return allowed_tools, setting_sources
 
-        if not skills:
+        if skills == "all":
             if "Skill" not in allowed_tools:
                 allowed_tools.append("Skill")
         else:

src/claude_agent_sdk/types.py

@@ -1222,17 +1222,17 @@ class ClaudeAgentOptions:
     agents: dict[str, AgentDefinition] | None = None
     # Setting sources to load (user, project, local)
     setting_sources: list[SettingSource] | None = None
-    # Skills to enable for the main session. When set, the SDK automatically
-    # enables the ``Skill`` tool and defaults ``setting_sources`` to
-    # ``["user", "project"]`` (if not already set) so installed SKILL.md
-    # files are discovered. The list is also sent on the ``initialize`` control
-    # request so a supporting CLI can filter which skills are loaded into the
-    # system prompt (older CLIs ignore the field).
-    #   * ``None`` (default): no automatic skill configuration — manage
-    #     ``allowed_tools`` and ``setting_sources`` directly.
-    #   * ``[]``: enable all discovered skills.
-    #   * ``[name, ...]``: enable only the listed skills (added as
-    #     ``Skill(name)`` entries in ``--allowedTools``).
+    # Skills to enable for the main session. This is the one place to turn
+    # skills on; you do not need to add ``"Skill"`` to ``allowed_tools`` or
+    # set ``setting_sources`` yourself — the SDK does both when this is set.
+    # The value is also sent on the ``initialize`` control request so a
+    # supporting CLI can filter which skills are loaded into the system prompt
+    # (older CLIs ignore the field).
+    #   * ``None`` (default): skills are off.
+    #   * ``"all"``: enable every discovered skill.
+    #   * ``[name, ...]``: enable only the listed skills. Names match the
+    #     SKILL.md ``name`` / directory name, or ``plugin:skill`` for
+    #     plugin-qualified skills.
     #
     # .. note::
     #     This is a **context filter**, not a sandbox. Unlisted skills are
@@ -1243,7 +1243,7 @@ class ClaudeAgentOptions:
     #     bundle the desired subset as a local plugin (``plugins=[...]`` with
     #     ``setting_sources=None``), or add explicit permission deny rules.
     #     Do not store secrets in skill files.
-    skills: list[str] | None = None
+    skills: list[str] | Literal["all"] | None = None
     # Sandbox configuration for bash command isolation.
     # Filesystem and network restrictions are derived from permission rules (Read/Edit/WebFetch),
     # not from these sandbox settings.

tests/test_query.py

@@ -60,10 +60,13 @@ def test_initialize_omits_exclude_dynamic_sections_when_unset():
 
 
 def test_initialize_sends_skills_when_set():
-    """Query.initialize() includes skills (including empty list) in the control request."""
+    """Query.initialize() includes skills (list, 'all', or empty) in the control request."""
     sent = _capture_initialize_request(skills=["pdf", "docx"])
     assert sent["skills"] == ["pdf", "docx"]
 
+    sent_all = _capture_initialize_request(skills="all")
+    assert sent_all["skills"] == "all"
+
     sent_empty = _capture_initialize_request(skills=[])
     assert sent_empty["skills"] == []
 

tests/test_transport.py

@@ -466,18 +466,29 @@ def test_build_command_skills_none_leaves_options_untouched(self):
         assert "--allowedTools" not in cmd
         assert "--setting-sources" not in cmd
 
-    def test_build_command_skills_empty_list_enables_skill_tool(self):
-        """Empty skills list enables the bare Skill tool and defaults setting_sources."""
+    def test_build_command_skills_all_enables_skill_tool(self):
+        """skills='all' enables the bare Skill tool and defaults setting_sources."""
         transport = SubprocessCLITransport(
             prompt="test",
-            options=make_options(skills=[]),
+            options=make_options(skills="all"),
         )
         cmd = transport._build_command()
         assert "--allowedTools" in cmd
         assert cmd[cmd.index("--allowedTools") + 1] == "Skill"
         assert "--setting-sources" in cmd
         assert cmd[cmd.index("--setting-sources") + 1] == "user,project"
 
+    def test_build_command_skills_empty_list_adds_no_skill_entries(self):
+        """skills=[] is a degenerate subset: setting_sources defaults, no Skill entries."""
+        transport = SubprocessCLITransport(
+            prompt="test",
+            options=make_options(skills=[]),
+        )
+        cmd = transport._build_command()
+        assert "--allowedTools" not in cmd
+        assert "--setting-sources" in cmd
+        assert cmd[cmd.index("--setting-sources") + 1] == "user,project"
+
     def test_build_command_skills_named_list_uses_skill_patterns(self):
         """Non-empty skills list adds Skill(name) entries and defaults setting_sources."""
         transport = SubprocessCLITransport(
@@ -507,7 +518,7 @@ def test_build_command_skills_preserves_user_setting_sources(self):
         transport = SubprocessCLITransport(
             prompt="test",
             options=make_options(
-                skills=[],
+                skills="all",
                 setting_sources=["local"],
             ),
         )