4.2.0
A skill is a SKILL.md of instructions plus whatever files it points to. Most agents load skills from a local folder, which means every laptop has its own copy and none of them agree. Put the skills on an MCP server instead: one copy, and an update ships when you deploy.
skill://release-notes/SKILL.md and template.md directly. Clients that speak the Skills extension can also call skills/list and get each skill’s description and a hashed manifest of its files, so a host can offer the skill without an install step. Few hosts do yet (VS Code 1.146 has it in preview), and FastMCP’s support is experimental, but you get both from the same provider. For clients that only call tools, see Clients that only call tools. Run fastmcp list server.py --skills to see what you’re serving.
Where skills come from
ASkill is a value: a name, a description, instructions, and the files they refer to. It doesn’t know where it came from or which URI it is served under. Build one in Python as above, or load what you already have on disk or in a package:
Skill.from_files() takes a mapping of relative paths to contents when the files are already in memory.
Skills are validated when you build them and never change afterward; editing the folder later doesn’t touch the loaded skill. The description is what an agent reads to decide whether to use the skill, so make it say when.
SkillCatalogProvider serves the skills you hand it. When the set of skills changes at runtime, override load_skills() instead and build the skills from wherever they live. FastMCP calls it once per request. Rows in a database are a fine source: the columns become the skill’s fields, and no file is involved.
Skill holds the bytes of every file, so a catalog of large skills is a lot to keep in memory. When the files already live somewhere else, such as object storage, subclass SkillManifestProvider instead. Discovery only needs each skill’s frontmatter and the digest and size of each file, which a SkillManifest holds. FastMCP calls read_file() only when a client reads that file.
load_skills(), load_manifests() runs once per request. Clients check what they read against the manifest, so read_file() must return exactly the bytes each digest describes, and the frontmatter in SKILL.md must match the manifest’s.
To serve a folder of skills, point SkillsDirectoryProvider at it. Every subfolder with a SKILL.md becomes a skill, served at its path below the root, so ops/deploy/SKILL.md becomes skill://ops/deploy/SKILL.md. A coding agent’s own skills folder works the same way:
SKILL.md must follow the Agent Skills spec: YAML frontmatter with a description and a name of lowercase letters, digits and hyphens that matches its folder. A folder that breaks the rules stops the server at startup with an error naming the fix for each one, so a server never comes up quietly missing skills. Hidden folders such as .git are skipped. Pass several roots and the first one wins when two contain the same path. The provider reads the folders once at startup; pass reload=True to re-read them on every request while you’re editing a skill. If a re-read finds a broken folder, the error is logged and the last valid skills keep serving until you fix it.
Access control
Discovery never shows a skill the caller can’t read. If any of its files is hidden, denied bycheck_resource_access (what AuthMiddleware uses), or shadowed by another resource, the skill drops out of skills/list.
Mounted servers
Skills come along when you mount a server, at the URIs the parent serves them at:mount(child, namespace="team") turns skill://review/ into skill://team/review/. If you’d rather choose exactly which providers are discoverable, register the extension yourself with mcp.add_extension(SkillsExtension(providers=[...])) from fastmcp.skills.extension.
Proxied servers
A proxy passes a backend’s skill files through as resources, but it can’t know whether the backend speaks the Skills extension, so discovery is opt-in. Passskills=True and the proxying server’s skills/list includes the backend’s skills alongside its own:
ProxyClient factory needs mode="auto" to negotiate the modern protocol used by Skills. Directly constructed ProxyClient instances default to the legacy handshake. create_proxy(..., skills=True) handles protocol mirroring for you.
Backend entries pass through unchanged, and the same access rules apply: a skill shows up only if the gateway serves every one of its files from that backend to that caller. A backend without the Skills extension contributes nothing. To namespace a backend’s skills, mount a proxy instead:
provider_error_strategy: the default "warn" logs a failing source and keeps healthy skills available. Set gateway.provider_error_strategy = "raise" to fail the operation when a source fails.
Clients that only call tools
Many MCP clients never show resources to the model, but nearly all of them call tools. Add theResourcesAsTools transform and the server also exposes list_resources and read_resource tools, which list and read the same skill:// files:
list_resources, though; a host that supports skills loads them for it. For agents that only load skills from a folder, install them instead.
Read skills from a client
Discover skills with the Skills extension
Opt the client into the extension and ask:ClientGroup.list_skills() does the same across several servers.
Read a whole skill
read_skill() fetches every file in the skill’s manifest, checks each one’s size and SHA-256 digest, and returns a Skill. When the extension supplies an entry, the downloaded frontmatter must also match it. The 512-file and 16 MiB limits are checked before downloading file contents. It uses skills/get when the extension was negotiated, falling back to FastMCP’s _manifest resource when the extension is unavailable or doesn’t know the skill:
SkillCatalogProvider on another server or write it to disk with skill.to_directory(path).
Install skills into a local agent
Most agents still only read skills from disk. List a server’s skills, read each one, and write it into the agent’s folder: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 server-level transform that renames or hides a skill’s files, like
Namespace, leaves that skill out, since its entry would name URIs the server no longer serves; mount a server instead. Transforms that only add tools, likeResourcesAsTools, are fine. - A proxied skill whose manifest is
"dynamic"is left out, since the gateway can’t check its files. directoryReadisn’t implemented.
Moving off the 4.1 skills API
The providers infastmcp.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.
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.
For manifest metadata alone, read the _manifest resource and parse its JSON; this does not require the Skills extension, download the skill’s files, or validate their frontmatter. client.get_skill(uri) requires the extension, while client.read_skill(uri) downloads and validates the whole skill.
Existing Pydantic fields annotated with the 4.1 Skill spelling still validate wire payloads as MCPSkill, and wire entries still satisfy isinstance(entry, Skill). Change wire-model annotations and checks to MCPSkill before 4.3. File-serving providers require authored Skill values containing the actual files, so passing a wire entry to SkillCatalogProvider remains an error.