Add SEP-2640 Skills extension support

[girishkvs]

Summary

Adds ModelContextProtocol.Extensions.Skills, implementing the skills/list and skills/get methods of SEP-2640 (io.modelcontextprotocol/skills, accepted 2026-09-01), alongside the existing Tasks and Apps extension packages. The capability is declared inline and both methods are registered through McpServerOptions.RequestHandlers, so the extension consumes only public Core API.

The Core API changes are intentional, and I am happy to split them into their own PR. PaginatedResult and PaginatedRequest had private protected constructors, so a package outside Core cannot implement a paginated method. skills/list is paginated. Widening those to protected is source and binary compatible, and package validation passes against the 2.0.0 baseline. CacheScopeConverter is also public so extensions can reuse Core's read-side leniency for unrecognized scope values.

A skill's manifest uses a closed SkillResources type admitting only an enumerated file list or the "dynamic" marker, and "resources": null is rejected on read. Entries receive structural validation, and pagination uses keyset cursors over URI order. The built-in catalog owns validated snapshots; custom catalogs remain checked on each request.

ttlMs, cacheScope and resultType are emitted on both list/get results for protocol revision 2026-07-28 and omitted on older revisions. Cache values are configurable and default to immediately stale/private. Client-side wrappers, byte-consistent file authoring, a bounded YAML reader and both client/server samples are included.

Directory loading excludes dot-prefixed, hidden and system entries by default, with explicit opt-in. Aggregating client listing defaults to 100 pages and 1,000 entries, with configurable positive limits and cursor-cycle errors rather than silent truncation. ListSkillsWithDiagnosticsAsync is an explicit alternative that returns valid entries and indexed failures while ordinary list helpers remain strict.

I would still like maintainer input on the authorization boundary and public Core API shape:

• Skills served through RequestHandlers do not automatically pass through AuthorizationFilterSetup. The current implementation keeps one shared application policy for catalog visibility and resource access, with HTTP allow/deny coverage. It does not derive authorization from resources/list, since that listing may be partial while direct reads remain valid. Would you prefer a general filter hook for custom request handlers in Core?
• Making CacheScopeConverter public is deliberate, alongside the pagination constructors. I can split these API changes if that is the preferred package boundary.

Following CONTRIBUTING.md I would normally open an issue first. I am opening this as a PR because the working group asked for a reference implementation in a Tier 1 SDK and Go already has one in flight. Happy to convert this to an issue, split it, or reshape the API if you would prefer.

Changes

File	What
Extensions.Skills/SkillsProtocol.cs	New. Method names, extension id, limits, sentinels
Extensions.Skills/Protocol/Skill.cs, SkillResource.cs	New. Entry and manifest file shapes
Extensions.Skills/Protocol/SkillResources.cs, SkillResourcesConverter.cs	New. Array-or-"dynamic" union and its converter
Extensions.Skills/Protocol/ListSkills*.cs, GetSkill*.cs	New. Required request/result shapes and protocol-gated cache hints
Extensions.Skills/McpSkillsJsonContext.cs	New. Source-generated serialization for AOT
Extensions.Skills/Server/IMcpSkillCatalog.cs, McpSkillPage.cs, McpSkillRequestContext.cs	New. Request-aware catalog abstraction and caller context
Extensions.Skills/Server/InMemoryMcpSkillCatalog.cs	New. Keyset cursors, strict UTF-8 decoding, validated owned snapshots and a narrow built-in fast path
Extensions.Skills/Server/McpSkillsBuilderExtensions.cs, McpSkillsOptions.cs	New. WithSkills(), directory discovery, safe selection defaults and options
Extensions.Skills/Server/McpServerSkill*.cs, SkillFrontmatter.cs	New. Manifests computed from the served bytes; selected directory files, link rejection and bounded frontmatter parsing
Extensions.Skills/SkillValidation.cs	New. Structural validation, Unicode-scalar names and string-valued known metadata
Extensions.Skills/Client	New. Capability/list/get helpers, bounded aggregation, diagnostic pages and manifest-bound resource verification
Core/Protocol/PaginatedResult.cs, PaginatedRequest.cs, CacheScopeConverter.cs	Widen pagination constructors to protected; expose the existing cache-scope converter
Core discovery / OAuth / tool and prompt binding	Pause the probe budget during authorization while preserving caller/init cancellation, HTTP-timeout fallback and configured limits; keep injected parameters out of wire schemas without relying on reflection-object identity
ConformanceServer/Skills/ConformanceSkills.cs	New. Skill fixture; digests computed from the same bytes the resources serve
ConformanceServer/Program.cs, conformance fixture/tests	Register skills/resources, await owned host readiness, use assigned loopback ports and retain bounded startup/cleanup ownership
Skills protocol, server and client tests	New. Serialization, hostile responses, file/catalog ownership, pagination, policy alignment and regression coverage
Conformance package / runner tests	Pin alpha.12, select all three Skills scenarios explicitly for both revisions, and require successful native process exits
samples/SkillsServer, samples/SkillsClient, guide and link workflow	New. Serving and verified-consumption samples; preserve main links and validate same-repository paths against the proposed checkout

