[Schema][Server] Add Skills extension (io.modelcontextprotocol/skills) support

[wachterjohannes]

Summary

Implements the MCP Skills extension (SEP-2640): a way for servers to ship skills — multi-step workflow instructions that tell an agent how to orchestrate tools to reach a goal. Skills ride on the existing Resources primitive, mirroring the MCP Apps extension (io.modelcontextprotocol/ui). This PR adds no new protocol methods (the SEP's one optional method, resources/directory/read, is a planned follow-up — see below).

A server can expose a whole directory of skills in one line:

$server = Server::builder()
    ->setServerInfo('My Server', '1.0.0')
    ->addSkillsFromDirectory(__DIR__.'/skills')
    ->build();

This registers each SKILL.md (and its supporting files) as skill:// resources, derives the resource metadata from the YAML frontmatter, and serves a skill://index.json discovery index whose entries mirror each skill's frontmatter verbatim and carry a SHA-256 digest of the SKILL.md.

Optionally, skills can also be served as one-shot archives:

->addSkillsFromDirectory(__DIR__.'/skills', archiveFormats: ['application/gzip'])

What's included

• Schema/Extension/Skills/McpSkills — extension marker (EXTENSION_ID, MIME_TYPE, URI_SCHEME, ENTRY_POINT, DISCOVERY_URI, META_PREFIX).
• DTOs — SkillMetadata, SkillDiscoveryEntry (frontmatter + optional url/digest + optional archives), SkillDiscoveryIndex, SkillArchive — readonly, fromArray, omit-null jsonSerialize.
• Server/Skill/FrontmatterParser — splits SKILL.md into YAML frontmatter + body (handles BOM/CRLF; rejects non-mapping frontmatter).
• Server/Skill/SkillProvider — walks a directory, registers each skill and its supporting files as skill:// resources, enforces the spec's name↔final-path-segment rule, sanitizes schema-valid resource names (URIs keep real paths), guesses MIME types, guards against path traversal, mirrors frontmatter + digest into the index, and (when requested) serves packed archives.
• Server/Skill/SkillArchiver — deterministic ustar + gzip writer (no temp files, zeroed mtime/owner; SKILL.md at the archive root) for application/gzip.
• Server/Builder::addSkillsFromDirectory() — convenience that auto-enables the extension; takes archiveFormats.

Notable fix

ServerCapabilities::jsonSerialize() only cast the outer extensions map, so an extension with an empty payload (like Skills) serialized to [] instead of {}. The Apps extension never hit this because its payload is non-empty. Empty inner payloads are now coerced to {}.

Dependency

Adds symfony/yaml (^5.4 || ^6.4 || ^7.3 || ^8.0) for frontmatter parsing — the feature is non-functional without it.

Tests & docs

• Unit tests for the extension, DTOs, FrontmatterParser, SkillProvider, and SkillArchiver (PharData round-trip, determinism, the digest-matches-served-bytes invariant), plus a serialization regression test for the {} fix.
• Inspector stdio snapshot test (resources/list, resources/read of a SKILL.md, a supporting file, and the discovery index).
• Example server at examples/server/skills/; docs in docs/extensions.md.

Verified: phpstan (level 6) clean, php-cs-fixer clean, full unit suite green (812 tests), inspector skills test green.

Updates tracking the SEP

The SEP redesigned the discovery index after this PR opened; it has been brought in line:

• Index format — entries now mirror SKILL.md frontmatter verbatim and carry a digest; dropped the $schema field and the type/SkillType enum (the mcp-resource-template type was removed from the index in the redesign).
• Archives — added optional archive serving (application/gzip), listed under each entry's archives.

Deferred / follow-up

• resources/directory/read — the SEP's one optional method (scoped directory listing) plus the directoryRead capability flag.
• ZIP archives (application/zip) — the SEP requires at least one of gzip-tar or zip; gzip-tar is implemented.

[wachterjohannes]

For cross-reference, the downstream pieces are now open:

• Consumer: [Mate] Add Symfony bridge skills anticipating the MCP Skills extension symfony/ai#2132 — ships the first skills built on this PR in the Symfony "Mate" MCP server, colocated with the tools they orchestrate (two skills, one with a references/ subdirectory exercising the multi-file model).
• Working-group findings: docs(findings): PHP MCP SDK + Symfony AI Mate skills-as-resources experimental-ext-skills#95 — records this as the first PHP-ecosystem implementation of SEP-2640, including the spec-text frictions surfaced here (undefined _meta namespace, the resource-name charset constraint vs. the "name SHOULD equal frontmatter name" recommendation, and the empty-payload {}-vs-[] serialization fix).

Together: this PR is the transport, symfony/ai#2132 is the content, modelcontextprotocol/experimental-ext-skills#95 is the write-up.

[wachterjohannes]

Updated to track the recent SEP-2640 redesign and to round out the index entries:

• Index format realigned (2fb9722): entries now mirror the SKILL.md frontmatter verbatim and carry a SHA-256 digest; dropped the $schema field and the type/SkillType enum (the mcp-resource-template type was removed from the index in the redesign).
• Archives (634f81e): skills can now also be served as one-shot packed resources via addSkillsFromDirectory(..., archiveFormats: ['application/gzip']) — a deterministic .tar.gz per skill, listed under the entry's archives, with the index digest matching the served bytes.

All green: phpstan (level 6), php-cs-fixer, 812 unit tests, inspector snapshot. Description updated accordingly.

Remaining SEP surface, as a follow-up: the optional resources/directory/read method (+ directoryRead capability), and ZIP archives.

[chr-hertel]

Even without mate needing this, this could become interesting - keeping this open! I guess it needs a heavier rebase nowadays tho, since the extension part changed with v0.8.0

[wachterjohannes]

@chr-hertel yeah i also think that this is something important for the future! will rebase that in the next days