Skip to content

Commit b2e92aa

Browse files
PederHPclaude
andcommitted
Read skill frontmatter from SKILL.md
Requiring authors to restate a SKILL.md's frontmatter as a JsonObject was awkward and error-prone. SkillFrontmatter.Parse now reads it from the file without a YAML dependency, accepting the subset Agent Skills frontmatter uses (nested block mappings, block and flow sequences, plain, quoted, and block scalars, comments) and resolving unquoted scalars per the YAML 1.2 core schema, which matches the YAML libraries other SDKs and hosts use. Anchors, aliases, tags, multi-document streams, complex keys, and tab indentation are rejected with a FormatException naming the construct, since a guessed rendering would fail host-side verification. McpServerSkill gains Create(files), Create(uri, files), CreateFromDirectory(path), and CreateFromDirectory(uri, path), which read the frontmatter from SKILL.md and, where no URI is given, derive it from the frontmatter name as skill://{name}/SKILL.md. The overloads that take an explicit JsonObject remain for frontmatter the reader cannot handle; when the reader can parse the file, a supplied object that differs from it is rejected at construction, since hosts compare the two field by field. WithSkillsFromDirectory(path, uriPrefix) serves every immediate subdirectory containing a SKILL.md in one call. The server sample shrinks to a single WithSkillsFromDirectory call, the conformance fixture reads its frontmatter from the files, and the docs describe the reader, its limits, and the escape hatch. ClientServerTestBase gains a virtual DisposeAsync so fixtures can clean up temporary directories. Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01P6omaTvQiryHtzFHRqUE3b
1 parent 53e5425 commit b2e92aa

12 files changed

Lines changed: 1827 additions & 140 deletions

File tree

‎docs/concepts/skills/skills.md‎

Lines changed: 34 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -36,48 +36,45 @@ lets a user's approval bind to specific content.
3636

3737
### Serving skills
3838

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.
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:
4341

4442
```csharp
4543
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"));
5644

5745
builder.Services
5846
.AddMcpServer()
5947
.WithHttpTransport()
60-
.WithSkills([gitWorkflow], options =>
48+
.WithSkillsFromDirectory(Path.Combine(AppContext.BaseDirectory, "Skills"), configure: options =>
6149
{
6250
options.TimeToLive = TimeSpan.FromMinutes(5);
6351
options.CacheScope = CacheScope.Public;
6452
});
6553
```
6654

67-
`McpServerSkill.Create` takes the files explicitly when they are not on disk:
55+
Every immediate subdirectory containing a `SKILL.md` becomes a skill. The SDK reads the frontmatter from each
56+
`SKILL.md`, computes every digest and size from the same bytes the resources serve, registers the file resources,
57+
and publishes each skill at `skill://{name}/SKILL.md`, where `name` comes from the frontmatter. Pass a `uriPrefix`
58+
such as `skill://acme/billing/` to place the skills under an organizational path.
59+
60+
For finer control, build skills individually with <xref:ModelContextProtocol.Extensions.Skills.McpServerSkill> and
61+
register them with `WithSkills`:
6862

6963
```csharp
70-
var skill = McpServerSkill.Create(
71-
"skill://refunds/SKILL.md",
72-
new JsonObject { ["name"] = "refunds", ["description"] = "Process refunds." },
64+
var gitWorkflow = McpServerSkill.CreateFromDirectory(Path.Combine(skillsRoot, "git-workflow"));
65+
66+
var refunds = McpServerSkill.Create(
67+
"skill://acme/billing/refunds/SKILL.md",
7368
[
7469
McpServerSkillFile.FromText("SKILL.md", skillMarkdown),
7570
McpServerSkillFile.FromText("examples/approved.md", approvedTemplate),
7671
new McpServerSkillFile { Path = "assets/logo.png", Content = logoBytes },
7772
]);
73+
74+
builder.Services.AddMcpServer().WithHttpTransport().WithSkills([gitWorkflow, refunds]);
7875
```
7976

80-
Both methods validate the skill against the specification and throw <xref:System.ArgumentException> with a
77+
All of these validate the skill against the specification and throw <xref:System.ArgumentException> with a
8178
specific message when, for example, the frontmatter `name` does not match the URI, `SKILL.md` is missing, or the
8279
skill exceeds the per-skill limits of 512 files or 16 MiB. File contents are copied when the skill is created, so
8380
later changes to a caller's buffer or to files on disk do not affect what is served. `CreateFromDirectory` does not
@@ -86,10 +83,19 @@ names containing characters with URI syntax (such as `{`, `?`, or a space) are p
8683

8784
#### Frontmatter
8885

