refactor: share one constant for the skills="all" sentinel

Also document in the skills docstring that listed names must be exact.

Author: ant-kurt

src/claude_agent_sdk/_internal/transport/subprocess_cli.py

@@ -21,7 +21,12 @@
 from ..._errors import CLIConnectionError, CLINotFoundError, ProcessError
 from ..._errors import CLIJSONDecodeError as SDKJSONDecodeError
 from ..._version import __version__
-from ...types import ClaudeAgentOptions, SystemPromptFile, SystemPromptPreset
+from ...types import (
+    _SKILLS_ALL,
+    ClaudeAgentOptions,
+    SystemPromptFile,
+    SystemPromptPreset,
+)
 from .._task_compat import TaskHandle, spawn_detached
 from . import Transport
 
@@ -66,7 +71,7 @@ def _kill_active_children() -> None:
 
 def _reject_bare_string_skills(skills: object) -> None:
     """Reject a string in place of a list, which would iterate as characters."""
-    if isinstance(skills, str) and skills != "all":
+    if isinstance(skills, str) and skills != _SKILLS_ALL:
         raise TypeError(
             "ClaudeAgentOptions.skills must be a list of skill names or"
             f' "all", got the string {skills!r}. Did you mean [{skills!r}]?'
@@ -528,7 +533,7 @@ def _apply_skills_defaults(
             return allowed_tools, setting_sources
         _reject_bare_string_skills(skills)
 
-        if skills == "all":
+        if skills == _SKILLS_ALL:
             if "Skill" not in allowed_tools:
                 allowed_tools.append("Skill")
         else:

src/claude_agent_sdk/types.py

@@ -5,7 +5,7 @@
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Literal, Protocol, TypeAlias
+from typing import TYPE_CHECKING, Any, Final, Literal, Protocol, TypeAlias
 
 if sys.version_info >= (3, 11):
     from typing import NotRequired, Required, TypedDict
@@ -31,6 +31,9 @@
 
 # Agent definitions
 SettingSource = Literal["user", "project", "local"]
+
+# The ClaudeAgentOptions.skills value meaning "every discovered skill".
+_SKILLS_ALL: Final = "all"
 EffortLevel: TypeAlias = Literal["low", "medium", "high", "xhigh", "max"]
 
 
@@ -1745,7 +1748,7 @@ def _warn_if_can_use_tool_shadowed(options: "ClaudeAgentOptions") -> None:
     # allowed_tools, so it shadows the callback just like a hand-written entry.
     # skills=[names] appends Skill(name) specifiers, which do not.
     allowed_tools = options.allowed_tools
-    if options.skills == "all" and "Skill" not in allowed_tools:
+    if options.skills == _SKILLS_ALL and "Skill" not in allowed_tools:
         allowed_tools = [*allowed_tools, "Skill"]
     message = _get_can_use_tool_shadowed_warning(options.permission_mode, allowed_tools)
     if message is not None:
@@ -2009,6 +2012,8 @@ class ClaudeAgentOptions:
     - ``"all"``: enable every discovered skill.
     - ``list[str]``: enable only the listed skills. Names match the SKILL.md
       ``name`` / directory name, or ``plugin:skill`` for plugin-qualified skills.
+      Names must be exact: wildcards, delimiters, and surrounding whitespace
+      raise at ``connect()``.
 
     This is a **context filter**, not a sandbox: unlisted skills are hidden
     from the model's listing and rejected by the Skill tool, but their files