Publish Skills documentation with VitePress and GitHub Pages

[sambhav]

Publish the Skills extension as a browsable documentation site, using the same VitePress theme as ext-tasks.

• Adapt the condensed overview from the MCP website's Skills page, including its examples and message-flow diagram.
• Render the existing specification/stable/skills.mdx directly through a Markdown include, preserving the specification source and its existing links.
• Add local search, specification navigation, MCP branding, and links to the SEP and Working Group.
• Build pull requests in CI and deploy main through GitHub Pages. The deployment reads Pages' base path so both the project URL and a custom domain work.
• Document local development. Publishing setup is recorded below.

Validation: production builds passed for / and /ext-skills/; generated internal page links, anchors, assets, favicon, and MDX callouts checked; JSON examples parsed and both sample file digests/sizes verified. Specification text is unchanged.

Publishing setup

The site uses the same VitePress theme as ext-tasks, with GitHub Actions building
and deploying to GitHub Pages. The tasks custom domain currently points to
Cloudflare Pages; this site uses GitHub Pages.

One-time Pages setup

An administrator must enable Pages with GitHub Actions as the source in
repository settings.
For a repository that has not enabled Pages, the equivalent authenticated GitHub
CLI command is:

gh api --method POST repos/modelcontextprotocol/ext-skills/pages -f build_type=workflow

Merge the website changes, or run the deployment workflow on main:

gh workflow run deploy.yml --repo modelcontextprotocol/ext-skills --ref main

The initial site is available at https://modelcontextprotocol.github.io/ext-skills/.
The workflow takes the base path from actions/configure-pages, so assets, search,
and navigation work at the project URL and after adding a custom domain.

Custom domain

Add this entry under the GitHub Pages sites in
modelcontextprotocol/dns/src/config/records.ts:

{ subdomain: 'skills.extensions', type: 'CNAME', content: 'modelcontextprotocol.github.io' },

The DNS repository's GitHub Actions workflow applies the record through Pulumi
after merge. Coordinate that merge with setting the Pages custom domain:

gh api --method PUT repos/modelcontextprotocol/ext-skills/pages \
  -f cname=skills.extensions.modelcontextprotocol.io
gh workflow run deploy.yml --repo modelcontextprotocol/ext-skills --ref main

Once DNS verification and GitHub's certificate provisioning complete, enable
Enforce HTTPS in Pages settings, or run:

gh api --method PUT repos/modelcontextprotocol/ext-skills/pages -F https_enforced=true

GitHub Actions deployments use the repository's Pages domain setting; a CNAME
file in the build artifact does not configure that setting. No custom deployment
token is needed for routine publishing: the deployment job uses GITHUB_TOKEN
with pages: write and id-token: write. The one-time setup commands require an
authenticated administrator; those credentials are not stored in the workflow.

After setup, every push to main publishes the latest overview and specification.
Check the github-pages environment URL in the deployment run to verify publication.

Companion DNS PR: modelcontextprotocol/dns#32 (closes modelcontextprotocol/dns#31). Coordinate its merge with the Pages custom-domain setup above.

[Copilot]

🟡 Changes recommended

The deployment build job needs Pages permission for actions/configure-pages to complete successfully.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds a VitePress documentation site for Skills with GitHub Pages publishing, local search, navigation, branding, and the existing specification rendered directly.

Changes:

• Adds overview content, examples, and specification inclusion.
• Adds development and publishing documentation.
• Adds CI and GitHub Pages deployment workflows.

File summaries

File	Summary
specification/stable/skills.md	VitePress wrapper for the existing specification
README.md	Links to the documentation site
package.json	Documentation tooling and scripts
package-lock.json	Locked dependencies
index.md	Skills overview content
docs/publishing.md	Pages and DNS setup instructions
CONTRIBUTING.md	Local documentation workflow
.vitepress/config.mts	Site configuration, navigation, search, and branding
.gitignore	Generated-file exclusions
.github/workflows/deploy.yml	GitHub Pages deployment workflow
.github/workflows/ci.yml	Documentation build validation

Review details

• Files reviewed: 8/11 changed files
• Comments generated: 1
• Review effort level: Lite (auto)

Note

Copilot is running an experiment and ran this review at Lite.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🔵 Needs a closer look

The site presents an unaccepted specification change as normative, and the deployment build lacks the Pages permission required by configure-pages.

Review details

Suppressed comments (2)

Previously missed (2) — in code that hasn't changed since the last review.

CONTRIBUTING.md:23

• AGENTS.md:3-15 says v1 comes from SEP-2640 and post-v1 changes must first be proposed in the decision log, with stable text updated only after acceptance. “Edit … for the full specification” omits both constraints and directs contributors to bypass that process. Identify this as the rendered local source and state the required proposal/acceptance flow.
  index.md:9
• Calling this the “full specification” publishes local requirements as normative, but the rendered source currently makes ttlMs and cacheScope required on skills/get (specification/stable/skills.mdx:366,427-432). Final SEP-2640 explicitly leaves those fields open, and the corresponding local record is still Status: Proposed (docs/decisions.md:338-354). Under the repository’s decision process, either accept and annotate that change before publishing, or clearly label/exclude this page as a proposal and link to the final SEP instead.

• Files reviewed: 8/11 changed files
• Comments generated: 0 new
• Review effort level: Balanced (auto)

Note

Copilot is running an experiment and ran this review at Balanced.