Skip to content

Commit 44d80ae

Browse files
PederHPclaude
andcommitted
Add Skills samples and docs
SkillsServer is a Streamable HTTP server serving two skills from directories on disk through McpServerSkill.CreateFromDirectory, one with a nested skill path, and pointing at one of them from its server instructions. SkillsClient connects to it and walks through the host side: capability check, listing with caching hints, retrieval by URI, verified reads of SKILL.md and a supporting file, and the refusal of an unlisted file. The docs page covers serving skills, custom catalogs, dynamic skills, protocol-version handling of the caching hints, the client API, verification, security considerations, and what is deliberately not implemented. README and PACKAGE.md list the new package. Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01P6omaTvQiryHtzFHRqUE3b
1 parent 50f7cd7 commit 44d80ae

17 files changed

Lines changed: 620 additions & 0 deletions

File tree

‎docs/concepts/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,4 +53,5 @@ To install the SDK and build your first MCP client and server, see [Getting star
5353
| - | - |
5454
| [MCP Apps](apps/apps.md) | Learn how to use the MCP Apps extension to deliver interactive UIs from MCP servers. |
5555
| [Tasks](tasks/tasks.md) | Learn how to use task-based execution for long-running operations that can be polled for status and results. |
56+
| [Skills](skills/skills.md) | Learn how to serve and consume Agent Skills over MCP, with verifiable file manifests. |
5657
| [Identity and Roles](identity/identity.md) | Learn how to access caller identity and roles in MCP tool, prompt, and resource handlers. |

‎docs/concepts/skills/skills.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
---
2+
title: Skills
3+
description: Serve and consume Agent Skills over MCP with the Skills extension.
4+
uid: skills
5+
---
6+
7+
## Skills
8+
9+
The Skills extension lets an MCP server publish [Agent Skills](https://agentskills.io/) alongside its tools,
10+
resources, and prompts. A skill is a directory of files, minimally a `SKILL.md` with YAML frontmatter, that gives
11+
an agent structured workflow instructions. Over MCP, each file is an ordinary resource, and the extension adds two
12+
methods for discovering skills and obtaining a verifiable manifest of their files:
13+
14+
- `skills/list` enumerates the skills a server serves, with pagination.
15+
- `skills/get` returns the entry for a single skill by the URI of its `SKILL.md`.
16+
17+
Skills are provided by the `ModelContextProtocol.Extensions.Skills` package. The implementation follows the
18+
[Skills extension specification](https://github.com/modelcontextprotocol/ext-skills/blob/main/specification/stable/skills.mdx)
19+
(SEP-2640, extension id `io.modelcontextprotocol/skills`).
20+
21+
### Overview
22+
23+
A skill entry (<xref:ModelContextProtocol.Extensions.Skills.Skill>) is a complete, point-in-time snapshot of a skill:
24+
25+
- `uri`: the resource URI of its `SKILL.md`, conventionally `skill://<skill-path>/SKILL.md`. The final segment
26+
of `<skill-path>` is the skill's name.
27+
- `frontmatter`: the `SKILL.md` YAML frontmatter, rendered verbatim as a JSON object. `name` and `description`
28+
are always present; every other authored field passes through.
29+
- `resources`: either a complete manifest of the skill's files, each with a SHA-256 digest and size
30+
(<xref:ModelContextProtocol.Extensions.Skills.SkillResource>), or the string `"dynamic"` for generated content
31+
that cannot be digested.
32+
33+
A host builds its registry from entries alone, then fetches files lazily with `resources/read` and verifies each
34+
one against the manifest. That verification, and the rule that an unlisted file is a change to the skill, is what
35+
lets a user's approval bind to specific content.
36+
37+
### Serving skills
38+
39+
The simplest way to serve skills is to describe each one with
40+
<xref:ModelContextProtocol.Extensions.Skills.McpServerSkill> and register them with `WithSkills`. The SDK computes
41+
every digest and size from the same bytes the resources serve, so the manifest and the content cannot disagree,
42+
and registers the file resources for you.
43+
44+
```csharp
45+
using ModelContextProtocol.Extensions.Skills;
46+
using System.Text.Json.Nodes;
47+
48+
var gitWorkflow = McpServerSkill.CreateFromDirectory(
49+
uri: "skill://git-workflow/SKILL.md",
50+
frontmatter: new JsonObject
51+
{
52+
["name"] = "git-workflow",
53+
["description"] = "Follow this team's Git conventions for branching and commits.",
54+
},
55+
directoryPath: Path.Combine(AppContext.BaseDirectory, "Skills", "git-workflow"));
56+
57+
builder.Services
58+
.AddMcpServer()
59+
.WithHttpTransport()
60+
.WithSkills([gitWorkflow], options =>
61+
{
62+
options.TimeToLive = TimeSpan.FromMinutes(5);
63+
options.CacheScope = CacheScope.Public;
64+
});
65+
```
66+
67+
`McpServerSkill.Create` takes the files explicitly when they are not on disk:
68+
69+
```csharp
70+
var skill = McpServerSkill.Create(
71+
"skill://refunds/SKILL.md",
72+
new JsonObject { ["name"] = "refunds", ["description"] = "Process refunds." },
73+
[
74+
McpServerSkillFile.FromText("SKILL.md", skillMarkdown),
75+
McpServerSkillFile.FromText("examples/approved.md", approvedTemplate),
76+
new McpServerSkillFile { Path = "assets/logo.png", Content = logoBytes },
77+
]);
78+
```
79+
80+
Both methods validate the skill against the specification and throw <xref:System.ArgumentException> with a
81+
specific message when, for example, the frontmatter `name` does not match the URI, `SKILL.md` is missing, or the
82+
skill exceeds the per-skill limits of 512 files or 16 MiB.
83+
84+
#### Frontmatter
85+
86+
The frontmatter is supplied as a <xref:System.Text.Json.Nodes.JsonObject> and must reproduce the YAML frontmatter
87+
at the top of `SKILL.md` exactly, field by field. Hosts re-parse the fetched `SKILL.md` and compare it against the
88+
entry, treating any discrepancy as a verification failure. The SDK does not include a YAML parser and does not
89+
derive the frontmatter from the file, so keep the two in sync.
90+
91+
#### Custom catalogs
92+
93+
When skills come from a database, a file share, or a large or generated catalog, implement
94+
<xref:ModelContextProtocol.Extensions.Skills.IMcpSkillCatalog> and pass it to `WithSkills`:
95+
96+
```csharp
97+
public sealed class DatabaseSkillCatalog(SkillRepository repository) : IMcpSkillCatalog
98+
{
99+
public async ValueTask<McpSkillPage> ListAsync(string? cursor, CancellationToken cancellationToken)
100+
{
101+
var (skills, nextCursor) = await repository.GetPageAsync(cursor, pageSize: 50, cancellationToken);
102+
return new McpSkillPage { Skills = skills, NextCursor = nextCursor };
103+
}
104+
105+
public ValueTask<Skill?> GetAsync(string uri, CancellationToken cancellationToken) =>
106+
repository.FindAsync(uri, cancellationToken);
107+
}
108+
```
109+
110+
A catalog supplies entries only; the skills' files must still be served as resources, since hosts read them with
111+
`resources/read`. A catalog may list only part of what it serves, or nothing at all, as long as `GetAsync` answers
112+
for every skill the server serves. Throw <xref:ModelContextProtocol.McpProtocolException> with
113+
<xref:ModelContextProtocol.McpErrorCode.InvalidParams> for a cursor the catalog did not issue.
114+
<xref:ModelContextProtocol.Extensions.Skills.InMemoryMcpSkillCatalog> is the built-in implementation over a fixed
115+
set of entries and can be composed into a custom one.
116+
117+
#### Dynamic skills
118+
119+
A skill whose content is generated on demand cannot publish stable digests. Set its entry's `Resources` to
120+
<xref:ModelContextProtocol.Extensions.Skills.SkillResources.Dynamic> and serve it through a catalog. Such a skill
121+
offers no content integrity, and hosts may decline to load it.
122+
123+
#### Protocol versions and caching hints
124+
125+
`skills/list` results carry the base protocol's `ttlMs` and `cacheScope` list-caching attributes, configured through
126+
<xref:ModelContextProtocol.Extensions.Skills.McpSkillsOptions>. Those attributes, and `resultType`, are defined
127+
from protocol revision `2026-07-28`. The SDK emits them only on requests negotiated under that revision or later,
128+
where they are required and default to `0` and `private` when unset, the same conservative defaults the built-in
129+
list methods use. On earlier revisions, which reject them as unrecognized keys, they are omitted.
130+
131+
### Consuming skills
132+
133+
The client extension methods in <xref:ModelContextProtocol.Extensions.Skills.McpSkillsClientExtensions> cover the
134+
host's side of the protocol:
135+
136+
```csharp
137+
using ModelContextProtocol.Extensions.Skills;
138+
139+
if (!client.SupportsSkills())
140+
{
141+
return; // Clients issue skills/list and skills/get only after observing the declaration.
142+
}
143+
144+
// Enumerate, following pagination. The listing may be empty or partial.
145+
IList<Skill> skills = await client.ListSkillsAsync();
146+
147+
// Retrieve one skill by URI, for example one referenced from server instructions.
148+
Skill skill = await client.GetSkillAsync("skill://git-workflow/SKILL.md");
149+
150+
// Read a file and verify it against the held entry's digest and size.
151+
ReadResourceResult contents = await client.ReadSkillResourceAsync(skill, skill.Uri);
152+
```
153+
154+
`ReadSkillResourceAsync` throws <xref:ModelContextProtocol.Extensions.Skills.SkillVerificationException> when the
155+
content's size or digest does not match the manifest, or when the URI is not listed in it at all. In both cases the
156+
content must not be used. To recover, refresh the entry with `GetSkillAsync` and proceed from the new manifest;
157+
because the manifest changed, any approval bound to the previous one is revoked and must be obtained again.
158+
159+
The lower-level overloads, `ListSkillsAsync(ListSkillsRequestParams)` and `GetSkillAsync(GetSkillRequestParams)`,
160+
return one page or the raw result and expose the caching hints.
161+
<xref:ModelContextProtocol.Extensions.Skills.SkillVerifier> exposes the verification and digest helpers for hosts
162+
that read resources through other means.
163+
164+
### Security considerations
165+
166+
Skill content is instructional text delivered to a model and is therefore a prompt-injection surface. The
167+
specification places most of the burden on hosts. In particular:
168+
169+
- Treat MCP-served skill content as untrusted model input, and tag it with its originating server when it enters
170+
the model's context.
171+
- Digests are unsigned and come from the same server as the content. A match proves consistency between the entry
172+
and what was fetched, not that either is trustworthy.
173+
- Bind any persisted per-skill approval to the entry's manifest. A later entry with a different manifest revokes it.
174+
- Do not honor frontmatter fields that widen the model's permissions, such as `allowed-tools`, for MCP-origin skills
175+
without explicit user approval.
176+
- Skill names are labels, not identifiers, and are not unique across servers. Identify a skill by the pair of server
177+
identity and URI.
178+
179+
The SDK implements digest and size verification and the unlisted-file rule. It does not verify frontmatter against
180+
the fetched `SKILL.md`, since it does not parse YAML; a host must do that itself before loading a skill.
181+
182+
### Not implemented
183+
184+
The optional `resources/directory/read` method and its `directoryRead` capability setting are not implemented.
185+
Servers built with this package do not declare `directoryRead`, and hosts must not call the method against them.
186+
187+
### Samples
188+
189+
- [SkillsServer](https://github.com/modelcontextprotocol/csharp-sdk/tree/main/samples/SkillsServer): a Streamable
190+
HTTP server serving two skills from directories on disk.
191+
- [SkillsClient](https://github.com/modelcontextprotocol/csharp-sdk/tree/main/samples/SkillsClient): a client that
192+
connects to it and discovers, retrieves, and verifies them.

‎docs/concepts/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,8 @@ items:
5555
uid: apps
5656
- name: Tasks
5757
uid: tasks
58+
- name: Skills
59+
uid: skills
5860
- name: Identity and Roles
5961
uid: identity
6062
- name: API Reference

‎samples/SkillsClient/Program.cs‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
// Demonstrates consuming Agent Skills over MCP with the Skills extension (SEP-2640), from the host's side:
2+
//
3+
// 1. Connect over Streamable HTTP and check that the server declares the extension.
4+
// 2. Enumerate the skills with skills/list (the client extension follows pagination for you).
5+
// 3. Retrieve a single skill by URI with skills/get, as a host does for a URI mentioned in server instructions.
6+
// 4. Read the skill's files with resources/read and verify each one against the manifest's digest and size.
7+
// 5. Show that a file the manifest does not list is refused before any request is sent.
8+
//
9+
// Start the SkillsServer sample first (dotnet run --project samples/SkillsServer). Pass a different endpoint as
10+
// the first argument to run against another server.
11+
12+
using ModelContextProtocol.Client;
13+
using ModelContextProtocol.Extensions.Skills;
14+
using ModelContextProtocol.Protocol;
15+
16+
var endpoint = new Uri(args.Length > 0 ? args[0] : "http://localhost:3001");
17+
18+
await using McpClient client = await McpClient.CreateAsync(new HttpClientTransport(new()
19+
{
20+
Name = "Skills Server",
21+
Endpoint = endpoint,
22+
}));
23+
24+
Console.WriteLine($"Connected to {client.ServerInfo.Name} {client.ServerInfo.Version} at {endpoint} (protocol {client.NegotiatedProtocolVersion})");
25+
Console.WriteLine();
26+
27+
// 1. Capability check. Clients issue skills/list and skills/get only after observing the declaration.
28+
if (!client.SupportsSkills())
29+
{
30+
Console.WriteLine("The server does not declare the io.modelcontextprotocol/skills extension.");
31+
return;
32+
}
33+
34+
// 2. Enumerate. A listing may be empty or partial; a skill can always be fetched by URI.
35+
Console.WriteLine("=== skills/list ===");
36+
ListSkillsResult firstPage = await client.ListSkillsAsync(new ListSkillsRequestParams());
37+
Console.WriteLine($" caching hints: ttlMs={(firstPage.TimeToLive is { } ttl ? ttl.TotalMilliseconds.ToString() : "(none)")} cacheScope={firstPage.CacheScope?.ToString() ?? "(none)"}");
38+
39+
IList<Skill> skills = await client.ListSkillsAsync();
40+
foreach (Skill listed in skills)
41+
{
42+
string manifest = listed.Resources.IsDynamic
43+
? "dynamic (no digests)"
44+
: $"{listed.Resources.Resources!.Count} file(s), {listed.Resources.Resources.Sum(r => r.Size)} bytes";
45+
Console.WriteLine($" {listed.Uri}");
46+
Console.WriteLine($" name: {listed.Name}");
47+
Console.WriteLine($" description: {listed.Description}");
48+
Console.WriteLine($" manifest: {manifest}");
49+
}
50+
51+
Console.WriteLine();
52+
53+
// 3. Retrieve one skill by URI. The server's instructions reference this one, so a host confirms it directly.
54+
Console.WriteLine("=== skills/get ===");
55+
Console.WriteLine($" server instructions: {client.ServerInstructions}");
56+
const string SkillUri = "skill://git-workflow/SKILL.md";
57+
Skill skill = await client.GetSkillAsync(SkillUri);
58+
Console.WriteLine($" {skill.Uri} ({skill.Name})");
59+
foreach (SkillResource file in skill.Resources.Resources!)
60+
{
61+
Console.WriteLine($" {file.Uri} {file.Size,6} bytes {file.Digest}");
62+
}
63+
64+
Console.WriteLine();
65+
66+
// 4. Verified reads. ReadSkillResourceAsync issues resources/read and checks size and digest against the held
67+
// entry; a mismatch throws SkillVerificationException and the content must not be used.
68+
Console.WriteLine("=== resources/read (verified) ===");
69+
ReadResourceResult skillFile = await client.ReadSkillResourceAsync(skill, SkillUri);
70+
Console.WriteLine($" {SkillUri} verified:");
71+
Console.WriteLine(Indent(((TextResourceContents)skillFile.Contents[0]).Text));
72+
73+
string supportingFileUri = skill.Resources.Resources.First(r => r.Uri != SkillUri).Uri;
74+
ReadResourceResult supportingFile = await client.ReadSkillResourceAsync(skill, supportingFileUri);
75+
Console.WriteLine($" {supportingFileUri} verified ({((TextResourceContents)supportingFile.Contents[0]).Text.Length} chars)");
76+
Console.WriteLine();
77+
78+
// 5. An unlisted file is a change to the skill. While acting on the held entry, the host must not read it.
79+
Console.WriteLine("=== unlisted file ===");
80+
try
81+
{
82+
await client.ReadSkillResourceAsync(skill, "skill://git-workflow/references/UNLISTED.md");
83+
}
84+
catch (SkillVerificationException e)
85+
{
86+
Console.WriteLine($" refused: {e.Message}");
87+
}
88+
89+
static string Indent(string text) =>
90+
string.Join(Environment.NewLine, text.TrimEnd().Split('\n').Select(line => " | " + line.TrimEnd('\r')));

‎samples/SkillsClient/README.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Skills Client Sample
2+
3+
A console client that consumes [Agent Skills](https://agentskills.io/) over MCP through the Skills extension
4+
([SEP-2640](https://github.com/modelcontextprotocol/ext-skills/blob/main/specification/stable/skills.mdx)),
5+
doing what a host's skill-loading path does:
6+
7+
1. Connects over Streamable HTTP and checks that the server declares `io.modelcontextprotocol/skills`
8+
(`client.SupportsSkills()`).
9+
2. Enumerates the catalog with `skills/list` (`client.ListSkillsAsync()` follows pagination; the per-page
10+
overload exposes the `ttlMs` and `cacheScope` hints).
11+
3. Retrieves one skill by URI with `skills/get` (`client.GetSkillAsync(uri)`), the way a host confirms a URI it
12+
found in server instructions.
13+
4. Reads the skill's files with `resources/read` and verifies each against the manifest's digest and size
14+
(`client.ReadSkillResourceAsync(skill, uri)`).
15+
5. Shows that a file the manifest does not list is refused before any request is sent.
16+
17+
## Run
18+
19+
Start the [SkillsServer](../SkillsServer) sample in one terminal:
20+
21+
```bash
22+
dotnet run --project samples/SkillsServer/SkillsServer.csproj
23+
```
24+
25+
Then run the client in another:
26+
27+
```bash
28+
dotnet run --project samples/SkillsClient/SkillsClient.csproj
29+
```
30+
31+
To run against another Streamable HTTP server, pass its endpoint:
32+
33+
```bash
34+
dotnet run --project samples/SkillsClient/SkillsClient.csproj -- https://skills.example.com/mcp
35+
```
36+
37+
Expected output (abridged):
38+
39+
```
40+
=== skills/list ===
41+
caching hints: ttlMs=300000 cacheScope=Public
42+
skill://acme/billing/refunds/SKILL.md
43+
name: refunds
44+
...
45+
skill://git-workflow/SKILL.md
46+
name: git-workflow
47+
manifest: 3 file(s), 1523 bytes
48+
49+
=== skills/get ===
50+
skill://git-workflow/SKILL.md (git-workflow)
51+
skill://git-workflow/SKILL.md 724 bytes sha256:…
52+
...
53+
54+
=== resources/read (verified) ===
55+
skill://git-workflow/SKILL.md verified:
56+
| ---
57+
| name: git-workflow
58+
...
59+
60+
=== unlisted file ===
61+
refused: 'skill://git-workflow/references/UNLISTED.md' is not listed in the manifest of skill ...
62+
```
63+
64+
## Notes
65+
66+
- Digest verification proves that the entry and the content are consistent. It is not a trust boundary: both come
67+
from the same server. Treat skill content as untrusted model input and tag it with its originating server.
68+
- The SDK does not verify frontmatter (re-parsing the fetched `SKILL.md`'s YAML and comparing it to the entry),
69+
because it does not include a YAML parser. A host must do that itself before loading a skill.
Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
3+
<PropertyGroup>
4+
<OutputType>Exe</OutputType>
5+
<TargetFramework>net8.0</TargetFramework>
6+
<ImplicitUsings>enable</ImplicitUsings>
7+
<Nullable>enable</Nullable>
8+
<NoWarn>$(NoWarn);MCPEXP001</NoWarn>
9+
</PropertyGroup>
10+
11+
<ItemGroup>
12+
<ProjectReference Include="..\..\src\ModelContextProtocol\ModelContextProtocol.csproj" />
13+
<ProjectReference Include="..\..\src\ModelContextProtocol.Extensions.Skills\ModelContextProtocol.Extensions.Skills.csproj" />
14+
</ItemGroup>
15+
16+
</Project>

0 commit comments

Comments
 (0)