ext-skills/docs/skill-uri-scheme.md

# Skill URI Scheme Proposal

> Proposed convention for identifying skill resources over MCP.

**Issue:** [#44](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/44)
**Status:** Incorporated into the draft [Skills Extension SEP](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/69), now submitted to the MCP spec as [SEP-2640](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640). This survey informed the SEP's URI scheme design; see also [PR #70](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/70) for subsequent refinements (multi-segment paths, path-name decoupling).

---

## Summary

This document surveys existing URI patterns for skill resources across implementations, analyzes their trade-offs, and proposes a recommended `skill://` URI scheme for skill resources over MCP.

## Survey of Existing Patterns

### 1. NimbleBrain: `skill://server-name/skill-name`

**Pattern:** `skill://{authority}/{path}`

NimbleBrain uses `skill://` URIs where the authority segment identifies the server or domain, and the path identifies the skill within that server.

```
skill://ipinfo/usage
```

Skills are registered as MCP resources using FastMCP's `@mcp.resource()` decorator. The server instructions direct the agent to read the skill resource before using tools:

```python
mcp = FastMCP("IPInfo", instructions=(
    "Before using IPInfo tools, read the skill://ipinfo/usage resource "
    "for tool selection guidance and context reuse patterns."
))

@mcp.resource("skill://ipinfo/usage")
def ipinfo_skill() -> str:
    return SKILL_CONTENT
```

**Discovery:** Via `resources/list` — skills appear alongside other resources.

**Pros:**
- Clean, human-readable URIs
- Authority segment naturally scopes skills to a server
- Already deployed in production across multiple servers ([mcp-ipinfo](https://github.com/NimbleBrainInc/mcp-ipinfo), [mcp-webfetch](https://github.com/NimbleBrainInc/mcp-webfetch), [mcp-pdfco](https://github.com/NimbleBrainInc/mcp-pdfco), [mcp-folk](https://github.com/NimbleBrainInc/mcp-folk), [mcp-brave-search](https://github.com/NimbleBrainInc/mcp-brave-search))
- Skills colocated with the tools they describe — versioned and shipped atomically
- Ephemeral availability: context present while server is connected, gone when disconnected

**Cons:**
- Authority segment usage varies across implementations (server name vs. skill name)
- No versioning in the URI
- No formal convention for sub-resources (references, scripts)
- Departs from the Agent Skills spec model where a skill is a directory containing at least `SKILL.md` — skills are exposed as flat, opaque resources with no directory structure

### 2. skilljack-mcp: `skill://{skillName}` with directory collections

**Pattern:** `skill://{skillName}` (no authority)

Skilljack uses `skill://` URIs where the skill name is placed directly after the scheme, without an authority segment. It also defines a directory collection pattern using a trailing slash:

```
skill://code-style              # SKILL.md content
skill://code-style/             # All files in skill directory (collection)
skill://code-style/reference.md # Individual file (accessed via tool, not listed)
```

**Discovery:** Via `resources/list` with resource templates (`skill://{skillName}`). Includes `_meta` annotations for skill metadata.

**Pros:**
- Simple, minimal URIs for the common case
- Directory collection pattern (`/`) efficiently bundles all files
- Resource templates enable auto-completion via MCP's completion API
- Separates listed resources from tool-accessible files to reduce noise

**Cons:**
- No authority segment means no built-in scoping across multiple servers
- Skill names must be globally unique within a client session
- `SKILL.md` is implicit in the base URI (`skill://code-style`) — diverges from the Agent Skills spec directory model where `SKILL.md` is an explicit file within the skill directory

### 3. skills-over-mcp: `skill://{skillName}` with index and templates

**Pattern:** `skill://{skillName}` plus well-known index URIs

Keith Groves' implementation uses a richer set of `skill://` URIs including an index resource and lookup templates:

```
skill://index                           # JSON listing all skills
skill://prompt-xml                      # XML for system prompt injection
skill://code-review                     # Skill SKILL.md content
skill://code-review/documents           # JSON list of supporting documents
skill://code-review/document/SECURITY.md  # Individual document
skill://lookup/{name}                   # Dynamic lookup by name (template)
```

**Discovery:** Via `skill://index` resource (returns JSON array of all skills with URIs) and `resources/list`.

**Pros:**
- Index resource provides structured discovery separate from `resources/list`
- Document sub-paths provide progressive disclosure
- Resource templates with completion support enable dynamic lookup
- XML prompt injection resource for system prompt integration

**Cons:**
- Multiple overlapping discovery mechanisms (index + lookup template + resources/list)
- More complex URI space to learn and implement
- No authority segment
- `SKILL.md` is implicit in the base URI (`skill://code-review`) — diverges from the Agent Skills spec directory model

### 4. FastMCP 3.0: `skill://{skillName}/SKILL.md` with manifest

**Pattern:** `skill://{skillName}/{filePath}`

FastMCP 3.0 uses a file-path-based URI structure where every file within a skill directory gets its own URI, including a synthetic manifest:

```
skill://pdf-processing/SKILL.md        # Main instruction file
skill://pdf-processing/_manifest       # Synthetic JSON manifest (sizes + SHA-256)
skill://pdf-processing/reference.md    # Supporting file
skill://pdf-processing/examples/sample.pdf  # Nested supporting file
```

**Discovery:** Via `resources/list` (configurable disclosure level). Client utilities (`list_skills`, `download_skill`, `sync_skills`) provide higher-level access.

**Pros:**
- File-path structure is intuitive and predictable
- Most compatible with the Agent Skills spec model — URIs directly reflect the directory structure (`skill://name/SKILL.md`, `skill://name/references/...`)
- Manifest with SHA-256 hashes enables integrity verification
- Configurable disclosure: `"template"` (minimal listing) vs. `"resources"` (all files listed)
- SDK-level utilities for listing, downloading, and syncing skills
- Built-in providers for multiple skill directory conventions (Claude, Cursor, Codex, VS Code)

**Cons:**
- `SKILL.md` is always explicit in the URI (more verbose for the common case)
- File-path structure couples the URI to the internal directory layout
- No authority segment for multi-server scoping

### 5. Agent Skills Discovery RFC: `/.well-known/skills/{name}/SKILL.md`

**Pattern:** HTTPS URLs under `/.well-known/skills/`

The Cloudflare RFC defines domain-level discovery via HTTP, not a custom URI scheme. Skills are regular HTTPS resources at well-known paths:

```
https://example.com/.well-known/skills/index.json
https://example.com/.well-known/skills/wrangler/SKILL.md
https://example.com/.well-known/skills/wrangler/scripts/deploy.sh
```

**Discovery:** Fetch `/.well-known/skills/index.json` which lists all skills with name, description, and file inventory.

**Pros:**
- No custom URI scheme — uses standard HTTPS
- Domain-level trust model (organizational identity)
- Progressive disclosure built into the spec (3 levels)
- File inventory in index enables prefetching and caching
- Complementary to MCP (discovery and distribution vs. runtime consumption)

**Cons:**
- Not an MCP resource URI scheme — designed for HTTP-level discovery
- Requires organizations to host web endpoints
- Not directly usable as an MCP resource URI

### 6. SEP-2076: `skills/list` and `skills/get`

**Pattern:** New protocol primitive, not URI-based

SEP-2076 proposes skills as a first-class MCP primitive with dedicated methods rather than a URI scheme:

```json
// skills/list response
{
  "skills": [{
    "name": "git-workflow",
    "description": "Follow team Git conventions",
    "tags": ["git", "workflow"]
  }]
}

// skills/get request
{ "name": "git-workflow" }
```

**Discovery:** Via `skills/list` method (dedicated, not via `resources/list`).

**Pros:**
- Clean separation from other resource types
- Dedicated capability and notification support
- No URI collision concerns

**Cons:**
- Requires protocol-level changes (new methods, capabilities)
- Adds a new primitive when resources may suffice
- Not yet accepted into the MCP spec
- Flattens skills to a name-addressed blob — does not model the Agent Skills spec's directory structure (skill as a directory containing `SKILL.md` plus optional supporting files)

## Comparison Matrix

| Pattern | URI Scheme | Authority | Versioning | Sub-resources | Templates | MCP-native |
|---------|-----------|-----------|------------|---------------|-----------|------------|
| NimbleBrain | `skill://` | Server name | No | No | No | Yes |
| skilljack-mcp | `skill://` | None | No | `/` collection | Yes | Yes |
| skills-over-mcp | `skill://` | None | No | `/document/` path | Yes | Yes |
| FastMCP 3.0 | `skill://` | None | No | File paths | Configurable | Yes |
| Well-Known RFC | `https://` | Domain | No | File paths | N/A | No |
| SEP-2076 | N/A | N/A | N/A | N/A | N/A | New primitive |

## Analysis

### Points of Convergence

All MCP-native implementations have independently converged on `skill://` as the URI scheme. This is a strong signal — four independent implementations chose the same scheme without coordination.

The divergence is in URI structure, specifically:

1. **Authority segment**: NimbleBrain uses it (server name); all others omit it.
2. **Path structure**: Ranges from minimal (`skill://name`) to file-path-based (`skill://name/SKILL.md`).
3. **Sub-resource access**: Different patterns for accessing supporting files.
4. **Discovery**: Some use `resources/list` alone; others add index resources or templates.

### Key Design Decisions

**1. What goes in the authority segment?**

In RFC 3986, the authority component (`scheme://authority/path`) is semantically a host identifier. A skill directory path is not a host. However, all four existing MCP implementations use the double-slash form, placing the first path segment in the authority position. While not semantically precise, this is established practice, produces clean URIs, and works well with MCP-aware parsers that don't need to resolve the authority as a network host.

**Recommendation:** Use the double-slash form (`skill://...`). The first segment of the skill path occupies the authority position by RFC 3986 mechanics but carries no special semantics under this convention — it is just the first path segment. Clients MUST NOT attempt DNS or network resolution of it. This avoids the awkward triple-slash (`skill:///`) form while staying honest about what the segment means.

**2. Should `SKILL.md` be explicit in the URI?**

FastMCP includes `SKILL.md` in every skill content URI. Other implementations treat the skill name itself as the content URI, with `SKILL.md` implicit.

Making `SKILL.md` explicit mirrors the directory structure and aligns with the Agent Skills spec, which defines a skill as a directory containing at least `SKILL.md`. Omitting it creates an abstraction that diverges from the spec and makes the relationship between the URI and the underlying skill format ambiguous.

**Recommendation:** `SKILL.md` MUST be explicit in the URI. The primary skill content is always at `skill://<skill-path>/SKILL.md`. This keeps the URI structure aligned with the Agent Skills spec and makes the directory model visible. Sub-resources are siblings at the same level (e.g., `skill://<skill-path>/references/GUIDE.md`).

**3. How should sub-resources (references, scripts) be addressed?**

Multiple patterns exist: trailing-slash collections (skilljack), `/document/` subpath (skills-over-mcp), direct file paths (FastMCP), and no sub-resource support (NimbleBrain).

**Recommendation:** Use path-based sub-resource addressing for consistency with other URI schemes.

**4. Should the URI path equal the skill name?**

Early drafts coupled the two: one path segment, equal to the frontmatter `name`. That works for a server with a handful of skills but fails when a server needs hierarchy. A large organization serving both `acme/billing/refunds` and `acme/support/refunds` cannot satisfy "single segment" and "segment equals name" simultaneously without renaming one skill to dodge the collision — which defeats the point of having a hierarchy. It also fails for servers with generated skill catalogs where the navigational axes (product, version, API surface) are orthogonal to what the skill is called.

**Recommendation:** Decouple. `<skill-path>` is a locator — one or more `/`-separated segments locating the skill directory within the server's namespace. The skill's identity (its `name`) lives in `SKILL.md` frontmatter and follows the Agent Skills spec naming rules. The URI says where to find it; the frontmatter says what it is.

## Proposed Convention

### URI Scheme: `skill://`

All skill resources MUST use the `skill://` URI scheme.

### URI Structure

```
skill://<skill-path>/SKILL.md
skill://<skill-path>/<file-path>
```

Following [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) structure:

- **Scheme:** `skill`
- **Authority:** The first segment of `<skill-path>`. Carries no special semantics; clients MUST NOT resolve it as a network host.
- **Path:** Remaining `<skill-path>` segments (if any) followed by `<file-path>`.

Where:

- `<skill-path>` is a `/`-separated path of one or more segments locating the skill directory within the server's namespace. MAY be a single segment (`git-workflow`) or nested to arbitrary depth (`acme/billing/refunds`). A `SKILL.md` MUST NOT appear in an ancestor directory of another `SKILL.md` — skills do not nest inside other skills.
- `<file-path>` is the file's path relative to the skill directory root, always `SKILL.md` for the primary content.

### Naming Rules

`<skill-path>` segments SHOULD be valid URI path segments per RFC 3986. No further constraints are imposed on the path — it is the server's organizational choice.

The skill's `name` (in `SKILL.md` frontmatter) is governed by the [Agent Skills specification naming rules](https://agentskills.io/specification#name-field): 1–64 characters, lowercase alphanumeric and hyphens, no leading/trailing or consecutive hyphens. The path is not required to match it.

### URI Patterns

#### Flat skill path

```
skill://git-workflow/SKILL.md
```

Single-segment path. The primary skill content is always at `SKILL.md` within the skill's path, matching the Agent Skills spec directory model.

#### Nested skill path

```
skill://acme/billing/refunds/SKILL.md
```

Multi-segment path. The skill directory is `acme/billing/refunds`; `acme` and `billing` are organizational path segments, not skills. The frontmatter `name` inside this `SKILL.md` might be `refund-handling` — it is independent of the path.

#### Sub-resources

```
skill://pdf-processing/SKILL.md                       # Primary skill content (required)
skill://pdf-processing/references/FORMS.md            # Supporting document
skill://acme/billing/refunds/templates/email.md       # Supporting file in nested skill
```

Supporting files are addressed by appending their path relative to the skill directory.

#### Resource templates

```
skill://docs/{product}/SKILL.md              # Per-product documentation skills
skill://acme/{domain}/{workflow}/SKILL.md    # Nested organizational namespace
skill://{skill_path}/{+file}                 # Generic: any file in any skill
```

Servers MAY register resource templates with `skill://` URI templates. These are primarily a user-facing discovery mechanism: hosts surface them in the UI with template variables wired to MCP's completion API, letting users interactively browse and select skills.

### Examples

| Use Case | URI | Notes |
|----------|-----|-------|
| Flat path | `skill://git-workflow/SKILL.md` | Single-segment skill path |
| Nested path | `skill://acme/billing/refunds/SKILL.md` | Path is locator; `name` is in frontmatter |
| Supporting document | `skill://code-review/references/SECURITY.md` | Sub-resource within skill directory |
| Supporting file, nested | `skill://acme/billing/refunds/templates/email.md` | Sub-resource in nested skill |

### How Clients Identify Skills

Clients can identify skill resources by:

1. **URI scheme:** Resources with URIs starting with `skill://` are skill resources.
2. **Entry point:** A URI ending in `/SKILL.md` is the skill's entry point; stripping that suffix gives the skill directory.
3. **MIME type:** `SKILL.md` content SHOULD use `text/markdown`.
4. **Annotations:** Servers MAY use the `_meta` field for additional skill metadata.

Enumeration via `resources/list` is optional. A `skill://` URI is directly readable via `resources/read` whether or not it appears in any list; clients MUST NOT treat an empty or absent enumeration as proof that a server has no skills.

### MCP Spec Alignment

The `skill://` scheme is a custom URI scheme as permitted by the MCP specification:

> Custom URI schemes **MUST** be in accordance with [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986).

The proposed scheme follows RFC 3986 structure. It uses existing MCP primitives (`resources/list`, `resources/read`, resource templates, subscriptions) without requiring protocol changes.

### Versioning

Versioning in URIs (e.g., query parameters or path segments) is intentionally deferred. The current convention focuses on establishing the base URI structure. Skill versioning is implicitly tied to the server version — when a server updates, its skill content updates with it.

### Multi-Server URI Collision

Since MCP resources are scoped per-server, identical `skill://` URIs from different servers are distinguishable by their originating server connection. With decoupled paths, the same `<skill-path>` appearing on two servers is less likely than a `name` collision would have been, but still possible.

Clients SHOULD provide a `read_resource` tool that accepts both the server name and the skill resource URI, allowing the model to disambiguate which server's skill to read. Within a skill's `SKILL.md` body, references to sub-resources (e.g., `references/GUIDE.md`) are relative to the skill — similar to how file-based skills use relative paths today. The model can resolve these from context, knowing which server the skill originated from.

Servers MAY include provenance metadata in `_meta` to make origin explicit.

## References

- [MCP Resources specification](https://modelcontextprotocol.io/specification/2025-11-25/server/resources)
- [RFC 3986: URIs](https://datatracker.ietf.org/doc/html/rfc3986)
- [RFC 6570: URI Templates](https://datatracker.ietf.org/doc/html/rfc6570)
- [Agent Skills specification](https://agentskills.io/specification)
- [Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc)
- [NimbleBrain skill:// findings](experimental-findings.md#nimblebrain-skill-resource-consolidation)
- [Approach 6: Official Convention](approaches.md#6-official-convention-as-intermediate-step)