Visitar URL original
Import Peder's additional Skills implementation · girishkvs/csharp-sdk@7a9e2eb · GitHub
Skip to content

Commit 7a9e2eb

Browse files
PederHPgirishkvs
andcommitted
Import Peder's additional Skills implementation
Import the net changes from PR modelcontextprotocol#1864 on top of the rebased modelcontextprotocol#1856 foundation, including the client, request-aware catalogs, validation, byte-snapshot authoring, YAML reader, samples, docs and regression tests. The shared foundation is retained once, not replayed. Source PR: modelcontextprotocol#1864 Source head: ecb11e6 Same-main source tree: ba9234d Source lineage (including already-shared foundation): 4a7d3f5 Widen PaginatedRequestParams and PaginatedResult constructors to protected 9569706 Add ModelContextProtocol.Extensions.Skills (SEP-2640) 50f7cd7 Add tests and a conformance fixture for the Skills extension 44d80ae Add Skills samples and docs 53e5425 Harden skill authoring and verified reads b2e92aa Read skill frontmatter from SKILL.md 9dc02bb Align the frontmatter reader with reference YAML parsers 72a0406 Point SkillVerifier remarks at SkillFrontmatter for frontmatter checks 932c318 Link the Skills docs page to the samples by relative path f18d7dc Address the Copilot review of modelcontextprotocol#1864 8c39436 Address the second Copilot review of modelcontextprotocol#1864 8593f0d Bind skills/get answers to the requested URI 82f0943 Enforce skill limits while reading a directory; match Core's URI equivalence fe89998 Address review feedback from the author of modelcontextprotocol#1856 4813b72 Complete earlier fixes and align the reader further with reference parsers ecb11e6 Close the neighbouring cases a differential YAML run and a second review pass found This local squash preserves human authorship, not source signatures. No consolidation repairs are included in this import. Co-authored-by: Girish Konda <girish.sai1@gmail.com>
1 parent c359bec commit 7a9e2eb

66 files changed

Lines changed: 6789 additions & 660 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎ModelContextProtocol.slnx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,8 @@
4949
<Project Path="samples/ProtectedMcpServer/ProtectedMcpServer.csproj" />
5050
<Project Path="samples/QuickstartClient/QuickstartClient.csproj" />
5151
<Project Path="samples/QuickstartWeatherServer/QuickstartWeatherServer.csproj" />
52+
<Project Path="samples/SkillsClient/SkillsClient.csproj" />
53+
<Project Path="samples/SkillsServer/SkillsServer.csproj" />
5254
<Project Path="samples/TasksExtension/TasksExtension.csproj" />
5355
<Project Path="samples/TestServerWithHosting/TestServerWithHosting.csproj" />
5456
<Project Path="samples/WeatherAppServer/WeatherAppServer.csproj" />

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ The SDK packages are:
1616