Validation

Local Windows results for source tree 26f58b0c, committed as 4837a3ff:

• Builds clean on net10.0, net9.0, net8.0, netstandard2.0 with warnings treated as errors
• Core and Skills pack/APICompat passed without breaking changes, including the Core 2.0.0 baseline; packages identify 4837a3ff
• Full .NET 10 Debug Core suite: 2,954 passed, 0 failed, four existing conditional skips
• Full .NET 10 Debug ASP.NET suite: 654 passed, 0 failed, 30 existing conditional skips
• Focused .NET 9/8 Debug: 716 Core and 147 ASP.NET cases passed per target, including the original OAuth/startup failures; net9 JSON reflection remains disabled
• Fresh committed-source .NET 10 Release: 716 Core and 147 ASP.NET cases passed, zero failed/skipped; expanded .NET Framework coverage passed 602 with 110 existing platform skips
• Native AOT win-x64 publish and execution passed; verified native PE, app returned Success!
• DocFX 2.78.5 warnings-as-errors and committed-tree Markdown link checks passed
• SEP-2640 conformance scenarios in pinned 0.2.0-alpha.12, run explicitly against the correct ConformanceServer endpoints:

Scenario	2025-11-25	2026-07-28
sep-2640-skills-enumeration	30/30	32/32
sep-2640-skills-manifest	6/6	6/6
sep-2640-skills-directory	1/1, 6 not applicable (directoryRead not declared)	1/1, 6 not applicable

All six scenario/version combinations passed on .NET 10/9/8 with Node 22.23.3 and strict process exits. A printed success summary cannot override a failed process. Earlier Node 24 aborts remain recorded, not retroactively green. Source-declared manual Docker cases were excluded and no live provider calls were enabled.

New-head hosted CI, including Linux/macOS, must be checked separately after publication.

resources/directory/read is not implemented in this PR, so directoryRead is not declared. Client wrappers are included; the results above are server-side conformance, not a claim to implement every host policy. Hosts must still parse fetched SKILL.md and compare frontmatter before loading. For YAML outside the bounded reader, explicit metadata remains the caller's full-validation responsibility. A maintained YAML library/provider, full host approval binding and origin isolation remain separate scope.

[Alumniminium]

Lets get this merged asap please

[PederHP]

At least one sample should be included imo.

[tarekgh]

@PederHP I see that you’ve opened PR #1864. Do you think we should keep both PRs, or would it make sense to close one in favor of the other?

[PederHP]

@PederHP I see that you’ve opened PR #1864: #1864. Do you think we should keep both PRs, or would it make sense to close one in favor of the other?

I think we should pick one. I was a little impatient when I made the other, as it represented what I'd like to have merged before the MCPCon in September. From what I remember the one I opened was more comprehensive, building on this one, and I put the author of this one as co-author of the foundational elements that I reused.

I would suggest having one or more agents compare the two and pick based on that.

[girishkvs]

@PederHP @tarekgh @Alumniminium

I compared #1856 and #1864 and found a few remaining gaps in #1864. I pulled Peder's changes into this #1856, preserving his authorship and crediting him as co-author, and then added my fixes on top of it.

