Skip to content

Commit 0f7df1f

Browse files
mattzcareytobi-oye
andcommitted
feat: Skills extension for server and client (ext/skills subpaths)
@modelcontextprotocol/server/ext/skills adds SkillsExtension(source): it declares io.modelcontextprotocol/skills and the resources capability, and serves skills/list and skills/get from a SkillSource, plus resources/directory/read (declared as directoryRead) when the source implements readDirectory. Entries are checked against the structural rules of SEP-2640 before they are sent; an invalid one answers -32603. Skill files stay ordinary resources; skillResourceOf computes the digest and size an entry lists for each. @modelcontextprotocol/client/ext/skills adds SkillsClientExtension: list, get and readDirectory, refused unless the server declared support, and read(skill, uri), which fetches a file and verifies it is listed and matches the entry's size and digest. Wire types and schemas live at @modelcontextprotocol/core-internal/ext/skills. The schemas and constants are adapted from #2818. Co-authored-by: tobi-oye <tobiloba5000@gmail.com>
1 parent 09c01f2 commit 0f7df1f

23 files changed

Lines changed: 984 additions & 4 deletions

File tree

‎.changeset/skills-extension.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
'@modelcontextprotocol/core-internal': minor
3+
'@modelcontextprotocol/client': minor
4+
'@modelcontextprotocol/server': minor
5+
---
6+
7+
The MCP Skills extension (`io.modelcontextprotocol/skills`, SEP-2640) as a pair of extensions.
8+
9+
`@modelcontextprotocol/server/ext/skills`: `new SkillsExtension(source)` in `ServerOptions.extensions` declares the extension and the `resources` capability, and serves `skills/list` and `skills/get` from a `SkillSource`, plus `resources/directory/read` (declared as `directoryRead`) when the source implements `readDirectory`. Entries are checked against the specification's structural rules before they are sent. Skill files stay ordinary resources; `skillResourceOf` computes the digest and size an entry lists for each.
10+
11+
`@modelcontextprotocol/client/ext/skills`: `new SkillsClientExtension()` in `ClientOptions.extensions` wraps `list`, `get` and `readDirectory`, each refused unless the server declared support, and `read(skill, uri)`, which fetches a skill file and verifies it is listed and matches the entry's size and digest.
12+
13+
Wire types and zod schemas live at `@modelcontextprotocol/core-internal/ext/skills` and are re-exported from both subpaths.

