Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
20 changes: 20 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
12 changes: 12 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,18 @@ 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 identifier names the current Beta revision. A Beta revision may make breaking changes, so the same identifier can name different content after a new revision ships. Pin to a commit of this repository if you need fixed content.

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.
23 changes: 23 additions & 0 deletions docs/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -408,3 +408,26 @@ 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:** Accepted

**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.

The directory and identifier use the lifecycle stage, `beta`, to match `specification/beta/`. [SEP-3392](https://modelcontextprotocol.io/seps/3392-extension-lifecycle) requires dated revision snapshots only at Stable. The Tasks extension keys its schema directory to the core protocol revision. That key would not be unique here, because a Beta extension can ship more than one revision against the same core revision. The identifier therefore names the current Beta revision and can name different content after a new revision ships. Consumers that need fixed content pin to a commit.

**References:**
- [Issue #158](https://github.com/modelcontextprotocol/ext-skills/issues/158), standalone schema request and implementation evidence.
- [PR #166](https://github.com/modelcontextprotocol/ext-skills/pull/166), the schema files, scripts and CI job.
- [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.
- [SEP-3392](https://modelcontextprotocol.io/seps/3392-extension-lifecycle), stage directories and revision rules.
Loading
Loading