π The fast, Pythonic way to build MCP servers and clients.
Deprecate the 4.1 skills API for removal in 4.3 (#6280)
nate nowack383760ffa336
diff --git a/dev-docs/v4-notes/change-register.md b/dev-docs/v4-notes/change-register.mdindex eb1db6549..878622be8 100644--- a/dev-docs/v4-notes/change-register.md+++ b/dev-docs/v4-notes/change-register.md@@ -589,7 +589,8 @@ The `_REMOVED_KWARGS` constructor shim (which raises helpful `TypeError`s for kw- **Component-import compatibility shims** β Breaking. `fastmcp.tools.tool`, `fastmcp.resources.resource`, and `fastmcp.prompts.prompt` no longer exist as modules. Two separate mechanisms kept them alive and both are now gone: the `__getattr__` shims that re-exported `FunctionTool` / `ParsedFunction` / `tool`, `FunctionResource` / `resource`, and `FunctionPrompt` / `prompt`; and the `sys.modules` aliases that pointed each old module name at its renamed `base.py`. Import the component types from the package itself β `from fastmcp.tools import Tool, ToolResult` β and the function-backed classes from their canonical modules (`fastmcp.tools.function_tool`, `fastmcp.resources.function_resource`, `fastmcp.prompts.function_prompt`).- **`fastmcp.experimental.sampling`** and **`fastmcp.experimental.sampling.handlers`** (2.x-era re-export shims) β Breaking. These aliased the client-side sampling handlers without warning. Import from `fastmcp.client.sampling.handlers.openai` instead. Note this is unrelated to the SEP-2577 removal of *server-initiated* sampling: a FastMCP client still answers a legacy-era server's sampling requests, so `Client(sampling_handler=...)` and the Anthropic / OpenAI / Google GenAI handlers under `fastmcp.client.sampling.handlers` remain fully supported.- **`fastmcp.server.auth.authorization`** (3.0-era re-export shim) β Breaking. The module was a pass-through sitting between the `fastmcp.server.auth` package and the real implementation in `fastmcp.utilities.authorization`, and FastMCP's own middleware and local-provider decorators imported through it. Everything internal now imports from `fastmcp.utilities.authorization` directly. The documented public path is unchanged: `from fastmcp.server.auth import require_scopes, require_roles, restrict_tag, run_auth_checks, AuthCheck, AuthContext`. Two names the old module also exported β `run_auth_checks_with_shortfall` and `scope_requirements` β are *not* re-exported from `fastmcp.server.auth` and must be imported from `fastmcp.utilities.authorization`. They are middleware plumbing with no documented user-facing use, so they were deliberately not widened onto the auth package's surface; the upgrade guide names the utilities path for them explicitly.-- **`SkillsProvider`** (3.0-era rename alias) β Breaking. Use `SkillsDirectoryProvider` from `fastmcp.server.providers.skills`. The alias was also re-exported from `fastmcp.server.providers`; both are gone.+- **`SkillsProvider`** (3.0-era rename alias) β Breaking. Use `SkillsDirectoryProvider` from `fastmcp.skills.provider`. The alias was also re-exported from `fastmcp.server.providers`; both are gone.+- **The 4.1 skills API** (`fastmcp.server.providers.skills`, `fastmcp.utilities.skills`) β Deprecated in 4.2, removed in 4.3. Both shipped in stable releases, so they keep their 4.1 behavior and each constructor or helper warns with its replacement: `SkillsDirectoryProvider(roots, *, reload=False)` and `SkillCatalogProvider([Skill.from_directory(path)])` from `fastmcp.skills.provider`, and `Client.list_skills()`, `Client.get_skill()`, `Client.read_skill()` plus `Skill.to_directory()` on the client side. The directory warnings run the new loader's checks and list each folder it would refuse, with the fix. The new provider stops the server at startup on any folder that isn't a valid Agent Skill. `experimental_skills=True` was documented as changeable, so it now returns the new provider directly (with a warning). `list_skill_summaries` existed only in the 4.2 alphas and is gone. `fastmcp.skills.Skill` was the wire model in 4.1 and is the authoring class in 4.2; the wire model is `MCPSkill`. Until 4.3, `Skill(uri=..., frontmatter=..., resources=...)`, `Skill.model_validate(...)` and `fastmcp.skills.models.Skill` still build an `MCPSkill` and warn. `Client.list_skill_resources()` is the supported way to list skills on servers without the Skills extension, and stays after 4.3.- **`ctx.elicit()` without `response_type`** (deprecated 3.2, warned through 3.4.4) β Breaking. The parameter is now required, and passing `None` explicitly raises `TypeError`. The empty-object schema it produced was ambiguous under the MCP spec and left some clients (e.g. VS Code) rendering an empty, non-functional form. Pass a type describing the data you expect back; `bool` covers confirmations. This is the server-authoring API only β the *client* elicitation handler still receives `response_type=None` for URL requests and for empty schemas sent by other servers, which is unchanged.*Verify:* deletions of `fastmcp_slim/fastmcp/server/proxy.py`, `fastmcp_slim/fastmcp/server/openapi/`, `fastmcp_slim/fastmcp/experimental/server/openapi/`, `fastmcp_slim/fastmcp/experimental/utilities/openapi/`, `fastmcp_slim/fastmcp/server/apps.py`, `fastmcp_slim/fastmcp/server/app.py`; the removed classes in `fastmcp_slim/fastmcp/server/middleware/tool_injection.py`; the removed parameter in `fastmcp_slim/fastmcp/client/transports/http.py`; `fastmcp_slim/fastmcp/server/server.py`; `fastmcp_slim/fastmcp/tools/base.py`, `tools/function_tool.py`, `tools/tool_transform.py`, `tools/function_parsing.py`; `fastmcp_slim/fastmcp/settings.py`, `resources/function_resource.py`, `prompts/function_prompt.py`, and the local-provider decorators; `resources/base.py`, `prompts/base.py`.diff --git a/docs/servers/skills.mdx b/docs/servers/skills.mdxindex db880d3b1..94b09500d 100644--- a/docs/servers/skills.mdx+++ b/docs/servers/skills.mdx@@ -175,8 +175,27 @@ async with client:Every file is verified before anything is written. `overwrite=True` replaces an existing skill folder, including any files added to it locally.+A server without the Skills extension, such as one on FastMCP 4.1, has no `skills/list`. Loop over `await client.list_skill_resources()` instead and pass each `str(resource.uri)` to `read_skill()`; that works on any server that publishes skills as `skill://` resources.+## Current limits- A provider added with a namespace or other transforms isn't discoverable; mount a server instead.- A proxied skill whose manifest is `"dynamic"` is left out, since the gateway can't check its files.- `directoryRead` isn't implemented.++## Moving off the 4.1 skills API++The providers in `fastmcp.server.providers.skills` and the helpers in `fastmcp.utilities.skills` still work in 4.2, exactly as they did in 4.1, and are removed in 4.3. Each warns with the call that replaces it: the providers when they're constructed, the helpers when they're called. The directory warnings also list every folder the new `SkillsDirectoryProvider` would refuse and the fix for each, so you can fix those first and then switch.++| 4.1 | 4.2 |+| --- | --- |+| `SkillsDirectoryProvider(root)` from `fastmcp.server.providers.skills` | `SkillsDirectoryProvider(root)` from `fastmcp.skills.provider` |+| `ClaudeSkillsProvider()` and the other vendor presets | `SkillsDirectoryProvider(Path.home() / ".claude" / "skills")` with the preset's folder |+| `SkillProvider(path)` | `SkillCatalogProvider([Skill.from_directory(path)])` |+| `SkillsDirectoryProvider(root, experimental_skills=True)` | `SkillsDirectoryProvider(root)` from `fastmcp.skills.provider`; the old call already returns it |+| `list_skills(client)` | `client.list_skill_resources()` (any server) or `client.list_skills()` (Skills extension) |+| `get_skill_manifest(client, name)` | `client.get_skill(uri)` |+| `Skill(uri=..., frontmatter=..., resources=...)` from `fastmcp.skills` | `MCPSkill(...)`; `Skill` is now the authoring class |+| `download_skill()` / `sync_skills()` | `client.read_skill(uri)` then `skill.to_directory(path)` ([example](#install-skills-into-a-local-agent)) |++`client.list_skills()` needs a server that serves the Skills extension, which a 4.1 server doesn't. `client.list_skill_resources()` lists skills on any server that publishes them as `skill://` resources, and `client.read_skill(uri)` reads a valid skill through its `_manifest` resource, so both keep working with older servers after 4.3. The new provider has no `main_file_name` or `supporting_files`: the main file is always `SKILL.md`, and every file in a skill is readable as a resource.diff --git a/fastmcp_slim/fastmcp/client/mixins/skills.py b/fastmcp_slim/fastmcp/client/mixins/skills.pyindex 2df76ed6e..6a5c76c3a 100644--- a/fastmcp_slim/fastmcp/client/mixins/skills.py+++ b/fastmcp_slim/fastmcp/client/mixins/skills.py@@ -207,6 +207,24 @@ class ClientSkillsMixin:send=_send,)+ async def list_skill_resources(self: Client) -> list[mcp_types.Resource]:+ """List the skills a server publishes as `skill://.../SKILL.md` resources.++ Use this for servers that serve skills as resources but not through the+ Skills extension, such as FastMCP 4.1 and earlier. Pass a returned+ resource's `uri` to `read_skill()` to fetch the whole skill.++ Returns:+ The `SKILL.md` resource of each skill, in the server's order.+ """+ resources = await self.list_resources()+ return [+ resource+ for resource in resources+ if str(resource.uri).startswith("skill://")+ and str(resource.uri).endswith("/SKILL.md")+ ]+async def get_skill(self: Client,uri: str,diff --git a/fastmcp_slim/fastmcp/server/providers/__init__.py b/fastmcp_slim/fastmcp/server/providers/__init__.pyindex 8cac9e782..d1d3377bb 100644--- a/fastmcp_slim/fastmcp/server/providers/__init__.py+++ b/fastmcp_slim/fastmcp/server/providers/__init__.py@@ -69,7 +69,7 @@ def __getattr__(name: str) -> object:return OpenAPIProviderif name in ("SkillProvider", "SkillsDirectoryProvider", "ClaudeSkillsProvider"):- # Imported lazily so `fastmcp.server.providers` stays light.+ # Deprecated providers; constructing one warns with the replacement.from fastmcp.server.providers import skillsreturn getattr(skills, name)diff --git a/fastmcp_slim/fastmcp/server/providers/skills/_deprecation.py b/fastmcp_slim/fastmcp/server/providers/skills/_deprecation.pynew file mode 100644index 000000000..4744a9ea8--- /dev/null+++ b/fastmcp_slim/fastmcp/server/providers/skills/_deprecation.py@@ -0,0 +1,92 @@+"""Deprecation warnings for the resource-only skills providers.++These providers shipped in FastMCP 3 and 4.1. They are deprecated in 4.2 and+removed in 4.3 in favor of `fastmcp.skills.provider`. Each warning names the+replacement call and, because the replacement refuses to start on folders that+are not valid Agent Skills, lists the folders that need fixing first.+"""++from __future__ import annotations++import warnings+from collections.abc import Sequence+from pathlib import Path++import fastmcp+from fastmcp._warnings import FastMCPDeprecationWarning++_SPEC = "https://agentskills.io/specification"+++def warn_directory_provider(+ cls: type,+ roots: Sequence[Path],+ *,+ reload: bool,+ main_file_name: str,+ stacklevel: int,+) -> None:+ """Warn that a resource-only directory provider is deprecated."""+ if not fastmcp.settings.deprecation_warnings:+ return+ from fastmcp.skills.provider import _scan_skill_roots++ old = f"`{cls.__name__}`"+ if not cls.__module__.startswith("fastmcp."):+ old += (+ " (a subclass of `fastmcp.server.providers.skills.SkillsDirectoryProvider`)"+ )+ paths = [str(root) for root in roots]+ reload_arg = ", reload=True" if reload else ""+ _, invalid = _scan_skill_roots(roots)+ warnings.warn(+ f"{old} is deprecated and will be removed in FastMCP 4.3. Replace it with "+ "`from fastmcp.skills.provider import SkillsDirectoryProvider` and "+ f"`SkillsDirectoryProvider({paths!r}{reload_arg})`. "+ + _readiness(invalid, main_file_name),+ FastMCPDeprecationWarning,+ stacklevel=stacklevel + 1,+ )+++def warn_skill_provider(skill_path: Path, main_file_name: str) -> None:+ """Warn that the single-folder `SkillProvider` is deprecated."""+ if not fastmcp.settings.deprecation_warnings:+ return+ from fastmcp.skills.provider import _invalid_folder+ from fastmcp.skills.skill import Skill++ invalid: list[str] = []+ try:+ skill = Skill.from_directory(skill_path)+ if skill.name != skill_path.name:+ raise ValueError(f"folder name must match its SKILL.md name {skill.name!r}")+ except (OSError, ValueError) as exc:+ invalid.append(_invalid_folder(skill_path, skill_path.name, exc))+ warnings.warn(+ "`SkillProvider` is deprecated and will be removed in FastMCP 4.3. Replace it "+ "with `from fastmcp.skills import Skill`, "+ "`from fastmcp.skills.provider import SkillCatalogProvider` and "+ f"`SkillCatalogProvider([Skill.from_directory({str(skill_path)!r})])`. "+ + _readiness(invalid, main_file_name),+ FastMCPDeprecationWarning,+ stacklevel=3,+ )+++def _readiness(invalid: list[str], main_file_name: str = "SKILL.md") -> str:+ rename = (+ f"Rename each `{main_file_name}` to `SKILL.md` first. "+ if main_file_name != "SKILL.md"+ else ""+ )+ intro = (+ "The replacement serves skills through the MCP skills extension as well as "+ "`skill://` resources, and it stops the server at startup if a folder is not "+ f"a valid Agent Skill ({_SPEC}). {rename}"+ )+ if main_file_name != "SKILL.md":+ return intro + "The folders can only be checked once they use `SKILL.md`."+ if not invalid:+ return intro + "Every skill folder found already passes."+ return intro + "Fix these folders first:\n" + "\n".join(invalid)diff --git a/fastmcp_slim/fastmcp/server/providers/skills/directory_provider.py b/fastmcp_slim/fastmcp/server/providers/skills/directory_provider.pyindex cc48ea2c2..a7483f3bc 100644--- a/fastmcp_slim/fastmcp/server/providers/skills/directory_provider.py+++ b/fastmcp_slim/fastmcp/server/providers/skills/directory_provider.py@@ -13,6 +13,7 @@ from fastmcp._warnings import FastMCPDeprecationWarningfrom fastmcp.resources.base import Resourcefrom fastmcp.resources.template import ResourceTemplatefrom fastmcp.server.providers.aggregate import AggregateProvider+from fastmcp.server.providers.skills._deprecation import warn_directory_providerfrom fastmcp.server.providers.skills.skill_provider import SkillProviderfrom fastmcp.utilities.logging import get_loggerfrom fastmcp.utilities.versions import VersionSpec@@ -23,6 +24,11 @@ logger = get_logger(__name__)class SkillsDirectoryProvider(AggregateProvider):"""Provider that scans directories and creates a SkillProvider per skill folder.+ Deprecated since 4.2 and removed in 4.3: use+ `fastmcp.skills.provider.SkillsDirectoryProvider`, which also serves the MCP+ skills extension. Constructing this provider warns with the replacement call+ and the folders that would stop the replacement from starting.+This extends AggregateProvider to combine multiple SkillProviders into one.Each subdirectory containing a main file (default: SKILL.md) becomes a skill.Can scan multiple root directories - if a skill name appears in multiple roots,@@ -91,6 +97,15 @@ class SkillsDirectoryProvider(AggregateProvider):self._main_file_name = main_file_nameself._supporting_files = supporting_filesself._discovered = False+ # A preset subclass adds one frame between the caller and this one.+ depth = 2 + type(self).__mro__.index(SkillsDirectoryProvider)+ warn_directory_provider(+ type(self),+ self._roots,+ reload=reload,+ main_file_name=main_file_name,+ stacklevel=depth,+ )self._discover_skills()def _discover_skills(self) -> None:@@ -137,6 +152,7 @@ class SkillsDirectoryProvider(AggregateProvider):skill_path=skill_dir,main_file_name=self._main_file_name,supporting_files=self._supporting_files,+ _from_directory_provider=True,)self.providers.append(provider)seen_skill_names.add(skill_name)diff --git a/fastmcp_slim/fastmcp/server/providers/skills/skill_provider.py b/fastmcp_slim/fastmcp/server/providers/skills/skill_provider.pyindex 5aa20ec36..e93b5fc13 100644--- a/fastmcp_slim/fastmcp/server/providers/skills/skill_provider.py+++ b/fastmcp_slim/fastmcp/server/providers/skills/skill_provider.py@@ -21,6 +21,7 @@ from fastmcp.server.providers.skills._common import (resolve_within,scan_skill_files,)+from fastmcp.server.providers.skills._deprecation import warn_skill_providerfrom fastmcp.utilities.logging import get_loggerfrom fastmcp.utilities.versions import VersionSpec@@ -170,6 +171,9 @@ class SkillFileResource(Resource):class SkillProvider(Provider):"""Provider that exposes a single skill folder as MCP resources.+ Deprecated since 4.2 and removed in 4.3: use+ `SkillCatalogProvider([Skill.from_directory(path)])` from `fastmcp.skills.provider`.+Each skill folder must contain a main file (default: SKILL.md) and maycontain additional supporting files.@@ -206,12 +210,16 @@ class SkillProvider(Provider):skill_path: str | Path,main_file_name: str = "SKILL.md",supporting_files: Literal["template", "resources"] = "template",+ *,+ _from_directory_provider: bool = False,) -> None:super().__init__()self._skill_path = Path(skill_path).resolve()self._main_file_name = main_file_nameself._supporting_files = supporting_filesself._skill_info: SkillInfo | None = None+ if not _from_directory_provider:+ warn_skill_provider(self._skill_path, main_file_name)# Load at init to catch errors earlyself._load_skill()diff --git a/fastmcp_slim/fastmcp/skills/models.py b/fastmcp_slim/fastmcp/skills/models.pyindex dab7debd3..1dc8fd0a5 100644--- a/fastmcp_slim/fastmcp/skills/models.py+++ b/fastmcp_slim/fastmcp/skills/models.py@@ -225,3 +225,20 @@ class GetSkillRequest(mcp_types.Request[GetSkillParams, Literal["skills/get"]]):method: Literal["skills/get"] = "skills/get"params: GetSkillParams+++def __getattr__(name: str) -> object:+ if name == "Skill":+ import warnings++ from fastmcp._warnings import FastMCPDeprecationWarning++ warnings.warn(+ "`fastmcp.skills.models.Skill` is now `MCPSkill`; replace it with "+ "`from fastmcp.skills import MCPSkill`. This alias is removed in "+ "FastMCP 4.3.",+ FastMCPDeprecationWarning,+ stacklevel=2,+ )+ return MCPSkill+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")diff --git a/fastmcp_slim/fastmcp/skills/skill.py b/fastmcp_slim/fastmcp/skills/skill.pyindex 53b0709e6..6872e759d 100644--- a/fastmcp_slim/fastmcp/skills/skill.py+++ b/fastmcp_slim/fastmcp/skills/skill.py@@ -6,18 +6,32 @@ import hashlibimport osimport shutilimport tempfile+import warningsfrom collections.abc import Mappingfrom pathlib import Path, PureWindowsPathfrom types import MappingProxyType-from typing import Any+from typing import Any, castfrom urllib.parse import quotefrom pydantic import JsonValue+from typing_extensions import Self+from fastmcp._warnings import FastMCPDeprecationWarningfrom fastmcp.skills._constants import MAX_SKILL_BYTES, MAX_SKILL_FILESfrom fastmcp.skills.models import MCPSkill, SkillFrontmatter, SkillResource+def _warn_wire_model(call: str) -> None:+ warnings.warn(+ f"`{call}` builds the 4.1 wire model, which is now `MCPSkill`; "+ "`fastmcp.skills.Skill` is the skill authoring class. Replace it with "+ f"`{call.replace('Skill', 'MCPSkill', 1)}` and "+ "`from fastmcp.skills import MCPSkill`. This alias is removed in FastMCP 4.3.",+ FastMCPDeprecationWarning,+ stacklevel=3,+ )++def _validate_limits(file_count: int, total_bytes: int) -> None:if file_count > MAX_SKILL_FILES:raise ValueError(f"A skill may contain at most {MAX_SKILL_FILES} files")@@ -74,6 +88,27 @@ class Skill:_files: Mapping[str, bytes]_frontmatter: SkillFrontmatter+ def __new__(cls, *args: Any, **kwargs: Any) -> Self:+ # In 4.1 `fastmcp.skills.Skill` was the wire model now named `MCPSkill`.+ # Its keywords (`uri`, `resources`) never mean an authored skill.+ if cls is Skill and ("uri" in kwargs or "resources" in kwargs):+ _warn_wire_model("Skill(uri=..., frontmatter=..., resources=...)")+ # Statically a `Skill`, so authoring code keeps its types.+ return cast(Any, MCPSkill(*args, **kwargs))+ return super().__new__(cls)++ @classmethod+ def model_validate(cls, obj: Any, **kwargs: Any) -> MCPSkill:+ """Deprecated 4.1 alias for `MCPSkill.model_validate`."""+ _warn_wire_model("Skill.model_validate(...)")+ return MCPSkill.model_validate(obj, **kwargs)++ @classmethod+ def model_validate_json(cls, json_data: str | bytes, **kwargs: Any) -> MCPSkill:+ """Deprecated 4.1 alias for `MCPSkill.model_validate_json`."""+ _warn_wire_model("Skill.model_validate_json(...)")+ return MCPSkill.model_validate_json(json_data, **kwargs)+def __init__(self,*,diff --git a/fastmcp_slim/fastmcp/utilities/skills.py b/fastmcp_slim/fastmcp/utilities/skills.pyindex 6e197fda2..196f318fb 100644--- a/fastmcp_slim/fastmcp/utilities/skills.py+++ b/fastmcp_slim/fastmcp/utilities/skills.py@@ -1,19 +1,35 @@-"""Client utilities for discovering and downloading skills from MCP servers."""+"""Client helpers for skills served as `skill://` resources.++Deprecated since 4.2 and removed in 4.3. Use the `Client` skills methods:+`list_skills()`, `get_skill()` and `read_skill()`, then `Skill.to_directory()`.+"""from __future__ import annotationsimport base64import json+import warningsfrom dataclasses import dataclassfrom pathlib import Pathfrom typing import TYPE_CHECKINGimport mcp_types+from fastmcp._warnings import FastMCPDeprecationWarning+if TYPE_CHECKING:from fastmcp.client import Client+def _deprecated(name: str, replacement: str) -> None:+ warnings.warn(+ f"`fastmcp.utilities.skills.{name}` is deprecated and will be removed in "+ f"FastMCP 4.3. {replacement}",+ FastMCPDeprecationWarning,+ stacklevel=3,+ )++@dataclassclass SkillSummary:"""Summary information about a skill available on a server."""@@ -63,6 +79,15 @@ async def list_skills(client: Client) -> list[SkillSummary]:print(f"{skill.name}: {skill.description}")```"""+ _deprecated(+ "list_skills",+ "Use `await client.list_skill_resources()`, or `await client.list_skills()` "+ "for servers with the Skills extension.",+ )+ return await _list_skills(client)+++async def _list_skills(client: Client) -> list[SkillSummary]:resources = await client.list_resources()skills = []@@ -97,6 +122,15 @@ async def get_skill_manifest(client: Client, skill_name: str) -> SkillManifest:Raises:ValueError: If manifest cannot be read or parsed"""+ _deprecated(+ "get_skill_manifest",+ "Use `await client.get_skill('skill://<name>/SKILL.md')`; its "+ "`resources` list every file with its digest and size.",+ )+ return await _get_skill_manifest(client, skill_name)+++async def _get_skill_manifest(client: Client, skill_name: str) -> SkillManifest:manifest_uri = f"skill://{skill_name}/_manifest"result = await client.read_resource(manifest_uri)@@ -163,6 +197,17 @@ async def download_skill(print(f"Downloaded to: {skill_path}")```"""+ _deprecated(+ "download_skill",+ "Use `(await client.read_skill('skill://<name>/SKILL.md'))"+ ".to_directory(target_dir / '<name>')`.",+ )+ return await _download_skill(client, skill_name, target_dir, overwrite=overwrite)+++async def _download_skill(+ client: Client, skill_name: str, target_dir: str | Path, *, overwrite: bool+) -> Path:target_dir = Path(target_dir).expanduser().resolve()skill_dir = (target_dir / skill_name).resolve()@@ -178,7 +223,7 @@ async def download_skill()# Get manifest to know what files to download- manifest = await get_skill_manifest(client, skill_name)+ manifest = await _get_skill_manifest(client, skill_name)# Create skill directoryskill_dir.mkdir(parents=True, exist_ok=True)@@ -242,12 +287,17 @@ async def sync_skills(print(f"Downloaded {len(paths)} skills")```"""- skills = await list_skills(client)+ _deprecated(+ "sync_skills",+ "Loop over `await client.list_skill_resources()` and call "+ "`(await client.read_skill(str(resource.uri))).to_directory(target_dir / name)`.",+ )+ skills = await _list_skills(client)downloaded = []for skill in skills:try:- path = await download_skill(+ path = await _download_skill(client, skill.name, target_dir, overwrite=overwrite)downloaded.append(path)diff --git a/tests/server/providers/test_skill_main_files.py b/tests/server/providers/test_skill_main_files.pyindex ac449b78a..f2eaf2878 100644--- a/tests/server/providers/test_skill_main_files.py+++ b/tests/server/providers/test_skill_main_files.py@@ -9,6 +9,12 @@ from mcp_types import TextResourceContentsfrom fastmcp import Client, FastMCPfrom fastmcp.server.providers.skills import SkillProvider, SkillsDirectoryProvider+# These providers are deprecated; tests/skills/test_deprecated_paths.py checks+# the warnings.+pytestmark = pytest.mark.filterwarnings(+ "ignore::fastmcp._warnings.FastMCPDeprecationWarning"+)+def make_skill(path: Path, content: str = "# Instructions") -> Path:path.mkdir()diff --git a/tests/server/providers/test_skill_supporting_reads.py b/tests/server/providers/test_skill_supporting_reads.pyindex 745bce8e7..0507d8a27 100644--- a/tests/server/providers/test_skill_supporting_reads.py+++ b/tests/server/providers/test_skill_supporting_reads.py@@ -10,6 +10,12 @@ from mcp_types import BlobResourceContents, TextResourceContentsfrom fastmcp import Client, FastMCPfrom fastmcp.server.providers.skills import SkillProvider+# These providers are deprecated; tests/skills/test_deprecated_paths.py checks+# the warnings.+pytestmark = pytest.mark.filterwarnings(+ "ignore::fastmcp._warnings.FastMCPDeprecationWarning"+)+@pytest.mark.parametrize("supporting_files", ["template", "resources"])@pytest.mark.parametrize(diff --git a/tests/server/providers/test_skills_provider.py b/tests/server/providers/test_skills_provider.pyindex d0164390a..51d4e5e8d 100644--- a/tests/server/providers/test_skills_provider.py+++ b/tests/server/providers/test_skills_provider.py@@ -16,6 +16,12 @@ from fastmcp.server.providers.skills import (from fastmcp.server.providers.skills._common import parse_frontmatterfrom fastmcp.server.providers.skills.skill_provider import SkillFileResource+# These providers are deprecated; tests/skills/test_deprecated_paths.py checks+# the warnings.+pytestmark = pytest.mark.filterwarnings(+ "ignore::fastmcp._warnings.FastMCPDeprecationWarning"+)+class TestParseFrontmatter:def test_no_frontmatter(self):diff --git a/tests/server/providers/test_skills_vendor_providers.py b/tests/server/providers/test_skills_vendor_providers.pyindex 65959ef1d..6dd7647f2 100644--- a/tests/server/providers/test_skills_vendor_providers.py+++ b/tests/server/providers/test_skills_vendor_providers.py@@ -4,6 +4,8 @@ from __future__ import annotationsfrom pathlib import Path+import pytest+from fastmcp.server.providers.skills import (ClaudeSkillsProvider,CodexSkillsProvider,@@ -15,6 +17,12 @@ from fastmcp.server.providers.skills import (VSCodeSkillsProvider,)+# These providers are deprecated; tests/skills/test_deprecated_paths.py checks+# the warnings.+pytestmark = pytest.mark.filterwarnings(+ "ignore::fastmcp._warnings.FastMCPDeprecationWarning"+)+class TestVendorProviders:"""Tests for vendor-specific skills providers."""diff --git a/tests/skills/test_deprecated_paths.py b/tests/skills/test_deprecated_paths.pyindex fa46b8de3..588218cf7 100644--- a/tests/skills/test_deprecated_paths.py+++ b/tests/skills/test_deprecated_paths.py@@ -1,7 +1,8 @@-"""`experimental_skills=True` now means the new provider; alpha-only helpers are gone."""+"""The 4.1 skills API keeps working in 4.2 and warns with its replacement."""from __future__ import annotations+import warningsfrom pathlib import Pathimport pytest@@ -11,10 +12,82 @@ from fastmcp._warnings import FastMCPDeprecationWarningfrom fastmcp.skills import Skill, SkillsClientExtensionfrom fastmcp.skills.extension import SkillsExtensionfrom fastmcp.skills.provider import SkillsDirectoryProvider+from fastmcp.utilities.tests import temporary_settingsREVIEW = Skill(name="review", description="Review changes", instructions="# Review\n")+def write_invalid(folder: Path) -> Path:+ folder.mkdir(parents=True)+ (folder / "SKILL.md").write_text("# Just text\n")+ return folder+++async def test_old_directory_provider_warns_and_keeps_serving(tmp_path: Path):+ from fastmcp.server.providers.skills import (+ SkillsDirectoryProvider as OldDirectoryProvider,+ )++ REVIEW.to_directory(tmp_path / "review")+ write_invalid(tmp_path / "pdf_tools")++ with pytest.warns(FastMCPDeprecationWarning) as record:+ provider = OldDirectoryProvider(tmp_path, reload=True)++ (warning,) = record+ message = str(warning.message)+ assert warning.filename == __file__+ assert "removed in FastMCP 4.3" in message+ assert (+ f"SkillsDirectoryProvider([{str(tmp_path.resolve())!r}], reload=True)"+ in message+ )+ assert "Fix these folders first:" in message+ assert "rename the folder to 'pdf-tools'" in message++ # Still the 4.1 resource behavior, including the folder the new loader rejects.+ async with Client(FastMCP("Skills", providers=[provider])) as client:+ uris = {str(resource.uri) for resource in await client.list_resources()}+ assert {"skill://review/SKILL.md", "skill://pdf_tools/SKILL.md"} <= uris+++def test_warning_says_when_every_folder_already_passes(tmp_path: Path):+ from fastmcp.server.providers.skills import (+ SkillsDirectoryProvider as OldDirectoryProvider,+ )++ REVIEW.to_directory(tmp_path / "review")+ with pytest.warns(FastMCPDeprecationWarning, match="already passes"):+ OldDirectoryProvider(tmp_path)+++def test_custom_main_file_is_told_to_rename(tmp_path: Path):+ from fastmcp.server.providers.skills import (+ SkillsDirectoryProvider as OldDirectoryProvider,+ )++ (tmp_path / "pdf_tools").mkdir()+ (tmp_path / "pdf_tools" / "README.md").write_text("# PDF tools\n")+ with pytest.warns(FastMCPDeprecationWarning) as record:+ OldDirectoryProvider(tmp_path, main_file_name="README.md")+ message = str(record[0].message)+ assert "Rename each `README.md`" in message+ assert "can only be checked once" in message+ assert "already passes" not in message+++def test_no_warning_or_scan_when_deprecation_warnings_are_off(tmp_path: Path):+ from fastmcp.server.providers.skills import (+ SkillsDirectoryProvider as OldDirectoryProvider,+ )++ write_invalid(tmp_path / "pdf_tools")+ with temporary_settings(deprecation_warnings=False):+ with warnings.catch_warnings():+ warnings.simplefilter("error", FastMCPDeprecationWarning)+ OldDirectoryProvider(tmp_path)++async def test_experimental_skills_returns_the_replacement(tmp_path: Path):from fastmcp.server.providers.skills import (SkillsDirectoryProvider as OldDirectoryProvider,@@ -47,12 +120,108 @@ def test_experimental_skills_still_rejects_custom_main_file(tmp_path: Path):)+async def test_old_skill_provider_warns_with_the_fix_and_keeps_serving(+ tmp_path: Path,+):+ from fastmcp.server.providers.skills import SkillProvider++ folder = write_invalid(tmp_path / "pdf_tools")+ with pytest.warns(FastMCPDeprecationWarning) as record:+ provider = SkillProvider(folder)++ (warning,) = record+ assert warning.filename == __file__+ assert "SkillCatalogProvider([Skill.from_directory(" in str(warning.message)+ assert "from fastmcp.skills.provider import SkillCatalogProvider" in str(+ warning.message+ )+ assert "rename the folder to 'pdf-tools'" in str(warning.message)+ async with Client(FastMCP("Skills", providers=[provider])) as client:+ (content,) = await client.read_resource("skill://pdf_tools/SKILL.md")+ assert "Just text" in getattr(content, "text", "")+++def test_vendor_presets_name_their_folder(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+):+ monkeypatch.setenv("HOME", str(tmp_path))+ monkeypatch.setenv("USERPROFILE", str(tmp_path))+ from fastmcp.server.providers import ClaudeSkillsProvider+ from fastmcp.server.providers.skills import CodexSkillsProvider++ with pytest.warns(FastMCPDeprecationWarning) as record:+ CodexSkillsProvider()+ ClaudeSkillsProvider()++ codex, claude = record+ assert str(codex.message).startswith("`CodexSkillsProvider` is deprecated")+ assert repr(str(Path(tmp_path, ".codex", "skills").resolve())) in str(codex.message)+ assert repr(str(Path(tmp_path, ".claude", "skills").resolve())) in str(+ claude.message+ )+ assert codex.filename == claude.filename == __file__+++async def test_old_client_helpers_warn_and_keep_working(tmp_path: Path):+ from fastmcp.skills.provider import SkillCatalogProvider+ from fastmcp.utilities.skills import download_skill, list_skills, sync_skills++ server = FastMCP("Skills", providers=[SkillCatalogProvider([REVIEW])])+ async with Client(server) as client:+ with pytest.warns(FastMCPDeprecationWarning, match=r"client\.list_skills"):+ (summary,) = await list_skills(client)+ with pytest.warns(FastMCPDeprecationWarning, match="to_directory"):+ downloaded = await download_skill(client, "review", tmp_path / "a")+ with pytest.warns(FastMCPDeprecationWarning, match="read_skill"):+ (synced,) = await sync_skills(client, tmp_path / "b")+ assert summary.name == "review"+ assert Skill.from_directory(downloaded) == REVIEW+ assert Skill.from_directory(synced) == REVIEW++def test_alpha_only_helper_is_gone():import fastmcp.utilities.skills as helpersassert not hasattr(helpers, "list_skill_summaries")+def test_41_wire_model_spellings_build_an_mcp_skill():+ from fastmcp.skills import MCPSkill+ from fastmcp.skills import Skill as Skill41++ entry = {+ "uri": "skill://review/SKILL.md",+ "frontmatter": {"name": "review", "description": "Review changes"},+ "resources": "dynamic",+ }+ with pytest.warns(FastMCPDeprecationWarning, match=r"MCPSkill\(") as record:+ # The 4.1 spelling no longer type-checks; it only has to keep running.+ built = Skill41(**entry) # ty: ignore[invalid-argument-type]+ assert record[0].filename == __file__+ with pytest.warns(FastMCPDeprecationWarning, match=r"MCPSkill\.model_validate"):+ parsed = Skill41.model_validate(entry)+ with pytest.warns(FastMCPDeprecationWarning, match="fastmcp.skills.models.Skill"):+ from fastmcp.skills.models import Skill as ModelsSkill+ assert built == parsed == MCPSkill.model_validate(entry)+ assert ModelsSkill is MCPSkill+ # The authoring constructor is untouched.+ assert isinstance(REVIEW, Skill)+++async def test_list_skill_resources_reaches_a_41_style_server(tmp_path: Path):+ from fastmcp.server.providers.skills import (+ SkillsDirectoryProvider as OldDirectoryProvider,+ )++ REVIEW.to_directory(tmp_path / "review")+ with pytest.warns(FastMCPDeprecationWarning):+ provider = OldDirectoryProvider(tmp_path)+ async with Client(FastMCP("Skills", providers=[provider])) as client:+ (resource,) = await client.list_skill_resources()+ skill = await client.read_skill(str(resource.uri))+ assert skill == REVIEW++def test_experimental_skills_refuses_subclasses(tmp_path: Path):from fastmcp.server.providers.skills import (SkillsDirectoryProvider as OldDirectoryProvider,diff --git a/tests/utilities/test_skills.py b/tests/utilities/test_skills.pyindex 90c6f5726..ef4cb09ff 100644--- a/tests/utilities/test_skills.py+++ b/tests/utilities/test_skills.py@@ -1,4 +1,4 @@-"""Tests for skills client utilities."""+"""Tests for the deprecated skills client utilities."""from __future__ import annotations@@ -11,6 +11,7 @@ import pytestfrom mcp_types import BlobResourceContents, TextResourceContentsfrom fastmcp import Client, FastMCP+from fastmcp._warnings import FastMCPDeprecationWarningfrom fastmcp.server.providers.skills import SkillsDirectoryProviderfrom fastmcp.utilities.skills import (SkillFile,@@ -22,6 +23,11 @@ from fastmcp.utilities.skills import (sync_skills,)+# Every helper here is deprecated; `TestDeprecation` checks the warnings.+pytestmark = pytest.mark.filterwarnings(+ "ignore::fastmcp._warnings.FastMCPDeprecationWarning"+)+class FakeResourceReader:def __init__(@@ -101,6 +107,26 @@ def skills_server(skills_dir: Path) -> FastMCP:return mcp+class TestDeprecation:+ @pytest.mark.filterwarnings("default::fastmcp._warnings.FastMCPDeprecationWarning")+ async def test_each_helper_warns_once_with_its_replacement(+ self, skills_server: FastMCP, tmp_path: Path+ ):+ async with Client(skills_server) as client:+ with pytest.warns(FastMCPDeprecationWarning, match=r"client\.list_skills"):+ await list_skills(client)+ with pytest.warns(FastMCPDeprecationWarning, match=r"client\.get_skill"):+ await get_skill_manifest(client, "pdf-processing")+ with pytest.warns(FastMCPDeprecationWarning, match="to_directory") as one:+ await download_skill(client, "pdf-processing", tmp_path / "one")+ with pytest.warns(FastMCPDeprecationWarning) as record:+ await sync_skills(client, tmp_path / "all")+ assert len(one) == 1+ assert len(record) == 1+ assert one[0].filename == record[0].filename == __file__+ assert "4.3" in str(record[0].message)++class TestListSkills:async def test_lists_available_skills(self, skills_server: FastMCP):async with Client(skills_server) as client: