|
| 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. |
0 commit comments