83 lines
3.1 KiB
Markdown
83 lines
3.1 KiB
Markdown
---
|
|
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](https://gofastmcp.com/servers/providers/skills) 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"`:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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](https://gofastmcp.com/servers/providers/skills)
|
|
2. [MCP resources](https://modelcontextprotocol.io/specification/latest/server/resources)
|
|
3. [RFC 3986 URI syntax](https://www.rfc-editor.org/rfc/rfc3986)
|
|
4. [RFC 6570 URI templates](https://www.rfc-editor.org/rfc/rfc6570)
|