I kept his client helpers, entry validation, file authoring, samples and docs. I also fixed the skills/get cache hints missing from both PRs.

Comparison and fixes

Compared sources

• Original Add SEP-2640 Skills extension support #1856: cbd8a588.
• Peder's Add the Skills extension (SEP-2640) as ModelContextProtocol.Extensions.Skills #1864: ecb11e62.
• Common comparison base: 3338e88e.
• Consolidated update: 6b0870cb.

Both PRs were compared on the same main. Both original heads had the old SourceLink NU1902 failure. The update already on main clears it; that isn't a new Skills fix.

Implementation comparison

Area	Original #1856	Peder's #1864	This update
Protocol foundation	Request/result types, SkillResources union, source-generated serialization, catalog and conformance fixtures	Reuses those foundations, with additional APIs and validation	Kept once, with the existing credit
Capabilities and version handling	Bare catalog registration lacks the resources declaration; current defaults and legacy resultType behavior have gaps	Declares resources, supplies list defaults and gates current-only fields	Peder's behavior retained, including older-protocol compatibility
skills/get cache hints	Missing	Missing	Added required ttlMs and cacheScope on current requests, including defaults and configured values; omitted on legacy requests
Request handling	Incorrectly typed uri/cursor can return InternalError	Typed parameter handling returns InvalidParams	Peder's handling retained
Catalog ownership	Caller-owned mutable entries	Defensive snapshots and keyset pagination	Peder's implementation retained
Caller context	Catalog interface has no request context	Catalog receives request context and caller identity	Retained; applications still need to apply their authorization policy consistently to entries and resources
Client APIs	No dedicated client helpers	Capability checks, list/get helpers and manifest-bound resource reads	Retained, including rejection of unlisted files and binding reads to the requested URI
Byte/file authoring	Application supplies metadata and resources	Manifest and served resources use the same copied bytes; directory helpers enforce file/URI boundaries	Retained
YAML convenience	Application supplies a JsonObject	Optional hand-written subset reader and automatic authoring	Reader retained; confirmed parsing errors fixed; unsupported-format and caller responsibilities stated explicitly
Samples and docs	No standalone Skills client/server samples	Both samples and a guide	Retained and updated; the client sample now parses fetched frontmatter and compares it before displaying the file
AOT and packaging	Generated metadata and pagination constructor changes	Adds Skills-specific AOT coverage and package integration	Retained, with additional assertions for our cache/parser changes

The stable spec added the skills/get cache requirement after both implementations. Both needed this fix; it doesn't invalidate their earlier conformance results.

Additional corrections

1. skills/get cache hints. Added ICacheableResult and set the fields in the raw handler. Defaults are 0 / private; configured values are honored. The interface alone wouldn't set them.
2. Next-line YAML values. Valid plain, quoted and nested values no longer fail because they start on the next line.
3. Folded TAB-led content. Kept the line breaks instead of silently replacing them with spaces.
4. Trailing comments. Require whitespace after a quoted or flow value before its comment. Plain values containing # still work.
5. Flow-collection keys. Kept the existing unsupported-YAML path so explicit metadata still works. Added regression cases alongside ordinary flow values and quoted keys.
6. Client sample verification. Kept the manifest, URI, digest and size checks. The sample now also parses fetched SKILL.md and compares its frontmatter before displaying it.
7. Docs and links. Clarified what the application, authoring helper and host each validate. Fixed the two sample links using a published source snapshot.

The trailing-comment check matches the yaml reference parser. Some other YAML libraries accept those forms, so this isn't a failure in every host.

Parser responsibility

I kept Peder's parser as an optional authoring helper. There's no new YAML dependency.

• Automatic authoring requires the bounded reader to succeed.
• With explicit metadata, the application must validate the complete file and supply matching JSON. Existing checks remain, but an unsupported-parser exception doesn't prove the rest of the YAML is valid.
• Hosts must independently parse fetched frontmatter and compare it field by field before loading. Digest verification alone is not enough.

This keeps the separation used in the TypeScript and Python proposals without dropping the authoring helpers. Go also separates digest checks from frontmatter verification. Those peer PRs were open when inspected, not released implementations.