‎docs/.vitepress/nav.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ export const guideSidebar: DefaultTheme.SidebarItem[] = [
2727
{ text: 'Elicitation', link: '/servers/elicitation' },
2828
{ text: 'Sampling (sunset)', link: '/servers/sampling' },
2929
{ text: 'Input required', link: '/servers/input-required' },
30+
{ text: 'Skills (extension)', link: '/servers/skills' },
3031
{ text: 'Notifications', link: '/servers/notifications' },
3132
{ text: 'Errors', link: '/servers/errors' }
3233
]
@@ -53,6 +54,7 @@ export const guideSidebar: DefaultTheme.SidebarItem[] = [
5354
{ text: 'Handle server requests', link: '/clients/server-requests' },
5455
{ text: 'Roots (sunset)', link: '/clients/roots' },
5556
{ text: 'Subscriptions', link: '/clients/subscriptions' },
57+
{ text: 'Skills (extension)', link: '/clients/skills' },
5658
{ text: 'OAuth', link: '/clients/oauth' },
5759
{ text: 'Machine auth', link: '/clients/machine-auth' },
5860
{ text: 'Middleware', link: '/clients/middleware' },

‎docs/clients/skills.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
shape: how-to
3+
---
4+
5+
# Skills (extension)
6+
7+
The [MCP Skills extension](https://github.com/modelcontextprotocol/ext-skills) (`io.modelcontextprotocol/skills`) lets a server publish [Agent Skills](https://agentskills.io/). `@modelcontextprotocol/client/ext/skills` is the client side, as a client extension: it lists and gets skill entries, reads directories, and reads skill files verified against their entry.
8+
9+
## Install the extension
10+
11+
```ts
12+
import { Client } from '@modelcontextprotocol/client';
13+
import { SkillsClientExtension } from '@modelcontextprotocol/client/ext/skills';
14+
15+
const skills = new SkillsClientExtension();
16+
const client = new Client({ name: 'host', version: '1.0.0' }, { extensions: [skills] });
17+
await client.connect(transport);
18+
```
19+
20+
Every method refuses with `CapabilityNotSupported` unless the server declared the extension and the `resources` capability. `readDirectory` also needs the server to declare `directoryRead`.
21+
22+
## List and get skills
23+
24+
`list` returns one page of entries. Pass `nextCursor` back as `cursor` for the next page. An entry is the full manifest: frontmatter, plus every file with its digest and size. `get(uri)` returns the entry for one skill by the URI of its `SKILL.md`, whether or not the listing included it.
25+
26+
```ts
27+
const { skills: entries, nextCursor } = await skills.list();
28+
const { skill } = await skills.get('skill://git-workflow/SKILL.md');
29+
```
30+
31+
## Read a skill file
32+
33+
`read(skill, uri)` fetches the file with `resources/read` and checks it against the entry. The file must be listed, and its size and SHA-256 digest must match. Any mismatch throws `SdkError` with `InvalidResult`. Refresh the entry with `get` and ask the user to approve the skill again.
34+
35+
```ts
36+
const manifest = await skills.read(skill, skill.uri);
37+
```
38+
39+
A skill with `resources: 'dynamic'` has nothing to verify against, so its files come back as read. The extension leaves two checks to the host: comparing a `SKILL.md`'s frontmatter with the entry (this needs a YAML parser), and the specification's [security requirements](https://github.com/modelcontextprotocol/ext-skills/blob/main/specification/stable/skills.mdx#security-considerations) for loading skills into a model.

‎docs/servers/skills.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
shape: how-to
3+
---
4+
5+
# Skills (extension)
6+
7+
The [MCP Skills extension](https://github.com/modelcontextprotocol/ext-skills) (`io.modelcontextprotocol/skills`) lets a server publish [Agent Skills](https://agentskills.io/): directories of instructions, each with a `SKILL.md`, that a host can load into its model. `@modelcontextprotocol/server/ext/skills` is the server side, as a [server extension](../advanced/extensions.md). It serves `skills/list`, `skills/get` and, optionally, `resources/directory/read`. Your server supplies the skill entries through a `SkillSource`, and serves the skill files as ordinary resources.
8+
9+
## Describe a skill
10+
11+
A skill entry names its `SKILL.md`, repeats that file's frontmatter, and lists every file of the skill with its SHA-256 digest and size. `skillResourceOf(uri, content)` computes a file's line in that list.
12+
13+
```ts
14+
import type { Skill } from '@modelcontextprotocol/server/ext/skills';
15+
import { skillResourceOf } from '@modelcontextprotocol/server/ext/skills';
16+
17+
const files = {
18+
'skill://git-workflow/SKILL.md': '---\nname: git-workflow\ndescription: Follow our Git conventions\n---\n\nBranch from main.\n'
19+
};
20+
21+
const gitWorkflow: Skill = {
22+
uri: 'skill://git-workflow/SKILL.md',
23+
frontmatter: { name: 'git-workflow', description: 'Follow our Git conventions' },
24+
resources: await Promise.all(Object.entries(files).map(([uri, text]) => skillResourceOf(uri, text)))
25+
};
26+
```
27+
28+
The frontmatter must match the `SKILL.md` exactly, and the URI's last directory must equal `frontmatter.name`. The server checks the second rule, and the entry's other structural rules, and answers `-32603` rather than send an entry that breaks one. A skill generated per request, with no stable digests, sets `resources: 'dynamic'`.
29+
30+
## Install the extension
31+
32+
`SkillsExtension` takes the source. `list` returns a page of entries (an empty or partial listing is allowed). `get` answers for any skill the server serves, listed or not, and returns `undefined` for anything else, which the client receives as `-32602`.
33+
34+
```ts
35+
import { McpServer } from '@modelcontextprotocol/server';
36+
import { SkillsExtension } from '@modelcontextprotocol/server/ext/skills';
37+
38+
const skills = new SkillsExtension(
39+
{
40+
list: () => ({ skills: [gitWorkflow] }),
41+
get: ({ uri }) => (uri === gitWorkflow.uri ? gitWorkflow : undefined)
42+
},
43+
{ cacheHint: { ttlMs: 300_000, cacheScope: 'public' } }
44+
);
45+
46+
const server = new McpServer({ name: 'skills-server', version: '1.0.0' }, { extensions: [skills] });
47+
48+
for (const [uri, text] of Object.entries(files)) {
49+
server.registerResource(uri, uri, { mimeType: 'text/markdown' }, () => ({ contents: [{ uri, mimeType: 'text/markdown', text }] }));
50+
}
51+
```
52+
53+
The server declares `io.modelcontextprotocol/skills` under `capabilities.extensions`, along with the `resources` capability the extension requires. `cacheHint` sets the `ttlMs` and `cacheScope` on `skills/list` and `skills/get` results. Both default to `0` and `'private'`.
54+
55+
## Serve directory reads
56+
57+
A source that implements `readDirectory` also gets `resources/directory/read`, and the server declares `directoryRead: true`. It returns the direct children of a directory such as `skill://pdf-processing/templates`, with subdirectories marked `mimeType: 'inode/directory'`, or `undefined` when the URI is not a directory.

‎packages/client/package.json‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,16 @@
4040
"default": "./dist/stdio.cjs"
4141
}
4242
},
43+
"./ext/skills": {
44+
"import": {
45+
"types": "./dist/ext/skills/index.d.mts",
46+
"default": "./dist/ext/skills/index.mjs"
47+
},
48+
"require": {
49+
"types": "./dist/ext/skills/index.d.cts",
50+
"default": "./dist/ext/skills/index.cjs"
51+
}
52+
},
4353
"./validators/ajv": {
4454
"import": {
4555
"types": "./dist/validators/ajv.d.mts",
@@ -115,6 +125,9 @@
115125
],
116126
"stdio": [
117127
"dist/stdio.d.mts"
128+
],
129+
"ext/skills": [
130+
"dist/ext/skills/index.d.mts"
118131
]
119132
}
120133
},
Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
/**
2+
* `@modelcontextprotocol/client/ext/skills` — the client side of the MCP
3+
* Skills extension (`io.modelcontextprotocol/skills`, SEP-2640).
4+
*
5+
* `SkillsClientExtension` wraps `skills/list`, `skills/get` and
6+
* `resources/directory/read`, and reads skill files verified against their
7+
* entry's digest and size.
8+
*/
9+
10+
export { SkillsClientExtension } from './skillsClientExtension';
11+
export type {
12+
GetSkillParams,
13+
GetSkillResult,
14+
ListSkillsParams,
15+
ListSkillsResult,
16+
ReadResourceDirectoryParams,
17+
ReadResourceDirectoryResult,
18+
Skill,
19+
SkillFrontmatter,
20+
SkillResource,
21+
SkillsCacheScope,
22+
SkillsExtensionCapability
23+
} from '@modelcontextprotocol/core-internal/ext/skills';
24+
export {
25+
getSkillParamsSchema,
26+
getSkillResultSchema,
27+
listSkillsParamsSchema,
28+
listSkillsResultSchema,
29+
readResourceDirectoryParamsSchema,
30+
readResourceDirectoryResultSchema,
31+
skillFrontmatterSchema,
32+
skillResourceSchema,
33+
skillSchema,
34+
skillsExtensionCapabilitySchema
35+
} from '@modelcontextprotocol/core-internal/ext/skills';
36+
export {
37+
DIRECTORY_MIME_TYPE,
38+
MAX_SKILL_RESOURCES,
39+
MAX_SKILL_TOTAL_BYTES,
40+
SKILL_MANIFEST_FILENAME,
41+
skillDigest,
42+
skillResourceOf,
43+
SKILLS_EXTENSION_ID
44+
} from '@modelcontextprotocol/core-internal/ext/skills';
Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
/**
2+
* `SkillsClientExtension` — the client side of the MCP Skills extension
3+
* (`io.modelcontextprotocol/skills`, SEP-2640) as a {@linkcode ClientExtension}.
4+
* It wraps `skills/list`, `skills/get` and `resources/directory/read`, each
5+
* refused unless the server declared support, and `read`, which fetches a
6+
* skill file with `resources/read` and verifies it against the skill's entry.
7+
*
8+
* ```ts
9+
* const skills = new SkillsClientExtension();
10+
* const client = new Client(info, { extensions: [skills] });
11+
* await client.connect(transport);
12+
*
13+
* const { skills: entries } = await skills.list();
14+
* const manifest = await skills.read(entries[0], entries[0].uri);
15+
* ```
16+
*
17+
* One extension instance serves one client: `install` binds it.
18+
*/
19+
20+
import type { BlobResourceContents, RequestOptions, TextResourceContents } from '@modelcontextprotocol/core-internal';
21+
import { SdkError, SdkErrorCode } from '@modelcontextprotocol/core-internal';
22+
import type {
23+
GetSkillResult,
24+
ListSkillsParams,
25+
ListSkillsResult,
26+
ReadResourceDirectoryResult,
27+
Skill,
28+
SkillsExtensionCapability
29+
} from '@modelcontextprotocol/core-internal/ext/skills';
30+
import {
31+
getSkillResultSchema,
32+
listSkillsResultSchema,
33+
readResourceDirectoryResultSchema,
34+
skillDigest,
35+
skillFileBytes,
36+
SKILLS_EXTENSION_ID,
37+
skillsExtensionCapabilitySchema
38+
} from '@modelcontextprotocol/core-internal/ext/skills';
39+
40+
import type { Client } from '../../client/client';
41+
import type { ClientExtension } from '../../client/extension';
42+
43+
const verificationFailure = (uri: string, reason: string): never => {
44+
throw new SdkError(SdkErrorCode.InvalidResult, `Skill file ${uri} failed verification: ${reason}`);
45+
};
46+
47+
const rawBytes = (content: TextResourceContents | BlobResourceContents): Uint8Array =>
48+
'blob' in content ? Uint8Array.from(atob(content.blob), char => char.codePointAt(0) ?? 0) : skillFileBytes(content.text);
49+
50+
export class SkillsClientExtension implements ClientExtension {
51+
readonly id = SKILLS_EXTENSION_ID;
52+
#client: Client | undefined;
53+
54+
install(client: Client): void {
55+
if (this.#client !== undefined) throw new Error('SkillsClientExtension is already installed on a client');
56+
this.#client = client;
57+
}
58+
59+
get client(): Client {
60+
if (this.#client === undefined) throw new SdkError(SdkErrorCode.NotConnected, 'SkillsClientExtension is not installed on a client');
61+
return this.#client;
62+
}
63+
64+
/** The extension settings the server declared, or `undefined` when it declared none. */
65+
get capability(): SkillsExtensionCapability | undefined {
66+
const declared = this.client.getServerCapabilities()?.extensions?.[SKILLS_EXTENSION_ID];
67+
const parsed = skillsExtensionCapabilitySchema.safeParse(declared);
68+
return parsed.success ? parsed.data : undefined;
69+
}
70+
71+
/** `skills/list`: one page of entries. Pass `nextCursor` back as `cursor` for the next. */
72+
async list(params?: ListSkillsParams, options?: RequestOptions): Promise<ListSkillsResult> {
73+
this.#require('skills/list');
74+
return (await this.client.request(
75+
{ method: 'skills/list', params: { ...params } },
76+
listSkillsResultSchema,
77+
options
78+
)) as ListSkillsResult;
79+
}
80+
81+
/** `skills/get`: the entry for the skill whose `SKILL.md` is at `uri`, listed or not. */
82+
async get(uri: string, options?: RequestOptions): Promise<GetSkillResult> {
83+
this.#require('skills/get');
84+
return (await this.client.request({ method: 'skills/get', params: { uri } }, getSkillResultSchema, options)) as GetSkillResult;
85+
}
86+
87+
/** `resources/directory/read`: the direct children of a directory resource. Refused unless the server declared `directoryRead`. */
88+
async readDirectory(uri: string, cursor?: string, options?: RequestOptions): Promise<ReadResourceDirectoryResult> {
89+
this.#require('resources/directory/read');
90+
if (this.capability?.directoryRead !== true) {
91+
throw new SdkError(SdkErrorCode.CapabilityNotSupported, 'Server does not support resources/directory/read');
92+
}
93+
const params = { uri, ...(cursor !== undefined && { cursor }) };
94+
return (await this.client.request(
95+
{ method: 'resources/directory/read', params },
96+
readResourceDirectoryResultSchema,
97+
options
98+
)) as ReadResourceDirectoryResult;
99+
}
100+
101+
/**
102+
* Reads one of `skill`'s files and verifies it against the entry: the file
103+
* must be listed, and its size and digest must match. Throws `InvalidResult`
104+
* on any mismatch. A `"dynamic"` skill has nothing to verify against, so its
105+
* files are returned as read. Comparing a `SKILL.md`'s frontmatter with the
106+
* entry needs a YAML parser and is left to the host.
107+
*/
108+
async read(skill: Skill, uri: string, options?: RequestOptions): Promise<TextResourceContents | BlobResourceContents> {
109+
const listed = skill.resources === 'dynamic' ? undefined : skill.resources.find(resource => resource.uri === uri);
110+
if (skill.resources !== 'dynamic' && listed === undefined) verificationFailure(uri, `not listed in ${skill.uri}`);
111+
112+
const { contents } = await this.client.readResource({ uri }, options);
113+
const content = contents.find(item => item.uri === uri) ?? verificationFailure(uri, 'not in the resources/read result');
114+
if (listed === undefined) return content;
115+
116+
const bytes = rawBytes(content);
117+
if (bytes.byteLength !== listed.size) verificationFailure(uri, `size ${bytes.byteLength}, entry says ${listed.size}`);
118+
if ((await skillDigest(bytes)) !== listed.digest) verificationFailure(uri, 'digest mismatch');
119+
return content;
120+
}
121+
122+
#require(method: string): void {
123+
if (this.capability === undefined) {
124+
throw new SdkError(
125+
SdkErrorCode.CapabilityNotSupported,
126+
`Server does not support the ${SKILLS_EXTENSION_ID} extension (${method})`
127+
);
128+
}
129+
if (this.client.getServerCapabilities()?.resources === undefined) {
130+
throw new SdkError(SdkErrorCode.CapabilityNotSupported, `Server declares ${SKILLS_EXTENSION_ID} without resources (${method})`);
131+
}
132+
}
133+
}

‎packages/client/tsconfig.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,8 @@
1717
"./node_modules/@modelcontextprotocol/core-internal/src/validators/cfWorkerProvider.ts"
1818
],
1919
"@modelcontextprotocol/test-helpers": ["./node_modules/@modelcontextprotocol/test-helpers/src/index.ts"],
20-
"@modelcontextprotocol/client/_shims": ["./src/shimsNode.ts"]
20+
"@modelcontextprotocol/client/_shims": ["./src/shimsNode.ts"],
21+
"@modelcontextprotocol/core-internal/ext/skills": ["./node_modules/@modelcontextprotocol/core-internal/src/ext/skills/index.ts"]
2122
}
2223
}
2324
}