89-
The frontmatter is supplied as a <xref:System.Text.Json.Nodes.JsonObject> and must reproduce the YAML frontmatter
90-
at the top of `SKILL.md` exactly, field by field. Hosts re-parse the fetched `SKILL.md` and compare it against the
91-
entry, treating any discrepancy as a verification failure. The SDK does not include a YAML parser and does not
92-
derive the frontmatter from the file, so keep the two in sync.
86+
<xref:ModelContextProtocol.Extensions.Skills.SkillFrontmatter> reads the YAML frontmatter of a `SKILL.md` into a
87+
<xref:System.Text.Json.Nodes.JsonObject> without a YAML library. It accepts the subset of YAML that Agent Skills
88+
frontmatter uses: block mappings nested to any depth, block and flow sequences, plain, quoted, and block scalars,
89+
and comments. Unquoted scalars are resolved per the YAML 1.2 core schema (`null`, booleans, integers, finite
90+
floats, otherwise strings), matching the YAML libraries used by other SDKs and by hosts. That matters because a
91+
host verifies a skill by parsing the fetched `SKILL.md` itself and comparing field by field against the published
92+
entry; a value that one side types as a number and the other as a string is a verification failure. Quote values
93+
such as version numbers that are meant to be strings.
94+
95+
Anchors, aliases, tags, multi-document streams, complex keys, and tab indentation are rejected with a
96+
<xref:System.FormatException> naming the construct. For such a file, the `Create` and `CreateFromDirectory`
97+
overloads that take an explicit `JsonObject` supply the frontmatter directly. When the reader can parse the file,
98+
an explicit object must match it exactly, or the skill is rejected at construction rather than by every host.
9399

94100
#### Custom catalogs
95101

@@ -180,7 +186,10 @@ specification places most of the burden on hosts. In particular:
180186
identity and URI.
181187

182188
The SDK implements digest and size verification and the unlisted-file rule. It does not verify frontmatter against
183-
the fetched `SKILL.md`, since it does not parse YAML; a host must do that itself before loading a skill.
189+
the fetched `SKILL.md` automatically. A host can do so with
190+
<xref:ModelContextProtocol.Extensions.Skills.SkillFrontmatter.Parse(System.String)> on the fetched text and
191+
<xref:System.Text.Json.Nodes.JsonNode.DeepEquals(System.Text.Json.Nodes.JsonNode,System.Text.Json.Nodes.JsonNode)>
192+
against the entry's frontmatter, treating a parse failure or a difference as a verification failure.
184193

185194
### Not implemented
186195