The explicit-metadata fallback still can't validate the rest of a file after unsupported syntax. I haven't claimed that as a parser fix. The docs now state the caller's responsibility, and hosts must still verify the fetched file. A maintained YAML-library/provider can be a separate follow-up.

History and credit

3338e88e  Current main
  47b9db7d  Original implementation - Girish
    f3d028b7  Peder's additional implementation - Peder
      6b0870cb  Added fixes and responsibility alignment - Girish

Peder is the author of the import commit, which records #1864 and the source commits. Before our fixes, its full tree is ba9234da7a7a3ff5ad2a4e78ca9308a72ad004d9, identical to his selected head. Our fixes are separately authored.

Validation of the consolidated commit

These results are for 6b0870cb on Windows x64.

Check	Result
Complete Skills suite, .NET 10 / 9 / 8	470 passed on each target; zero failures or skips
Complete Skills suite, .NET Framework 4.7.2	466 passed; four modern-.NET-only symlink cases are not compiled on this target
Full non-manual .NET 10 suite	2,860 passed, zero failures, four declared skips
Pack and API compatibility	Passed; Core checked against the existing 2.0.0 baseline
NativeAOT, Windows x64	Published and executed the Skills list/get/read/verify and parser/cache assertions successfully
Source/artifact identity	Package metadata, informational versions and production SourceLink identify 6b0870cb; 31 PE/PDB pairs passed source/binary inspection
Client/server samples and documentation links	Samples passed; normal related and full documentation link checks reported zero errors
Skills conformance, 2026-07-28	39 applicable checks passed; all three scenario processes exited zero. Six optional directoryRead checks were not applicable
Skills conformance, 2025-11-25	Enumeration exited zero with 30 checks passed and two version-inapplicable cache checks. Manifest and directory processes aborted with UV_HANDLE_CLOSING after printing successful checks; neither process is counted green

The full-suite filter excludes two declared manual Docker cases. The four skips are two API-key-dependent cases, one unsupported-platform case and one optional-default-extraction limitation. No failing assertion or audit check was disabled.

The Windows legacy runner shutdown failure is still open. This isn't an all-green conformance matrix, and local results don't replace hosted CI.

Remaining scope and review decisions

• No new general YAML dependency, directoryRead support, full host implementation or general Core authorization hook is included.
• Package placement, the public reader and Core API changes still need maintainer review.
• Hosted CI hasn't run on this head. The earlier Ubuntu Debug OAuth failure isn't fixed by these Skills changes.
• Add the Skills extension (SEP-2640) as ModelContextProtocol.Extensions.Skills #1864 remains open; this update doesn't assume agreement to close it.

— girishkvs's Copilot 🤖

[PederHP]