‎packages/client/tsdown.config.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ export default defineConfig({
55
entry: [
66
'src/index.ts',
77
'src/stdio.ts',
8+
'src/ext/skills/index.ts',
89
'src/shimsNode.ts',
910
'src/shimsWorkerd.ts',
1011
'src/shimsBrowser.ts',
@@ -28,6 +29,7 @@ export default defineConfig({
2829
'fast-uri': ['../core-internal/src/validators/fastUriShim.d.ts'],
2930
'@modelcontextprotocol/core-internal': ['../core-internal/src/index.ts'],
3031
'@modelcontextprotocol/core-internal/public': ['../core-internal/src/exports/public/index.ts'],
32+
'@modelcontextprotocol/core-internal/ext/skills': ['../core-internal/src/ext/skills/index.ts'],
3133
'@modelcontextprotocol/core-internal/validators/ajv': ['../core-internal/src/validators/ajvProvider.ts'],
3234
'@modelcontextprotocol/core-internal/validators/cfWorker': ['../core-internal/src/validators/cfWorkerProvider.ts']
3335
}

‎packages/core-internal/package.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,10 @@
3333
"types": "./src/exports/public/index.ts",
3434
"import": "./src/exports/public/index.ts"
3535
},
36+
"./ext/skills": {
37+
"types": "./src/ext/skills/index.ts",
38+
"import": "./src/ext/skills/index.ts"
39+
},
3640
"./validators/ajv": {
3741
"types": "./src/validators/ajvProvider.ts",
3842
"import": "./src/validators/ajvProvider.ts"

0 commit comments

Comments
 (0)