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