Looks good. I made a PR (girishkvs#1) with some suggestions mostly related to docs and description. I was going to close #1864 so we can focus on getting this one over the finish line, but I was beat to it by a few minutes. Very much agree on joining forces and thank you for taking in what you did from the other one.

[Copilot]

🟡 Changes recommended

Protocol conformance, authorization exposure, validation gaps, and inaccurate PR metadata remain unresolved.

7 open findings

• Apply authorization to skill catalog handlers · New
• Require skills property to reject omitted response members · New
• Reject invalid UTF-8 in cursors · New
• Validate Unicode lowercase letters by scalar value · New
• Enforce string-only metadata values · New
• Document or revert unintended public converter API · New
• Document newly added public client wrappers · New

What changed in this PR

Adds SEP-2640 Skills support, including protocol models, server/client APIs, validation, samples, conformance fixtures, and AOT coverage.

Changes:

• Adds Skills discovery, retrieval, authoring, and integrity verification.
• Adds directory-backed and custom catalogs with pagination.
• Expands Core pagination and cache-converter APIs.

File	Description
README.md	Lists the Skills package.
ModelContextProtocol.slnx	Adds Skills projects and samples.
docs/​concepts/​index.md	Links Skills documentation.
docs/​concepts/​toc.yml	Adds Skills navigation.
docs/​concepts/​skills/​skills.md	Documents serving, consuming, and security.
src/​Directory.Build.targets	Includes Skills in package dependency versioning.
src/​PACKAGE.md	Lists the Skills package.
src/​ModelContextProtocol.Core/​Protocol/​CacheScopeConverter.cs	Makes the converter public.
src/​ModelContextProtocol.Core/​Protocol/​PaginatedRequest.cs	Allows external derivation.
src/​ModelContextProtocol.Core/​Protocol/​PaginatedResult.cs	Allows external derivation.
src/​ModelContextProtocol.Extensions.Skills/​ModelContextProtocol.Extensions.Skills.csproj	Defines the new package.
src/​ModelContextProtocol.Extensions.Skills/​SkillsProtocol.cs	Defines protocol constants and limits.
src/​ModelContextProtocol.Extensions.Skills/​McpSkillsJsonContext.cs	Adds AOT serialization metadata.
src/​ModelContextProtocol.Extensions.Skills/​SkillFrontmatter.cs	Implements bounded YAML frontmatter parsing.
src/​ModelContextProtocol.Extensions.Skills/​SkillValidation.cs	Validates skill entries and manifests.
src/​ModelContextProtocol.Extensions.Skills/​Protocol/​Skill.cs	Defines skill entries.
src/​ModelContextProtocol.Extensions.Skills/​Protocol/​SkillResource.cs	Defines manifest files.
src/​ModelContextProtocol.Extensions.Skills/​Protocol/​SkillResources.cs	Models static or dynamic manifests.
src/​ModelContextProtocol.Extensions.Skills/​Protocol/​SkillResourcesConverter.cs	Serializes the manifest union.
src/​ModelContextProtocol.Extensions.Skills/​Protocol/​ListSkillsRequestParams.cs	Defines list parameters.
src/​ModelContextProtocol.Extensions.Skills/​Protocol/​ListSkillsResult.cs	Defines paginated list results.
src/​ModelContextProtocol.Extensions.Skills/​Protocol/​GetSkillRequestParams.cs	Defines get parameters.
src/​ModelContextProtocol.Extensions.Skills/​Protocol/​GetSkillResult.cs	Defines get results.
src/​ModelContextProtocol.Extensions.Skills/​Server/​IMcpSkillCatalog.cs	Defines the catalog contract.
src/​ModelContextProtocol.Extensions.Skills/​Server/​InMemoryMcpSkillCatalog.cs	Implements keyset pagination.
src/​ModelContextProtocol.Extensions.Skills/​Server/​McpSkillPage.cs	Models catalog pages.
src/​ModelContextProtocol.Extensions.Skills/​Server/​McpSkillRequestContext.cs	Exposes caller context to catalogs.
src/​ModelContextProtocol.Extensions.Skills/​Server/​McpServerSkill.cs	Authors entries and file resources.
src/​ModelContextProtocol.Extensions.Skills/​Server/​McpServerSkillFile.cs	Models authored files.
src/​ModelContextProtocol.Extensions.Skills/​Server/​McpSkillsBuilderExtensions.cs	Registers Skills handlers and resources.
src/​ModelContextProtocol.Extensions.Skills/​Server/​McpSkillsOptions.cs	Configures caching hints.
src/​ModelContextProtocol.Extensions.Skills/​Client/​McpSkillsClientExtensions.cs	Adds client Skills operations.
src/​ModelContextProtocol.Extensions.Skills/​Client/​SkillVerifier.cs	Verifies resource integrity.
src/​ModelContextProtocol.Extensions.Skills/​Client/​SkillVerificationException.cs	Defines verification failures.
samples/​SkillsClient/​SkillsClient.csproj	Defines the client sample.
samples/​SkillsClient/​Program.cs	Demonstrates discovery and verification.
samples/​SkillsClient/​README.md	Documents the client sample.
samples/​SkillsServer/​SkillsServer.csproj	Defines the server sample.
samples/​SkillsServer/​Program.cs	Configures directory-backed skills.
samples/​SkillsServer/​README.md	Documents the server sample.
samples/​SkillsServer/​Properties/​launchSettings.json	Configures the sample endpoint.
samples/​SkillsServer/​Skills/​git-workflow/​SKILL.md	Adds a Git workflow skill.
samples/​SkillsServer/​Skills/​git-workflow/​references/​COMMIT_STYLE.md	Adds commit guidance.
samples/​SkillsServer/​Skills/​git-workflow/​templates/​PULL_REQUEST.md	Adds a pull-request template.
samples/​SkillsServer/​Skills/​refunds/​SKILL.md	Adds a refunds skill.
samples/​SkillsServer/​Skills/​refunds/​policy/​REFUND_POLICY.md	Adds refund policy data.
samples/​SkillsServer/​Skills/​refunds/​examples/​approved.md	Adds an approval response.
samples/​SkillsServer/​Skills/​refunds/​examples/​declined.md	Adds a decline response.
tests/​ModelContextProtocol.AotCompatibility.TestApp/​ModelContextProtocol.AotCompatibility.TestApp.csproj	Roots the Skills assembly for AOT.
tests/​ModelContextProtocol.AotCompatibility.TestApp/​Program.cs	Exercises Skills under AOT.
tests/​ModelContextProtocol.ConformanceServer/​ModelContextProtocol.ConformanceServer.csproj	References the Skills package.
tests/​ModelContextProtocol.ConformanceServer/​Program.cs	Registers conformance skills.
tests/​ModelContextProtocol.ConformanceServer/​Skills/​ConformanceSkills.cs	Defines conformance fixtures.
tests/​ModelContextProtocol.Tests/​ModelContextProtocol.Tests.csproj	References the Skills package.
tests/​ModelContextProtocol.Tests/​ClientServerTestBase.cs	Enables derived async cleanup.
tests/​ModelContextProtocol.Tests/​Protocol/​SkillSerializationTests.cs	Tests protocol serialization.
tests/​ModelContextProtocol.Tests/​Client/​McpSkillsClientValidationTests.cs	Tests hostile server responses.
tests/​ModelContextProtocol.Tests/​Client/​SkillVerifierTests.cs	Tests digest verification.
tests/​ModelContextProtocol.Tests/​Server/​InMemoryMcpSkillCatalogTests.cs	Tests catalog behavior.
tests/​ModelContextProtocol.Tests/​Server/​McpServerSkillAuthoringBoundaryTests.cs	Tests authoring boundaries.
tests/​ModelContextProtocol.Tests/​Server/​McpServerSkillTests.cs	Tests skill authoring.
tests/​ModelContextProtocol.Tests/​Server/​McpServerSkillsCatalogTests.cs	Tests custom catalogs.
tests/​ModelContextProtocol.Tests/​Server/​McpServerSkillsDefaultsTests.cs	Tests default cache hints.
tests/​ModelContextProtocol.Tests/​Server/​McpServerSkillsFromDirectoryTests.cs	Tests directory loading.
tests/​ModelContextProtocol.Tests/​Server/​McpServerSkillsIntegrityTests.cs	Tests content integrity.
tests/​ModelContextProtocol.Tests/​Server/​McpServerSkillsOwnershipTests.cs	Tests metadata and byte ownership.
tests/​ModelContextProtocol.Tests/​Server/​McpServerSkillsTests.cs	Tests end-to-end Skills behavior.
tests/​ModelContextProtocol.Tests/​Server/​SkillFrontmatterCorpusTests.cs	Tests parser compatibility corpus.
tests/​ModelContextProtocol.Tests/​Server/​SkillFrontmatterNodeClassificationTests.cs	Tests YAML node classification.
tests/​ModelContextProtocol.Tests/​Server/​SkillFrontmatterRegressionTests.cs	Adds parser regression coverage.
tests/​ModelContextProtocol.Tests/​Server/​SkillFrontmatterTests.cs	Tests frontmatter parsing.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[tarekgh]

Should we upgrade the conformance test package to 0.2.0-alpha.12 to ensure the added skills tests are covered? By the way, I already ran these tests against the PR, and all passed.

[girishkvs]

@tarekgh Re your alpha.12 question:

Pinned alpha.12 and added explicit Skills scenarios for both protocol revisions; a nonzero runner exit now fails even if stdout reports success, and the tests require actual executed checks.

— girishkvs's Copilot 🤖