‎samples/SkillsClient/README.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -39,12 +39,12 @@ Expected output (abridged):
3939
```
4040
=== skills/list ===
4141
caching hints: ttlMs=300000 cacheScope=Public
42-
skill://acme/billing/refunds/SKILL.md
43-
name: refunds
44-
...
4542
skill://git-workflow/SKILL.md
4643
name: git-workflow
4744
manifest: 3 file(s), 1523 bytes
45+
skill://refunds/SKILL.md
46+
name: refunds
47+
...
4848
4949
=== skills/get ===
5050
skill://git-workflow/SKILL.md (git-workflow)
@@ -65,5 +65,5 @@ Expected output (abridged):
6565

6666
- Digest verification proves that the entry and the content are consistent. It is not a trust boundary: both come
6767
from the same server. Treat skill content as untrusted model input and tag it with its originating server.
68-
- The SDK does not verify frontmatter (re-parsing the fetched `SKILL.md`'s YAML and comparing it to the entry),
69-
because it does not include a YAML parser. A host must do that itself before loading a skill.
68+
- The SDK does not verify frontmatter automatically. A host can re-parse the fetched `SKILL.md` with
69+
`SkillFrontmatter.Parse` and compare it to the entry with `JsonNode.DeepEquals` before loading a skill.

‎samples/SkillsServer/Program.cs‎

Lines changed: 7 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,20 @@
11
// Demonstrates serving Agent Skills over MCP with the Skills extension (SEP-2640) from a Streamable HTTP server.
22
//
33
// Each skill is a directory under ./Skills containing a SKILL.md and, optionally, supporting files.
4-
// McpServerSkill.CreateFromDirectory reads the files, computes the SHA-256 digest and size of each one, and
5-
// produces both the skill's entry (what skills/list and skills/get return) and the resources that serve the files
6-
// (what resources/read returns). WithSkills registers all of it.
7-
//
8-
// The frontmatter is supplied in code and must mirror the YAML frontmatter at the top of SKILL.md exactly. Hosts
9-
// re-parse the fetched SKILL.md and compare it field by field against the entry, and refuse the skill on any
10-
// discrepancy. The extension deliberately does not parse YAML.
4+
// WithSkillsFromDirectory reads every skill directory, parses the YAML frontmatter of each SKILL.md, computes the
5+
// SHA-256 digest and size of every file, and registers both the skills' entries (what skills/list and skills/get
6+
// return) and the resources that serve their files (what resources/read returns).
117

128
using ModelContextProtocol.Extensions.Skills;
139
using ModelContextProtocol.Protocol;
14-
using System.Text.Json.Nodes;
1510

1611
var builder = WebApplication.CreateBuilder(args);
1712

13+
// Every immediate subdirectory of ./Skills that contains a SKILL.md becomes a skill. The frontmatter is read from
14+
// each SKILL.md, and the skill's URI is skill://{name}/SKILL.md. Use McpServerSkill.CreateFromDirectory or
15+
// McpServerSkill.Create with WithSkills for finer control, for example an organizational URI prefix per skill.
1816
string skillsRoot = Path.Combine(AppContext.BaseDirectory, "Skills");
1917

20-
var gitWorkflow = McpServerSkill.CreateFromDirectory(
21-
uri: "skill://git-workflow/SKILL.md",
22-
frontmatter: new JsonObject
23-
{
24-
["name"] = "git-workflow",
25-
["description"] = "Follow this team's Git conventions for branching, commit messages, and pull requests.",
26-
["license"] = "MIT",
27-
},
28-
directoryPath: Path.Combine(skillsRoot, "git-workflow"));
29-
30-
// A nested skill path: the organizational prefix is "acme/billing" and the skill's name is "refunds".
31-
var refunds = McpServerSkill.CreateFromDirectory(
32-
uri: "skill://acme/billing/refunds/SKILL.md",
33-
frontmatter: new JsonObject
34-
{
35-
["name"] = "refunds",
36-
["description"] = "Process customer refund requests per company policy.",
37-
["metadata"] = new JsonObject { ["owner"] = "billing-team", ["version"] = "2.1.0" },
38-
},
39-
directoryPath: Path.Combine(skillsRoot, "refunds"));
40-
4118
builder.Services
4219
.AddMcpServer(options =>
4320
{
@@ -49,7 +26,7 @@
4926
"Before making commits in this repository, load the skill at skill://git-workflow/SKILL.md.";
5027
})
5128
.WithHttpTransport()
52-
.WithSkills([gitWorkflow, refunds], options =>
29+
.WithSkillsFromDirectory(skillsRoot, configure: options =>
5330
{
5431
// Every caller sees the same catalog, so the listing may be shared by intermediaries for a while.
5532
options.TimeToLive = TimeSpan.FromMinutes(5);

‎samples/SkillsServer/README.md‎

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,12 @@ Each skill is a directory under [`Skills/`](Skills) with a `SKILL.md` and suppor
88
| Skill URI | Files |
99
| ---------------------------------------- | -------------------------------------------------------------- |
1010
| `skill://git-workflow/SKILL.md` | `SKILL.md`, `references/COMMIT_STYLE.md`, `templates/PULL_REQUEST.md` |
11-
| `skill://acme/billing/refunds/SKILL.md` | `SKILL.md`, `policy/REFUND_POLICY.md`, `examples/approved.md`, `examples/declined.md` |
11+
| `skill://refunds/SKILL.md` | `SKILL.md`, `policy/REFUND_POLICY.md`, `examples/approved.md`, `examples/declined.md` |
1212

13-
`McpServerSkill.CreateFromDirectory` reads each directory, computes the SHA-256 digest and size of every file, and
14-
produces both the skill's entry and the resources that serve its files. `WithSkills` registers the `skills/list`
15-
and `skills/get` methods and the resources in one call.
16-
17-
The frontmatter is passed in code and must mirror the YAML at the top of each `SKILL.md` exactly. Hosts verify
18-
this and refuse a skill whose entry disagrees with its file. The extension does not parse YAML.
13+
`WithSkillsFromDirectory` reads every skill directory, parses the YAML frontmatter of each `SKILL.md`, computes the
14+
SHA-256 digest and size of every file, and registers the `skills/list` and `skills/get` methods together with the
15+
resources that serve the files, in one call. Each skill's URI is `skill://{name}/SKILL.md`, where `name` comes from
16+
its frontmatter; pass a `uriPrefix` to place skills under an organizational path such as `skill://acme/billing/`.
1917

2018
## Run
2119

@@ -35,8 +33,8 @@ Any MCP host that supports Streamable HTTP can also be pointed at `http://localh
3533

3634
## Notes
3735

38-
- Skill URIs are scoped to the server that serves them. The nested path `acme/billing/refunds` shows an
39-
organizational prefix; only the final segment must equal the skill's `name`.
36+
- Skill URIs are scoped to the server that serves them. A URI may carry an organizational prefix, as in
37+
`skill://acme/billing/refunds/SKILL.md`; only the final segment must equal the skill's `name`.
4038
- The server's instructions point the agent at `skill://git-workflow/SKILL.md` directly. A host can confirm a
4139
URI with `skills/get` and read it with `resources/read` without ever listing the catalog.
4240
- The listing is identical for every caller, so it advertises `cacheScope: public` with a five-minute `ttlMs`.

0 commit comments

Comments
 (0)