Publish Skills schemas and validate specification examples in CI

.github/workflows/ci.yml

@@ -9,6 +9,18 @@ permissions:
   contents: read
 
 jobs:
+  schema:
+    name: Validate schema and specification examples
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run check:schema
+
   docs:
     name: Build documentation
     runs-on: ubuntu-latest

CONTRIBUTING.md

@@ -32,6 +32,26 @@ Pull requests build the website in CI, including contributions from forks.
 Broken internal page links fail the build. Cloudflare Pages builds the site with
 `npm run docs:build` and serves `.vitepress/dist`.
 
+## Schema Validation
+
+Run `npm run check:schema` before submitting schema or specification changes.
+This type-checks `schema/beta/schema.ts`, compares its declarations with the
+released specification, checks that the generated JSON Schema is current, and
+validates the JSON examples and regression fixtures. The schema CI job runs the
+same command on pull requests, including forks.
+
+Use `npm run generate:schemas` to regenerate `schema/beta/schema.json`. Generation
+and validation run offline after `npm ci`; they never fetch an SDK or a moving
+upstream schema. The base protocol types and their license notice are vendored
+at a commit pinned in `scripts/fetch-spec-types.mjs`. `npm run fetch:spec-types`
+reproduces that snapshot. A repin must be reviewed explicitly and followed by
+generation and validation.
+
+The Beta types mirror the released specification, which remains normative.
+Propose wire changes through the decision-log process rather than editing the
+released revision. Neither a schema pass nor an example pass establishes
+semantic conformance, host security, or consent handling.
+
 ## How to Participate
 
 This Working Group welcomes contributions from anyone interested in skills distribution over MCP. You can participate by:

README.md

@@ -34,6 +34,32 @@ The specification is a released revision and is not edited in place. The extensi
 
 For the case for serving skills over MCP, see the [official overview](https://modelcontextprotocol.io/extensions/skills/overview) and the Motivation section of [SEP-2640](https://modelcontextprotocol.io/seps/2640-skills-extension).
 
+## Machine-readable schema
+
+[`schema/beta/schema.ts`](schema/beta/schema.ts) exports the wire types in the
+released Beta specification. [`schema/beta/schema.json`](schema/beta/schema.json)
+is generated from those types using the base protocol's `typescript-json-schema`
+generator and integer-number convention. It uses JSON Schema 2020-12 and the
+identifier `https://modelcontextprotocol.io/ext-skills/beta/schema.json`.
+
+The JSON file is a container of named `$defs`, like the core MCP schema. Validate
+a specific definition (for example `#/$defs/ReadResourceDirectoryResult`), not
+the container itself. The artifact is available in this repository; its `$id`
+does not require a network lookup. It includes the base definitions needed by
+the extension and the message-flow examples, so validation can run offline.
+
+The released [specification](specification/beta/skills.mdx) remains normative.
+CI checks all of its TypeScript declarations against the exported types and
+validates every JSON message example, including base resource reads and errors.
+Type generation preserves inherited required fields such as request `_meta`,
+`ttlMs`, and `cacheScope`, without depending on an SDK's interpretation.
+
+This is structural validation. It does not enforce prose-only requirements such
+as digest integrity, manifest completeness, URI/frontmatter name agreement,
+consent, or the semantic requirement that successful skill results have
+`resultType: "complete"` (the published types inherit the base `ResultType`).
+Those still require semantic conformance tests and host-side checks.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for how to participate.

docs/decisions.md

@@ -408,3 +408,41 @@ The wire format of a successful exchange is otherwise unchanged. `skills/list` a
 - [Issue #156](https://github.com/modelcontextprotocol/ext-skills/issues/156) from @paulbalandan, which reports the compile error and proposes named params interfaces for both requests.
 - Base schema `2026-07-28`: `RequestParams`, `RequestMetaObject`, `PaginatedRequestParams` and `CacheableResult`.
 - [2026-09-08 entry](#2026-09-08-stable-spec-page-caching-attributes-on-skills-list-and-skills-get-and-the-resources-capability-dependency), the previous alignment of the page's types with the base schema.
+
+---
+
+### 2026-11-02: Publish machine-readable Skills extension types and validate examples in CI
+
+**Status:** Proposed
+
+**Context:** [Issue #158](https://github.com/modelcontextprotocol/ext-skills/issues/158)
+requests standalone types and JSON Schema for SDK authors. The released page
+defines its types in TypeScript blocks, but implementers cannot consume those
+as a schema artifact. The issue records a server omitting directory-read cache
+attributes while its own tests passed. PR #157 corrected the page's types; an
+automated check is needed to keep implementations and examples aligned.
+
+**Decision:** Publish `schema/beta/schema.ts` and generated `schema.json`, matching
+the current `specification/beta/skills.mdx` revision. Use the identifier
+`https://modelcontextprotocol.io/ext-skills/beta/schema.json` and JSON Schema
+2020-12 with named `$defs`, following the core schema's generator and integer
+convention. Vendor the referenced `2026-07-28` base types at an explicit commit
+so generation and validation are reproducible without network access.
+
+Keep the released page normative and unchanged. Check its TypeScript declarations
+against the exported interfaces, regenerate and compare the JSON artifact, and
+validate every JSON message example in CI. Include positive and negative
+directory-result fixtures to require both `ttlMs` and `cacheScope`. Subsequent
+wire changes still follow the existing draft/release process; this proposal
+neither changes the released wire format nor establishes a new release policy.
+
+**Rationale:** A reusable schema lets implementations test the published shapes
+instead of only testing what they already emit. A separate schema job catches
+drift regardless of the development tool used. Structural validation does not
+establish semantic or security conformance: prose-only constraints, integrity,
+and approval handling remain outside these generated types.
+
+**References:**
+- [Issue #158](https://github.com/modelcontextprotocol/ext-skills/issues/158), standalone schema request and implementation evidence.
+- [PR #157](https://github.com/modelcontextprotocol/ext-skills/pull/157), type and example alignment with the base schema.
+- [Tasks schema layout](https://github.com/modelcontextprotocol/ext-tasks/tree/main/schema), separate extension and base type artifacts.