Move Skills client API into extensions

Author: Kludex

docs/advanced/extensions.md

@@ -198,7 +198,7 @@ after connecting to get the API bound to that connection. Run the
 import anyio
 
 from mcp import Client
-from mcp.client.skills import Skills
+from mcp.client.extensions.skills import Skills
 
 
 async def main() -> None:

docs/advanced/skills.md

@@ -56,7 +56,7 @@ get the verbs tied to that connection:
 --8<-- "docs_src/skills/tutorial001_client.py"
 ```
 
-`client.extension(Skills)` hands you a `BoundSkills` with the SEP-2640 methods:
+`client.extension(Skills)` hands you a `SkillsClient` with the SEP-2640 methods:
 
 * `list_skills` and `read_directory` follow `nextCursor` to completion, so a single call gives you
   every page's skills or resources.

docs_src/skills/tutorial001_client.py

@@ -1,7 +1,7 @@
 import anyio
 
 from mcp import Client
-from mcp.client.skills import Skills
+from mcp.client.extensions.skills import Skills
 
 
 async def main() -> None:

src/mcp/client/extensions/__init__.py

@@ -0,0 +1,3 @@
+from mcp.client.extensions.skills import Skills, SkillsClient
+
+__all__ = ["Skills", "SkillsClient"]

src/mcp/client/skills.py src/mcp/client/extensions/skills.pysrc/mcp/client/skills.py renamed to src/mcp/client/extensions/skills.py

@@ -9,7 +9,7 @@
         for skill in await client.extension(Skills).list_skills():
             print(skill.uri, skill.frontmatter["description"])
 
-`client.extension(Skills)` returns a `BoundSkills`. Its catalog verbs — `list_skills`,
+`client.extension(Skills)` returns a `SkillsClient`. Its catalog verbs — `list_skills`,
 `get_skill`, and `read_directory` — check that the server advertises the
 extension and validate its response; `list_skills` and `read_directory` follow
 `nextCursor` to completion, so one call returns every page's results.
@@ -36,25 +36,25 @@
     validate_directory_result,
 )
 
-__all__ = ["BoundSkills", "Skills"]
+__all__ = ["Skills", "SkillsClient"]
 
 
 class Skills(ClientExtension):
     """The client-side Skills extension: register, then access its typed verbs.
 
     Pass an instance to `Client(extensions=[Skills()])` — this advertises
     `io.modelcontextprotocol/skills` under the client's capabilities — and call
-    `client.extension(Skills)` once connected for a `BoundSkills` handle.
+    `client.extension(Skills)` once connected for a `SkillsClient` handle.
     """
 
     identifier = EXTENSION_ID
 
-    def bind(self, session: ClientSession) -> BoundSkills:
+    def bind(self, session: ClientSession) -> SkillsClient:
         """Return the SEP-2640 verbs bound to `session`."""
-        return BoundSkills(session)
+        return SkillsClient(session)
 
 
-class BoundSkills:
+class SkillsClient:
     """The SEP-2640 verbs bound to one connected session.
 
     Obtain it from `client.extension(Skills)`. The catalog verbs — `list_skills`,

src/mcp/shared/skills.py

@@ -1,6 +1,6 @@
 """Wire types and SEP-2640 conformance checks for the Skills extension.
 
-Shared by the server (`mcp.server.skills`) and client (`mcp.client.skills`)
+Shared by the server (`mcp.server.skills`) and client (`mcp.client.extensions.skills`)
 surfaces, mirroring how `mcp.shared.extension` hosts the identifier grammar
 both tiers need. See https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640.
 """

tests/client/test_skills.py tests/client/extensions/test_skills.pytests/client/test_skills.py renamed to tests/client/extensions/test_skills.py

@@ -1,4 +1,4 @@
-"""Tests for the client-side Skills extension (SEP-2640, `mcp.client.skills`)."""
+"""Tests for the client-side Skills extension (SEP-2640, `mcp.client.extensions.skills`)."""
 
 import hashlib
 from collections.abc import AsyncIterator
@@ -9,8 +9,8 @@
 from mcp_types import INVALID_PARAMS, Resource
 
 from mcp.client.client import Client
-from mcp.client.skills import BoundSkills
-from mcp.client.skills import Skills as ClientSkills
+from mcp.client.extensions.skills import Skills as ClientSkills
+from mcp.client.extensions.skills import SkillsClient
 from mcp.server.context import ServerRequestContext
 from mcp.server.extension import Extension, MethodBinding
 from mcp.server.mcpserver import MCPServer
@@ -82,7 +82,7 @@ async def handler(ctx: ServerRequestContext[Any, Any], params: ListSkillsParams)
 class _NonConformantGetSkill(Extension):
     """A server that advertises the extension but answers `skills/get` with the wrong skill -
     the case the SDK's own `Skills` extension already rules out server-side, so this
-    exercises `mcp.client.skills.get_skill`'s own defense-in-depth check."""
+    exercises `mcp.client.extensions.skills.SkillsClient.get_skill`'s own defense-in-depth check."""
 
     identifier = EXTENSION_ID
 
@@ -138,7 +138,7 @@ def _server(*, with_directory_read: bool = False) -> MCPServer:
 
 
 @asynccontextmanager
-async def _skills(server: MCPServer) -> AsyncIterator[BoundSkills]:
+async def _skills(server: MCPServer) -> AsyncIterator[SkillsClient]:
     """Register the client `Skills` extension, connect, and yield the bound verbs."""
     extension = ClientSkills()
     async with Client(server, extensions=[extension]) as client:

tests/docs_src/test_skills.py

@@ -5,7 +5,7 @@
 
 from docs_src.skills import tutorial001
 from mcp import Client
-from mcp.client.skills import Skills
+from mcp.client.extensions.skills import Skills
 from mcp.shared.exceptions import MCPError
 
 pytestmark = pytest.mark.anyio

tests/shared/test_skills.py

@@ -1,7 +1,7 @@
 """SEP-2640 conformance checks in `mcp.shared.skills`: types and validation.
 
 Server- and client-side end-to-end wiring live in `tests/server/test_skills.py` and
-`tests/client/test_skills.py`; this file pins the pure functions both depend on.
+`tests/client/extensions/test_skills.py`; this file pins the pure functions both depend on.
 """
 
 from typing import Any