prompts/docs/contracts/uris.md

icon

icon
lucide/link

URI Contract

This page defines the public resource URI contract for native skills, registry-backed prompts, and general authored documentation.

Native Skill URIs

The FastMCP Skills Provider publishes each skill through the skill:// scheme:

1. skill://<skill-name>/SKILL.md
2. skill://<skill-name>/_manifest
3. skill://<skill-name>/<supporting-path>

The first two are concrete resources returned by resources/list. Supporting files use a per-skill wildcard resource template when the provider is configured with supporting_files="template":

skill://<skill-name>/{path*}

Main File

skill://<skill-name>/SKILL.md returns the canonical authored skill document. The skill directory name supplies <skill-name>, and the resource description comes from SKILL.md frontmatter.

Manifest

skill://<skill-name>/_manifest returns JSON containing the skill name and every file beneath its directory. Each file entry includes:

1. relative POSIX path
2. byte size
3. SHA256 hash

Clients read the manifest before requesting supporting files. FastMCP client utilities such as list_skills() and get_skill_manifest() understand this contract directly.

Supporting Files

Supporting files retain their real skill-relative paths. For example:

skill://pytesting/references/pytest-docs.md

FastMCP confines reads to the selected skill directory. Absolute paths, traversal outside the directory, missing files, directories, and symlinks that resolve outside the skill root are rejected.

Prompt And Docs URIs

Prompts and general documentation retain the existing registry-backed resource surface:

1. resource://catalog/prompts_index
2. resource://catalog/prompts_index{?q,tag,cursor,limit}
3. resource://catalog/prompts/{prompt_id}
4. resource://prompts/{prompt_id}/document
5. resource://docs/{path*}

Prompt ids remain lowercase kebab-case. The docs wildcard accepts normalized relative POSIX Markdown paths beneath docs/ and rejects absolute paths, traversal segments, backslashes, and non-Markdown targets.

Discovery Order

For skills:

1. list resources or call FastMCP list_skills()
2. select a skill by name and description
3. read skill://<skill-name>/SKILL.md
4. read _manifest when supporting material may be needed
5. fetch only the supporting paths relevant to the task

For prompts, use the prompt catalog or MCP prompt-object APIs.

Compatibility Policy

The native skill:// family directly replaces the repository's former custom skill URI and catalog surfaces. No compatibility aliases or dual registrations are maintained. Prompt and general-doc URIs are unaffected.

Skill renames are breaking because the directory name is part of every native skill URI. Supporting-file renames change the corresponding manifest path and URI.

Sources

1. FastMCP Skills Provider
2. MCP resources
3. RFC 3986 URI syntax
4. RFC 6570 URI templates