1717
- **[ModelContextProtocol.Extensions.Apps](https://www.nuget.org/packages/ModelContextProtocol.Extensions.Apps)** [![NuGet version](https://img.shields.io/nuget/v/ModelContextProtocol.Extensions.Apps.svg)](https://www.nuget.org/packages/ModelContextProtocol.Extensions.Apps) - MCP Apps extension for building interactive UI applications that render inside MCP hosts.
1818

19+
- **[ModelContextProtocol.Extensions.Skills](https://www.nuget.org/packages/ModelContextProtocol.Extensions.Skills)** [![NuGet version](https://img.shields.io/nuget/v/ModelContextProtocol.Extensions.Skills.svg)](https://www.nuget.org/packages/ModelContextProtocol.Extensions.Skills) - MCP Skills extension for serving and consuming Agent Skills with verifiable file manifests.
20+
1921
- **[ModelContextProtocol.Extensions.Tasks](https://www.nuget.org/packages/ModelContextProtocol.Extensions.Tasks)** [![NuGet version](https://img.shields.io/nuget/v/ModelContextProtocol.Extensions.Tasks.svg)](https://www.nuget.org/packages/ModelContextProtocol.Extensions.Tasks) - MCP Tasks extension for running long-running tool invocations asynchronously with status polling and input requests.
2022

2123
## Getting Started

‎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: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
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 keep each one in its own directory, as the Agent Skills specification
40+
lays them out, and point `WithSkillsFromDirectory` at the parent:
41+
42+
```csharp
43+
using ModelContextProtocol.Extensions.Skills;
44+
using ModelContextProtocol.Protocol;
45+
46+
builder.Services
47+
.AddMcpServer()
48+
.WithHttpTransport()
49+
.WithSkillsFromDirectory(Path.Combine(AppContext.BaseDirectory, "Skills"), configure: options =>
50+
{
51+
options.TimeToLive = TimeSpan.FromMinutes(5);
52+
options.CacheScope = CacheScope.Public;
53+
});
54+
```
55+
56+
Every immediate subdirectory containing a `SKILL.md` becomes a skill. The SDK reads the frontmatter from each
57+
`SKILL.md`, computes every digest and size from the same bytes the resources serve, registers the file resources,
58+
and publishes each skill at `skill://{name}/SKILL.md`, where `name` comes from the frontmatter. Pass a `uriPrefix`
59+
such as `skill://acme/billing/` to place the skills under an organizational path.
60+
61+
For finer control, build skills individually with <xref:ModelContextProtocol.Extensions.Skills.McpServerSkill> and
62+
register them with `WithSkills`:
63+
64+
```csharp
65+
var gitWorkflow = McpServerSkill.CreateFromDirectory(Path.Combine(skillsRoot, "git-workflow"));
66+
67+
var refunds = McpServerSkill.Create(
68+
"skill://acme/billing/refunds/SKILL.md",
69+
[
70+
McpServerSkillFile.FromText("SKILL.md", skillMarkdown),
71+
McpServerSkillFile.FromText("examples/approved.md", approvedTemplate),
72+
new McpServerSkillFile { Path = "assets/logo.png", Content = logoBytes },
73+
]);
74+
75+
builder.Services.AddMcpServer().WithHttpTransport().WithSkills([gitWorkflow, refunds]);
76+
```
77+
78+
All of these validate the skill against the specification and throw <xref:System.ArgumentException> with a
79+
specific message when, for example, the frontmatter `name` does not match the URI, `description` exceeds the
80+
Agent Skills limit of 1024 characters, a resource URI escapes the skill's directory, `SKILL.md` is missing, or
81+
the skill exceeds the per-skill limits of 512 files or 16 MiB. Frontmatter fields beyond `name`, `description`,
82+
`compatibility`, and the shape of `metadata` pass through verbatim, as the specification requires; hosts compare
83+
them against the file and ignore fields such as `allowed-tools` for MCP-origin skills. File contents are copied when the skill is created, so
84+
later changes to a caller's buffer or to files on disk do not affect what is served. `CreateFromDirectory` does not
85+
follow symbolic links, since a link can point outside the skill directory; it throws if it encounters one. File
86+
names containing characters with URI syntax (such as `{`, `?`, or a space) are percent-encoded in the resource URIs.
87+
88+
#### Frontmatter
89+
90+
<xref:ModelContextProtocol.Extensions.Skills.SkillFrontmatter> reads the YAML frontmatter of a `SKILL.md` into a
91+
<xref:System.Text.Json.Nodes.JsonObject> without a YAML library. It accepts the subset of YAML that Agent Skills
92+
frontmatter uses: block mappings (nested up to 32 levels), block and flow sequences, plain, quoted, and block
93+
scalars, and comments. Unquoted scalars are resolved per the YAML 1.2 core schema (`null`, booleans, integers, finite
94+
floats, otherwise strings), matching the YAML libraries used by other SDKs and by hosts. That matters because a
95+
host verifies a skill by parsing the fetched `SKILL.md` itself and comparing field by field against the published
96+
entry; a value that one side types as a number and the other as a string is a verification failure. Quote values
97+
such as version numbers that are meant to be strings.
98+
99+
Anchors, aliases, tags, complex keys, nested and multi-line flow collections, and multi-line quoted scalars are
100+
valid YAML the reader does not support; it rejects them with a <xref:System.FormatException> naming the construct. For such a
101+
file, the `Create` and `CreateFromDirectory` overloads that take an explicit `JsonObject` supply the frontmatter
102+
directly. That escape hatch covers only valid-but-unsupported YAML: a file with no frontmatter block, malformed
103+
YAML, or invalid UTF-8 is rejected regardless, since no host could parse it either. When the reader can parse the
104+
file, an explicit object must match it exactly, or the skill is rejected at construction rather than by every host.
105+
106+
#### Custom catalogs
107+
108+
When skills come from a database, a file share, or a large or generated catalog, implement
109+
<xref:ModelContextProtocol.Extensions.Skills.IMcpSkillCatalog> and pass it to `WithSkills`:
110+
111+
```csharp
112+
public sealed class DatabaseSkillCatalog(SkillRepository repository) : IMcpSkillCatalog
113+
{
114+
public async ValueTask<McpSkillPage> ListAsync(string? cursor, McpSkillRequestContext context, CancellationToken cancellationToken)
115+
{
116+
string tenant = GetTenant(context.User);
117+
var (skills, nextCursor) = await repository.GetPageAsync(tenant, cursor, pageSize: 50, cancellationToken);
118+
return new McpSkillPage { Skills = skills, NextCursor = nextCursor };
119+
}
120+
121+
public ValueTask<Skill?> GetAsync(string uri, McpSkillRequestContext context, CancellationToken cancellationToken) =>
122+
repository.FindAsync(GetTenant(context.User), uri, cancellationToken);
123+
}
124+
```
125+
126+
Both methods receive an <xref:ModelContextProtocol.Extensions.Skills.McpSkillRequestContext> with the JSON-RPC request,
127+
the caller's <xref:System.Security.Claims.ClaimsPrincipal> when the transport supplies one (the ASP.NET Core
128+
transport does), and any items that incoming-message filters attached to the request.
129+
130+
A catalog supplies entries only; the skills' files must still be served as resources, since hosts read them with
131+
`resources/read`. A catalog may list only part of what it serves, or nothing at all, as long as `GetAsync` answers
132+
for every skill the server serves to the caller. Throw <xref:ModelContextProtocol.McpProtocolException> with
133+
<xref:ModelContextProtocol.McpErrorCode.InvalidParams> for a cursor the catalog cannot interpret.
134+
<xref:ModelContextProtocol.Extensions.Skills.InMemoryMcpSkillCatalog> is the built-in implementation over a fixed
135+
set of entries and can be composed into a custom one.
136+
137+
#### Dynamic skills
138+
139+
A skill whose content is generated on demand cannot publish stable digests. Set its entry's `Resources` to
140+
<xref:ModelContextProtocol.Extensions.Skills.SkillResources.Dynamic> and serve it through a catalog. Such a skill
141+
offers no content integrity, and hosts may decline to load it.
142+
143+
#### Protocol versions and caching hints
144+
145+
`skills/list` results carry the base protocol's `ttlMs` and `cacheScope` list-caching attributes, configured through
146+
<xref:ModelContextProtocol.Extensions.Skills.McpSkillsOptions>. Those attributes, and `resultType`, are defined
147+
from protocol revision `2026-07-28`. The SDK emits them only on requests negotiated under that revision or later,
148+
where they are required and default to `0` and `private` when unset, the same conservative defaults the built-in
149+
list methods use. On earlier revisions, which reject them as unrecognized keys, they are omitted.
150+
151+
### Consuming skills
152+
153+
The client extension methods in <xref:ModelContextProtocol.Extensions.Skills.McpSkillsClientExtensions> cover the
154+
host's side of the protocol:
155+
156+
```csharp
157+
using ModelContextProtocol.Extensions.Skills;
158+
159+
if (!client.SupportsSkills())
160+
{
161+
return; // Clients issue skills/list and skills/get only after observing the declaration.
162+
}
163+
164+
// Enumerate, following pagination. The listing may be empty or partial.
165+
IList<Skill> skills = await client.ListSkillsAsync();
166+
167+
// Retrieve one skill by URI, for example one referenced from server instructions.
168+
Skill skill = await client.GetSkillAsync("skill://git-workflow/SKILL.md");
169+
170+
// Read a file and verify it against the held entry's digest and size.
171+
ReadResourceResult contents = await client.ReadSkillResourceAsync(skill, skill.Uri);
172+
```
173+
174+
`ListSkillsAsync` and `GetSkillAsync` validate every entry the server returns against the specification's structural
175+
requirements and throw <xref:ModelContextProtocol.Extensions.Skills.SkillVerificationException> for an entry a host
176+
must not load, such as one whose manifest omits its own `SKILL.md`, carries a malformed digest, or lists a file
177+
outside the skill. `ReadSkillResourceAsync` throws the same exception when the
178+
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
179+
content must not be used. To recover, refresh the entry with `GetSkillAsync` and proceed from the new manifest;
180+
because the manifest changed, any approval bound to the previous one is revoked and must be obtained again.
181+
182+
The lower-level overloads, `ListSkillsAsync(ListSkillsRequestParams)` and `GetSkillAsync(GetSkillRequestParams)`,
183+
return one page or the raw result and expose the caching hints.
184+
<xref:ModelContextProtocol.Extensions.Skills.SkillVerifier> exposes the verification and digest helpers for hosts
185+
that read resources through other means.
186+
187+
### Security considerations
188+
189+
Skill content is instructional text delivered to a model and is therefore a prompt-injection surface. The
190+
specification places most of the burden on hosts. In particular:
191+
192+
- `skills/list` and `skills/get` are registered as raw request handlers, so they do not pass through the request
193+
filters that guard the built-in resource methods, including the ASP.NET Core authorization filters. A listing
194+
therefore discloses frontmatter, file names, sizes, and digests to any caller the transport admits. If some
195+
callers must not see some skills, implement <xref:ModelContextProtocol.Extensions.Skills.IMcpSkillCatalog> and
196+
decide from the request context's user, and guard the corresponding resources the same way. The built-in
197+
in-memory catalog serves the same entries to every caller.
198+
- Treat MCP-served skill content as untrusted model input, and tag it with its originating server when it enters
199+
the model's context.
200+
- Digests are unsigned and come from the same server as the content. A match proves consistency between the entry
201+
and what was fetched, not that either is trustworthy.
202+
- Bind any persisted per-skill approval to the entry's manifest. A later entry with a different manifest revokes it.
203+
- Do not honor frontmatter fields that widen the model's permissions, such as `allowed-tools`, for MCP-origin skills
204+
without explicit user approval.
205+
- Skill names are labels, not identifiers, and are not unique across servers. Identify a skill by the pair of server
206+
identity and URI.
207+
208+
The SDK implements digest and size verification and the unlisted-file rule. It does not verify frontmatter against
209+
the fetched `SKILL.md` automatically. A host can do so with
210+
<xref:ModelContextProtocol.Extensions.Skills.SkillFrontmatter.Parse(System.String)> on the fetched text and
211+
<xref:System.Text.Json.Nodes.JsonNode.DeepEquals(System.Text.Json.Nodes.JsonNode,System.Text.Json.Nodes.JsonNode)>
212+
against the entry's frontmatter, treating a parse failure or a difference as a verification failure.
213+
214+
### Not implemented
215+
216+
The optional `resources/directory/read` method and its `directoryRead` capability setting are not implemented.
217+
Servers built with this package do not declare `directoryRead`, and hosts must not call the method against them.
218+
219+
### Samples
220+
221+
- [SkillsServer](https://github.com/modelcontextprotocol/csharp-sdk/tree/main/samples/SkillsServer): a Streamable
222+
HTTP server serving two skills from directories on disk.
223+
- [SkillsClient](https://github.com/modelcontextprotocol/csharp-sdk/tree/main/samples/SkillsClient): a client that
224+
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

0 commit comments

Comments
 (0)