Repository navigation
Description
[Bug] Skills with non-ASCII directory names are listed but unreadable; space-containing names silently disappear
Summary
SkillProvider uses the skill directory name verbatim as the host segment of skill:// URIs (fastmcp_slim/fastmcp/server/providers/skills/skill_provider.py:290-292, 304, 323-325):
uri=AnyUrl(f"skill://{skill.name}/{quote(self._main_file_name, safe='/')}")
uri=AnyUrl(f"skill://{skill.name}/_manifest")Pydantic's AnyUrl percent-encodes non-ASCII hosts (café -> caf%C3%A9) and rejects a space outright. The read path never decodes that segment: _get_resource splits the path and compares the first segment raw against skill.name (skill_provider.py:352), unquoting only the file segment (:354); _get_resource_template repeats the raw comparison at :431.
Two user-visible consequences:
- Non-ASCII directory name.
resources/listadvertisesskill://caf%C3%A9/SKILL.mdandskill://caf%C3%A9/_manifest, but every read of those exact advertised URIs raisesResource not found. Template reads of supporting files fail as well. - Space in the directory name.
AnyUrl("skill://my skill/SKILL.md")raisesValidationError: ... invalid domain characterinside_list_resources. With the defaultprovider_error_strategy="warn"(server/providers/aggregate.py:85) the whole skill is dropped fromresources/listwith only a log warning, while its template still leaks intotemplates/listas the invalid URIskill://my skill/{path*}.
This contradicts the documented behavior in docs/servers/providers/skills.mdx: "Each subdirectory containing a SKILL.md file becomes a discoverable skill" (line 34) and "The directory name becomes the skill's identifier" (line 52), with no character restrictions. Existing percent-encoding round-trip tests only cover the file-name segment (test_read_supporting_file_with_space_in_name, test_read_supporting_file_with_utf8_name, from #4545), always under ASCII skill directory names — so the file-segment contract is already intended, and only the skill-name segment diverges from it.
Repro
# repro_skills.py
import asyncio
import tempfile
from pathlib import Path
from fastmcp import Client, FastMCP
from fastmcp.server.providers.skills import SkillsDirectoryProvider
async def main() -> None:
root = Path(tempfile.mkdtemp())
for name in ("café", "my skill", "good"):
skill_dir = root / name
skill_dir.mkdir()
(skill_dir / "SKILL.md").write_text(f"# {name}\n", encoding="utf-8")
mcp = FastMCP("skills-repro")
mcp.add_provider(SkillsDirectoryProvider(roots=root))
async with Client(mcp) as client:
resources = await client.list_resources()
print("listed resources:")
for r in resources:
print(f" name={r.name!r} uri={str(r.uri)!r}")
print("'my skill' listed:", any(r.name.startswith("my skill") for r in resources))
print("reads:")
for r in resources:
if str(r.uri).startswith("skill://caf"):
try:
contents = await client.read_resource(r.uri)
print(f" {r.uri!s} -> OK: {contents[0].text!r}")
except Exception as exc:
print(f" {r.uri!s} -> {type(exc).__name__}: {exc}")
contents = await client.read_resource("skill://good/SKILL.md")
print(f" skill://good/SKILL.md -> OK: {contents[0].text!r}")
print("templates:")
for t in await client.list_resource_templates():
print(f" {t.uri_template!r}")
if __name__ == "__main__":
asyncio.run(main())ACTUAL output
listed resources:
name='café/SKILL.md' uri='skill://caf%C3%A9/SKILL.md'
name='café/_manifest' uri='skill://caf%C3%A9/_manifest'
name='good/SKILL.md' uri='skill://good/SKILL.md'
name='good/_manifest' uri='skill://good/_manifest'
'my skill' listed: False
reads:
skill://caf%C3%A9/SKILL.md -> MCPError: Resource not found: 'skill://caf%C3%A9/SKILL.md'
skill://caf%C3%A9/_manifest -> MCPError: Resource not found: 'skill://caf%C3%A9/_manifest'
skill://good/SKILL.md -> OK: '# good\n'
templates:
'skill://café/{path*}'
'skill://good/{path*}'
'skill://my skill/{path*}'
Alongside the my skill warning:
WARNING Error during list_resources from provider SkillProvider(skill_path=.../'my skill', supporting_files='template'): 1 validation error for function-wrap[wrap_val()]
Input should be a valid URL, invalid domain character
[type=url_parsing, input_value='skill://my skill/SKILL.md', input_type=str]
Expected: every URI advertised by the provider round-trips through read_resource (as the file segment already does), and a skill directory whose name contains a space is still listed and readable.
Suggested fix direction
Percent-encode the skill name when constructing skill:// URIs, and unquote the first path segment before comparing it to skill.name in both _get_resource and _get_resource_template — mirroring the existing file-segment handling.
Environment: origin/main at 7f3c53eadf6bb1b7194e00c42551e4db380b3f67.
Activity
zzstoatzz commentedon Nov 10, 2026
Thanks for the report and the fix in #5820. The 4.x skills provider this targets is deprecated for removal in 4.3, and its replacement,
SkillsDirectoryProvider, rejects folder names likecaféandmy skillas invalid Agent Skills names; the deprecation warning lists folders to rename. Rename those skill folders to valid names. Closing this and #5820 rather than extending support for names the replacement refuses.