Skip to content

Publish Skills schemas and validate specification examples in CI - #166

Merged
olaservo merged 7 commits into
modelcontextprotocol:mainfrom
anencore94:feat/skills-schema-158
Nov 20, 2026
Merged

olaservo merged 7 commits into
modelcontextprotocol:mainfrom
anencore94:feat/skills-schema-158

Conversation

@anencore94

@anencore94 anencore94 commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Closes #158.

The released Skills page defines wire types in prose, so an implementation can omit required cache attributes while its own tests still pass. This adds consumable TypeScript and JSON Schema plus a CI job that checks the artifact, all 13 documented declarations, and all 16 JSON message examples.

  • schema/beta/schema.ts mirrors the released interfaces and imports a pinned, vendored copy of the 2026-07-28 base types. JSON generation uses the core specification's typescript-json-schema generator and integer-number convention; generation and validation are offline after dependency installation.
  • Regression fixtures reject directory results missing either ttlMs or cacheScope. Tests also cover inherited request metadata, cache constraints, dynamic manifests, type/JSDoc drift, and malformed or unmapped examples.
  • The released MDX is unchanged and remains normative. A Proposed decision-log entry records the schema layout and identifier. Structural validation does not establish semantic/security conformance, including digest verification, consent, or the prose-only resultType: "complete" requirement.

Validation (local): Initial validation on Node 22.23.4; follow-up self-review checks on Node 23.11.0, npm run check:schema (34 tests and all 16 examples pass); npm run docs:build; production preview HTTP smoke check; pinned base re-fetch produces identical artifacts; a deliberately stale JSON artifact is rejected without being rewritten; git diff --check. GitHub CI has not executed the jobs yet: run 41511523641 is action_required, with no job results available.

The schema layout and identifier are proposed in the decision log. The $id does not itself deploy a hosting endpoint. Automated code review is requested before further human review requests.

AI assistance: Codex assisted with implementation, local validation, and this description.

@anencore94
anencore94 requested a review from a team as a code owner November 2, 2026 19:36

Copy link
Copy Markdown
Contributor Author

@codex review

Please review the full PR at 6071129, especially schema conversion correctness, inherited base constraints, and false-success paths in the CI checks. Self-review fixes preserve literal/property names during conversion and validate examples before writing artifacts. Local schema checks pass (34 tests, 16 documented examples).

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 2, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-02T20:06:46.341257Z 6c32371 Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 60711295f0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread scripts/schema.mjs Resolved

Copy link
Copy Markdown
Contributor Author

@codex review

Addressed the completed resource-read validation finding in 6c32371. After validating the response envelope, the example checker now explicitly validates resultType: "complete" against ReadResourceResult. The released specification, vendored base types, and generated schema are unchanged.

Validation: eight negative regression cases reproduced the bypass before the fix; Node 22 check:schema now passes all 43 tests and 16 published examples. Positive coverage retains input-required responses and envelope validation. Both check and --write reject the original malformed-result reproducer without altering the existing schema artifact. Documentation build and git diff --check also pass.

Please re-review the latest commit, including the success-branch selection and regression coverage.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. You're on a roll.

Reviewed commit: 6c32371da1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Copy link
Copy Markdown
Contributor Author

@olaservo could you please approve the pending GitHub Actions CI run for this fork PR at 6c32371? The run is awaiting approval (action_required): https://github.com/modelcontextprotocol/ext-skills/actions/runs/41515671830

Local validation on Node 22 passed all 43 schema tests and 16 published examples; the documentation build also passed. Codex re-review of this head completed with no findings: #166 (comment)

This is a request to authorize CI execution only; I'm not requesting a code review yet. Thank you!

@olaservo

olaservo commented Nov 3, 2026

Copy link
Copy Markdown
Member

Hi @anencore94 I just approved CI to run.

@XVincentX

Copy link
Copy Markdown

Is there any chance to get this one in? It would help out for validation!

@anencore94

Copy link
Copy Markdown
Contributor Author

@XVincentX Could you available to review this PR @olaservo ?

@XVincentX

Copy link
Copy Markdown

I do not believe I have the necessary privileges to merge this

olaservo and others added 4 commits November 19, 2026 20:20
Record why the schema directory and $id use the lifecycle stage, and
that the $id is not a fixed reference across Beta revisions.

Unwrap the README and decision-log additions to one line per paragraph,
as the rest of both files.

Select the list and get results in the tests by method, and import from
schema.mjs once.

Normalize CRLF before comparing schema.json. The check failed on a
Windows checkout with core.autocrlf=true.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

@olaservo olaservo left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this, and for the patience! I reviewed it against the pinned upstream commit and the core spec's generator settings, and both match.

I pushed two commits to your branch before merging:

e6b9ea7:

  • README.md and docs/decisions.md: record why the directory and $id use beta. SEP-3392 requires dated revisions only at Stable, and a Beta extension can ship more than one revision against the same core revision. The $id names the current Beta revision, so consumers that need fixed content pin to a commit.
  • README.md and docs/decisions.md: unwrap the additions to one line per paragraph, as the rest of both files.
  • docs/decisions.md: add this PR and SEP-3392 to the entry's references.
  • scripts/schema.test.mjs: select the list and get results by method, and import from schema.mjs once.
  • scripts/schema.mjs: normalize CRLF before comparing schema.json. The check failed on a Windows checkout with core.autocrlf=true.

e18b0a2:

  • docs/decisions.md: set the 2026-11-02 entry to Accepted.

@olaservo
olaservo merged commit dbb463d into modelcontextprotocol:main Nov 20, 2026
2 checks passed
@XVincentX

Copy link
Copy Markdown

Thanks @olaservo - would it be possible to also cut a GitHub release? That helps people that want to download the file for their own validation purposes - thanks!

@olaservo

Copy link
Copy Markdown
Member

Thanks @olaservo - would it be possible to also cut a GitHub release? That helps people that want to download the file for their own validation purposes - thanks!

Hi @XVincentX , I published v0.1.0 as a pre-release with schema.json and the TypeScript types attached. I marked as pre-release since the extension is labeled beta to match our latest extension release cycle vocab. Hope that works!

@XVincentX

Copy link
Copy Markdown

That will absolutely do - thanks

@anencore94
anencore94 deleted the feat/skills-schema-158 branch November 20, 2026 21:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Publish a standalone schema for the skills extension shapes

3 participants