Skip to content

[Bug] Skills with non-ASCII directory names are listed but unreadable; space-containing names silently disappear #5819

Closed as not planned

Description

@BlueX888

[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:

  1. Non-ASCII directory name. resources/list advertises skill://caf%C3%A9/SKILL.md and skill://caf%C3%A9/_manifest, but every read of those exact advertised URIs raises Resource not found. Template reads of supporting files fail as well.
  2. Space in the directory name. AnyUrl("skill://my skill/SKILL.md") raises ValidationError: ... invalid domain character inside _list_resources. With the default provider_error_strategy="warn" (server/providers/aggregate.py:85) the whole skill is dropped from resources/list with only a log warning, while its template still leaks into templates/list as the invalid URI skill://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

  1. added
    bugSomething isn't working. Reports of errors, unexpected behavior, or broken functionality.
    providerRelated to the FastMCP Provider class
    on Oct 18, 2026
  2. zzstoatzz commented on Nov 10, 2026

    @zzstoatzz
    Collaborator

    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 like café and my skill as 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working. Reports of errors, unexpected behavior, or broken functionality.providerRelated to the FastMCP Provider class

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions