You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs(skills): point SKILL.md files at SEP-2640 and cover archive distribution
Repoint the Skills Extension SEP reference from the experimental-ext-skills
working draft (#69) to the canonical SEP-2640 (modelcontextprotocol#2640) in
both the host and server implementation skills, and remove the "this link
will change" caveat.
Server skill: expand the Archive distribution section to declare the
`type: "archive"` index entry shape, MIME types, archive-root + path-traversal
producer constraints, and the URL-suffix-stripping rule that derives the
host-facing `skill://<path>/` namespace from `skill://<path>.tar.gz|.zip`.
Host skill: add an Archive index entries gotcha — hosts walking only
`type: "skill-md"` will silently drop archive entries; cover dual
`.tar.gz`/`.zip` support keyed off mimeType with URL-suffix fallback,
archive-safety validation (traversal, absolute paths, escaping links,
decompression-bomb size cap), and post-unpack namespace identity.
Also fix a `.mdd` typo in the server skill's reference to skill-meta-keys.md.
Two concerns determine how a host integrates skills over MCP: how it discovers what's available, and how it loads content when the model needs it.
12
11
@@ -38,6 +37,8 @@ Note: Relative-path resolution within a skill MUST be consistent across all opti
38
37
39
38
**Server name in the model's context.** If the host's read tool takes `(server, uri)` (matching the SEP's illustrative `read_resource` signature), the model has to write the server name on each call. The TS SDK's e2e demo found that without the server name visibly placed in the skill catalog block, model first-call activation fell from ~90% to ~33% — the model either hallucinated the wrong server name or skipped the call entirely. Two ways out: (1) inject the server name into each catalog entry (e.g. `<server>{name}</server>`) so the model has it in context to copy, or (2) drop the `server` argument from the tool entirely and resolve the server host-side from the URI's known origin at discovery time. (2) avoids the failure mode by construction but assumes URIs are unique across connected servers.
40
39
40
+
**Archive index entries.** A host that walks only `type: "skill-md"` entries will silently drop skills declared as `type: "archive"` (a single archive resource that unpacks to the skill directory). Hosts MUST handle both. For archives: support both `.tar.gz` and `.zip`, determining format from the resource's `mimeType` (`application/gzip` or `application/zip`) and falling back to the URL suffix; derive the skill's namespace by stripping the archive suffix from the entry's `url` (`skill://pdf-processing.tar.gz` → `skill://pdf-processing/`); apply archive-safety validation — reject path traversal (`..`), absolute paths, links resolving outside the skill directory, and bound total unpacked size to defend against decompression bombs. After unpacking, files are addressable as `skill://<skill-path>/<file-path>` exactly as they would be under individual-resource distribution; the model-facing namespace is identical.
41
+
41
42
## Reuse your existing resource-read tool
42
43
43
44
If the host already exposes a model-facing resource-read tool, it should in theory needs **zero** changes to support skills — the SEP is a transport binding and skills are just resources. Keep skill-specific guidance in the activated-skill output, not in the tool description.
@@ -46,7 +47,7 @@ If the host already exposes a model-facing resource-read tool, it should in theo
Three concerns determine how an MCP server exposes skills: what URI scheme and structure to use, how to make skills discoverable, and how to distribute multi-file skills. Most authors can accept defaults on all three. This section covers when and why to deviate.
12
+
Three concerns determine how an MCP server exposes skills: what URI scheme and structure to use, how to make skills discoverable, and how to distribute multi-file skills.
14
13
15
14
### URI structure
16
15
@@ -20,12 +19,13 @@ Skills are exposed as MCP resources. Servers SHOULD use the `skill://` URI schem
20
19
21
20
The final segment of `<skill-path>` MUST match the skill's `name` as declared in its `SKILL.md` frontmatter. Preceding segments are a server-chosen organizational prefix — use them if the server has meaningful hierarchy (by team, product, domain, or version), omit them for flat catalogs.
22
21
22
+
Servers MAY serve skills under a domain-native scheme (`github://owner/repo/skills/refunds/SKILL.md`) provided every skill is listed in `skill://index.json`. The structural constraints above (final segment matches name, `SKILL.md` explicit, no skill nesting inside another skill) apply regardless of scheme.
23
+
23
24
| Server shape | Example URI |
24
25
|---|---|
25
26
| Single flat catalog |`skill://git-workflow/SKILL.md`|
Servers MAY serve skills under a domain-native scheme (`github://owner/repo/skills/refunds/SKILL.md`) provided every skill is listed in `skill://index.json`. The structural constraints above (final segment matches name, `SKILL.md` explicit, no skill nesting inside another skill) apply regardless of scheme.
29
29
30
30
### Enumeration
31
31
@@ -65,15 +65,26 @@ Register the same URI as an MCP resource template so hosts can wire the `{produc
65
65
66
66
A skill is a directory: `SKILL.md` plus any supporting files the skill references (additional markdown, scripts, templates, examples). Two ways to distribute these:
67
67
68
-
**Individual resources (default).** Each file is its own `skill://` resource. Simple, composable, and gives hosts fine-grained control over what they fetch and when. Appropriate for most multi-file skills.
68
+
**Individual resources (default).** Each file is its own `skill://` resource (`type: "skill-md"` in the index). Simple, composable, and gives hosts fine-grained control over what they fetch and when. Appropriate for most multi-file skills.
69
+
70
+
**Archive distribution.** For skills with many supporting files, where atomicity across the bundle matters, or where UNIX file metadata (executable bits, symlinks) needs to round-trip, declare the skill as `type: "archive"` in `skill://index.json` with `url` pointing at a single archive resource:
71
+
72
+
```json
73
+
{
74
+
"name": "pdf-processing",
75
+
"type": "archive",
76
+
"description": "Extract and transform PDF documents",
77
+
"url": "skill://pdf-processing.tar.gz"
78
+
}
79
+
```
69
80
70
-
**Archive distribution.** For skills with many supporting files or where atomicity across the bundle matters, the server publishes a single archive resource (`.tar.gz` or `.zip`) that the host unpacks into the skill's URI namespace. The host-facing namespace is identical to individual-file distribution after unpacking.
81
+
The archive MUST be `.tar.gz` (`mimeType: application/gzip`) or `.zip` (`mimeType: application/zip`). `SKILL.md` MUST be at the archive root — no wrapper directory — and the archive MUST NOT contain path-traversal sequences (`..`) or absolute paths. The `<skill-path>`the host exposes is the entry's `url` with the archive suffix stripped: `skill://pdf-processing.tar.gz` unpacks to `skill://pdf-processing/`, `skill://acme/billing/refunds.zip` to `skill://acme/billing/refunds/`. The host-facing namespace is identical to individual-file distribution after unpacking.
71
82
72
-
If you're unsure which to use, start with individual resources. Archive distribution is an optimization for servers shipping pre-built skill bundles or hitting round-trip-count issues with large multi-file skills.
83
+
If you're unsure which to use, always start with individual resources. Archive distribution is an optimization for servers shipping pre-built skill bundles, hitting round-trip-count issues with large multi-file skills, or needing UNIX file metadata that individual-resource distribution can't represent. The trade-off is per-file `resources/subscribe` granularity, which the skill reading model does not depend on.
73
84
74
85
### Metadata
75
86
76
-
Most skill metadata lives in `SKILL.md` YAML frontmatter per the [Agent Skills specification](https://agentskills.io/specification) — that's the authoritative source for skill-level semantics (version, compatibility, allowed tools). See [Using `_meta` for Skill Resources](https://github.com/modelcontextprotocol/experimental-ext-skills/blob/main/docs/skill-meta-keys.mdd) for guidance on when MCP resource `_meta` is appropriate vs. when frontmatter suffices.
87
+
Most skill metadata lives in `SKILL.md` YAML frontmatter per the [Agent Skills specification](https://agentskills.io/specification) — that's the authoritative source for skill-level semantics (version, compatibility, allowed tools). See [Using `_meta` for Skill Resources](https://github.com/modelcontextprotocol/experimental-ext-skills/blob/main/docs/skill-meta-keys.md) for guidance on when MCP resource `_meta` is appropriate vs. when frontmatter suffices.
77
88
78
89
### Updates
79
90
@@ -85,7 +96,7 @@ Skill content changes flow through the generic MCP Resources update mechanism. S
85
96
86
97
The relative link `skill-meta-keys.md` above resolves to the authoritative WG doc on `modelcontextprotocol/experimental-ext-skills@main`.
0 commit comments