Repair Skills cache hints and frontmatter parsing

Add ICacheableResult and source-generated cache-hint serialization to
skills/get. Apply the configured hints or zero/private defaults on
2026-07-28 requests, and keep all versioned fields off 2025-11-25 replies.

Read scalar values starting on the next line, preserve folded line breaks
around TAB-led content, and reject comments without whitespace after a
quoted scalar or flow collection. Keep plain hashes, existing chomping
rules and non-JSON number rejection intact.

Add parser, authoring, wire and serialization regressions. Exercise the
new cache fields and authoring cases in the native AOT app. Update the
cache option docs and pin both sample links to their published source.

Author: girishkvs

docs/concepts/skills/skills.md

@@ -31,8 +31,19 @@ A skill entry (<xref:ModelContextProtocol.Extensions.Skills.Skill>) is a complet
   that cannot be digested.
 
 A host builds its registry from entries alone, then fetches files lazily with `resources/read` and verifies each
-one against the manifest. That verification, and the rule that an unlisted file is a change to the skill, is what
-lets a user's approval bind to specific content.
+one against the manifest. Before loading `SKILL.md`, it must also parse the fetched YAML and compare every
+frontmatter field with the held entry. Digest and size verification alone does not establish that equality.
+
+### Responsibility boundaries
+
+The protocol carries structured metadata; it does not require a particular parser or provider.
+
+| Layer | Responsibility |
+|---|---|
+| Application / catalog | Supply frontmatter identical to the complete frontmatter in the file, and serve matching file bytes and manifests. Structural entry validation does not read or validate the YAML on a catalog's behalf. |
+| Optional automatic authoring helper | `McpServerSkill.Create` / `CreateFromDirectory` without explicit metadata use the bounded `SkillFrontmatter` reader. Unsupported or malformed input is rejected, not replaced with guessed metadata. |
+| Explicit-metadata authoring | Keep the helper's enforced checks. If the bounded reader cannot fully read unsupported YAML, the application must parse and validate the entire frontmatter with a suitable mechanism and supply the correct JSON. |
+| Host | Independently parse fetched `SKILL.md` and compare its frontmatter with the held entry before loading, regardless of server authoring path. Reject unsupported input or use a suitable full parser; server-provided JSON is not verification. |
 
 ### Serving skills
 
@@ -75,7 +86,7 @@ var refunds = McpServerSkill.Create(
 builder.Services.AddMcpServer().WithHttpTransport().WithSkills([gitWorkflow, refunds]);
 ```
 
-All of these validate the skill against the specification and throw <xref:System.ArgumentException> with a
+All of these validate structural entry and file constraints and throw <xref:System.ArgumentException> with a
 specific message when, for example, the frontmatter `name` does not match the URI, `description` exceeds the
 Agent Skills limit of 1024 characters, a resource URI escapes the skill's directory, `SKILL.md` is missing, or
 the skill exceeds the per-skill limits of 512 files or 16 MiB. Frontmatter fields beyond `name`, `description`,
@@ -88,20 +99,28 @@ names containing characters with URI syntax (such as `{`, `?`, or a space) are p
 #### Frontmatter
 
 <xref:ModelContextProtocol.Extensions.Skills.SkillFrontmatter> reads the YAML frontmatter of a `SKILL.md` into a
-<xref:System.Text.Json.Nodes.JsonObject> without a YAML library. It accepts the subset of YAML that Agent Skills
-frontmatter uses: block mappings (nested up to 32 levels), block and flow sequences, plain, quoted, and block
+<xref:System.Text.Json.Nodes.JsonObject> without a YAML library. This is an optional bounded reader, not a
+requirement for serving structured metadata through a catalog. It supports block mappings (nested up to 32 levels), block and flow sequences, plain, quoted, and block
 scalars, and comments. Unquoted scalars are resolved per the YAML 1.2 core schema (`null`, booleans, integers, finite
-floats, otherwise strings), matching the YAML libraries used by other SDKs and by hosts. That matters because a
+floats, otherwise strings). YAML parsers can differ in their supported forms and resolution; identical semantics
+across other SDKs or libraries are not assumed. That matters because a
 host verifies a skill by parsing the fetched `SKILL.md` itself and comparing field by field against the published
 entry; a value that one side types as a number and the other as a string is a verification failure. Quote values
 such as version numbers that are meant to be strings.
 
-Anchors, aliases, tags, complex keys, nested and multi-line flow collections, and multi-line quoted scalars are
-valid YAML the reader does not support; it rejects them with a <xref:System.FormatException> naming the construct. For such a
-file, the `Create` and `CreateFromDirectory` overloads that take an explicit `JsonObject` supply the frontmatter
-directly. That escape hatch covers only valid-but-unsupported YAML: a file with no frontmatter block, malformed
-YAML, or invalid UTF-8 is rejected regardless, since no host could parse it either. When the reader can parse the
-file, an explicit object must match it exactly, or the skill is rejected at construction rather than by every host.
+Automatic authoring requires the bounded reader to succeed. Unsupported constructs and detected malformed input
+raise an error; no fallback object is invented. Unsupported forms include anchors, aliases, tags, complex keys,
+nested and multi-line flow collections, and multi-line quoted scalars.
+
+The explicit `JsonObject` overloads retain UTF-8 and frontmatter-boundary checks, entry/URI validation, and manifest
+digest/size computation from the served bytes. They also reject format errors detected by the reader and reject
+metadata that differs from a frontmatter block the reader can parse completely.
+
+**The explicit overloads do not guarantee whole-document YAML validation.** An unsupported construct can stop
+parsing before later content is examined. The application must parse and validate the **entire frontmatter**
+with a suitable mechanism and supply identical JSON before relying on that path. An unsupported-format error
+is not proof that the rest of the document is valid, and acceptance of supplied metadata is not proof of equality.
+This boundary does not relax the specification's requirement that published frontmatter match the file.
 
 #### Custom catalogs
 
@@ -128,7 +147,9 @@ the caller's <xref:System.Security.Claims.ClaimsPrincipal> when the transport su
 transport does), and any items that incoming-message filters attached to the request.
 
 A catalog supplies entries only; the skills' files must still be served as resources, since hosts read them with
-`resources/read`. A catalog may list only part of what it serves, or nothing at all, as long as `GetAsync` answers
+`resources/read`. The application/catalog author must supply frontmatter identical to the file. The transport
+validates entry structure, not full file contents, and does not require use of the optional authoring reader.
+A catalog may list only part of what it serves, or nothing at all, as long as `GetAsync` answers
 for every skill the server serves to the caller. Throw <xref:ModelContextProtocol.McpProtocolException> with
 <xref:ModelContextProtocol.McpErrorCode.InvalidParams> for a cursor the catalog cannot interpret.
 <xref:ModelContextProtocol.Extensions.Skills.InMemoryMcpSkillCatalog> is the built-in implementation over a fixed
@@ -139,14 +160,16 @@ set of entries and can be composed into a custom one.
 A skill whose content is generated on demand cannot publish stable digests. Set its entry's `Resources` to
 <xref:ModelContextProtocol.Extensions.Skills.SkillResources.Dynamic> and serve it through a catalog. Such a skill
 offers no content integrity, and hosts may decline to load it.
+If a host accepts a dynamic skill, parsing and comparing its fetched frontmatter is still required.
 
 #### Protocol versions and caching hints
 
-`skills/list` results carry the base protocol's `ttlMs` and `cacheScope` list-caching attributes, configured through
+`skills/list` and `skills/get` results carry the base protocol's `ttlMs` and `cacheScope` caching attributes, configured through
 <xref:ModelContextProtocol.Extensions.Skills.McpSkillsOptions>. Those attributes, and `resultType`, are defined
 from protocol revision `2026-07-28`. The SDK emits them only on requests negotiated under that revision or later,
 where they are required and default to `0` and `private` when unset, the same conservative defaults the built-in
-list methods use. On earlier revisions, which reject them as unrecognized keys, they are omitted.
+list methods use. On earlier revisions, which reject them as unrecognized keys, they are omitted. Both methods use
+the same configured hints. Only use `public` when both the listing and individual entries are identical for every caller.
 
 ### Consuming skills
 
@@ -155,6 +178,8 @@ host's side of the protocol:
 
 ```csharp
 using ModelContextProtocol.Extensions.Skills;
+using ModelContextProtocol.Protocol;
+using System.Text.Json.Nodes;
 
 if (!client.SupportsSkills())
 {
@@ -169,6 +194,19 @@ Skill skill = await client.GetSkillAsync("skill://git-workflow/SKILL.md");
 
 // Read a file and verify it against the held entry's digest and size.
 ReadResourceResult contents = await client.ReadSkillResourceAsync(skill, skill.Uri);
+
+// This example loads text SKILL.md resources and rejects other content forms.
+if (contents.Contents.Single(content => content.Uri == skill.Uri) is not TextResourceContents text)
+{
+    throw new SkillVerificationException("A text SKILL.md is required for this example.");
+}
+
+// A parse failure, including unsupported YAML, rejects this load. Do not fall back to skill.Frontmatter.
+var fetchedFrontmatter = SkillFrontmatter.Parse(text.Text);
+if (!JsonNode.DeepEquals(fetchedFrontmatter, skill.Frontmatter))
+{
+    throw new SkillVerificationException("The fetched frontmatter differs from the held entry.");
+}
 ```
 
 `ListSkillsAsync` and `GetSkillAsync` validate every entry the server returns against the specification's structural
@@ -206,10 +244,13 @@ specification places most of the burden on hosts. In particular:
   identity and URI.
 
 The SDK implements digest and size verification and the unlisted-file rule. It does not verify frontmatter against
-the fetched `SKILL.md` automatically. A host can do so with
+the fetched `SKILL.md` automatically. **The host must perform that independent check before loading**, regardless
+of whether the server used a catalog, automatic authoring, or explicit metadata. For the supported subset it can use
 <xref:ModelContextProtocol.Extensions.Skills.SkillFrontmatter.Parse(System.String)> on the fetched text and
 <xref:System.Text.Json.Nodes.JsonNode.DeepEquals(System.Text.Json.Nodes.JsonNode,System.Text.Json.Nodes.JsonNode)>
-against the entry's frontmatter, treating a parse failure or a difference as a verification failure.
+against the entry's frontmatter. Unsupported content must be rejected or parsed with a suitable full parser;
+malformed input or a difference is a verification failure. Never use the server's JSON as a substitute for parsing
+the fetched file. These examples do not implement the host's complete approval, origin-isolation or loading policy.
 
 ### Not implemented
 
@@ -218,7 +259,7 @@ Servers built with this package do not declare `directoryRead`, and hosts must n
 
 ### Samples
 
-- [SkillsServer](https://github.com/modelcontextprotocol/csharp-sdk/tree/main/samples/SkillsServer): a Streamable
+- [SkillsServer](https://github.com/modelcontextprotocol/csharp-sdk/tree/ecb11e621b0ae46685314729a74c0cb8fe283d44/samples/SkillsServer): a Streamable
   HTTP server serving two skills from directories on disk.
-- [SkillsClient](https://github.com/modelcontextprotocol/csharp-sdk/tree/main/samples/SkillsClient): a client that
+- [SkillsClient](https://github.com/modelcontextprotocol/csharp-sdk/tree/ecb11e621b0ae46685314729a74c0cb8fe283d44/samples/SkillsClient): a client that
   connects to it and discovers, retrieves, and verifies them.

samples/SkillsClient/Program.cs

@@ -3,7 +3,7 @@
 //   1. Connect over Streamable HTTP and check that the server declares the extension.
 //   2. Enumerate the skills with skills/list (the client extension follows pagination for you).
 //   3. Retrieve a single skill by URI with skills/get, as a host does for a URI mentioned in server instructions.
-//   4. Read the skill's files with resources/read and verify each one against the manifest's digest and size.
+//   4. Verify fetched bytes against the manifest, then independently parse and compare SKILL.md frontmatter.
 //   5. Show that a file the manifest does not list is refused before any request is sent.
 //
 // Start the SkillsServer sample first (dotnet run --project samples/SkillsServer). Pass a different endpoint as
@@ -12,6 +12,7 @@
 using ModelContextProtocol.Client;
 using ModelContextProtocol.Extensions.Skills;
 using ModelContextProtocol.Protocol;
+using System.Text.Json.Nodes;
 
 var endpoint = new Uri(args.Length > 0 ? args[0] : "http://localhost:3001");
 
@@ -63,12 +64,32 @@
 
 Console.WriteLine();
 
-// 4. Verified reads. ReadSkillResourceAsync issues resources/read and checks size and digest against the held
-//    entry; a mismatch throws SkillVerificationException and the content must not be used.
+// 4. ReadSkillResourceAsync checks manifest membership, URI, size and digest, not frontmatter.
+//    The host must independently verify frontmatter before loading, regardless of the server's authoring path.
 Console.WriteLine("=== resources/read (verified) ===");
 ReadResourceResult skillFile = await client.ReadSkillResourceAsync(skill, SkillUri);
-Console.WriteLine($"  {SkillUri} verified:");
-Console.WriteLine(Indent(((TextResourceContents)skillFile.Contents[0]).Text));
+if (skillFile.Contents.Single(content => content.Uri == SkillUri) is not TextResourceContents skillText)
+{
+    throw new SkillVerificationException("This sample requires text SKILL.md contents for frontmatter verification.");
+}
+
+try
+{
+    var fetchedFrontmatter = SkillFrontmatter.Parse(skillText.Text);
+    if (!JsonNode.DeepEquals(fetchedFrontmatter, skill.Frontmatter))
+    {
+        throw new SkillVerificationException("The fetched SKILL.md frontmatter differs from the held entry.");
+    }
+}
+catch (FormatException exception)
+{
+    // This sample rejects unsupported YAML. A full host may instead use a suitable full parser,
+    // but must never treat the server-provided JSON as verification of the fetched file.
+    throw new SkillVerificationException("The fetched SKILL.md frontmatter could not be verified.", exception);
+}
+
+Console.WriteLine($"  {SkillUri} manifest and frontmatter verified:");
+Console.WriteLine(Indent(skillText.Text));
 
 string supportingFileUri = skill.Resources.Resources.First(r => r.Uri != SkillUri).Uri;
 ReadResourceResult supportingFile = await client.ReadSkillResourceAsync(skill, supportingFileUri);

samples/SkillsClient/README.md

@@ -10,8 +10,9 @@ doing what a host's skill-loading path does:
    overload exposes the `ttlMs` and `cacheScope` hints).
 3. Retrieves one skill by URI with `skills/get` (`client.GetSkillAsync(uri)`), the way a host confirms a URI it
    found in server instructions.
-4. Reads the skill's files with `resources/read` and verifies each against the manifest's digest and size
-   (`client.ReadSkillResourceAsync(skill, uri)`).
+4. Reads the skill's files with `resources/read` and verifies manifest membership, URI, digest and size
+   (`client.ReadSkillResourceAsync(skill, uri)`). Before displaying `SKILL.md`, independently parses its
+   frontmatter and compares every field with the held entry.
 5. Shows that a file the manifest does not list is refused before any request is sent.
 
 ## Run
@@ -52,7 +53,7 @@ Expected output (abridged):
     ...
 
 === resources/read (verified) ===
-  skill://git-workflow/SKILL.md verified:
+  skill://git-workflow/SKILL.md manifest and frontmatter verified:
     | ---
     | name: git-workflow
     ...
@@ -65,5 +66,11 @@ Expected output (abridged):
 
 - Digest verification proves that the entry and the content are consistent. It is not a trust boundary: both come
   from the same server. Treat skill content as untrusted model input and tag it with its originating server.
-- The SDK does not verify frontmatter automatically. A host can re-parse the fetched `SKILL.md` with
-  `SkillFrontmatter.Parse` and compare it to the entry with `JsonNode.DeepEquals` before loading a skill.
+- Digest and size verification are not frontmatter verification. Every host must independently parse the
+  fetched `SKILL.md` and compare all fields with the held entry before loading, regardless of how the server
+  authored the metadata.
+- This sample accepts text `SKILL.md` resources and uses `SkillFrontmatter.Parse` for its supported subset.
+  It rejects mismatches, malformed input and unsupported YAML. A host needing other YAML forms must use a
+  suitable full parser, never the server-provided JSON as a verification fallback.
+- This is not a complete host implementation: approval binding, origin isolation and permission decisions
+  remain application responsibilities.

samples/SkillsServer/README.md

@@ -15,6 +15,11 @@ SHA-256 digest and size of every file, and registers the `skills/list` and `skil
 resources that serve the files, in one call. Each skill's URI is `skill://{name}/SKILL.md`, where `name` comes from
 its frontmatter; pass a `uriPrefix` to place skills under an organizational path such as `skill://acme/billing/`.
 
+This is the optional automatic provider path. Its bounded `SkillFrontmatter` reader rejects unsupported or
+malformed input rather than guessing metadata. Applications may instead supply structured metadata through a
+catalog. When using explicit-metadata authoring for unsupported YAML, the application must parse and validate
+the entire frontmatter and supply identical JSON; acceptance by the helper is not proof of full YAML validity.
+
 ## Run
 
 ```bash
@@ -39,5 +44,7 @@ Any MCP host that supports Streamable HTTP can also be pointed at `http://localh
   URI with `skills/get` and read it with `resources/read` without ever listing the catalog.
 - The listing is identical for every caller, so it advertises `cacheScope: public` with a five-minute `ttlMs`.
   A catalog that varies by principal must not do that.
+- Hosts must independently parse fetched `SKILL.md` and compare its frontmatter with the held entry before
+  loading, regardless of the server's authoring path. Digest/size checks alone do not perform that comparison.
 - See [docs/concepts/skills/skills.md](../../docs/concepts/skills/skills.md) for the full walkthrough,
   including how to implement a custom `IMcpSkillCatalog`.