Publish Skills documentation with VitePress and Cloudflare Pages (#143)

Publish the Skills extension as a browsable VitePress site on Cloudflare
Pages, using the same documentation theme as ext-tasks and reusing the
existing source documents.

- Follow the Tasks site's structure: a substantive overview at `/` and a
separate stable specification page. The small `index.md` uses native
VitePress includes to reuse excerpts from the released specification,
rather than duplicating its prose.
- Link to the condensed overview on the MCP website.
- Render `specification/stable/skills.mdx` through a small Markdown
include, preserving the released specification unchanged.
- Add local search, section outlines, MCP branding, source edit links,
and a Specification navigation item with a Stable sidebar entry. Keep
the full specification at `/specification/stable/skills`.
- Build pull requests, including fork contributions, in read-only GitHub
Actions CI.
- Use the existing Cloudflare Pages Git integration for publishing.
Remove the GitHub Pages deployment workflow and project-path
configuration.

## Validation

- `npm run docs:build` passed with VitePress 1.6.4.
- Checked that the build emits an overview and a separate specification
page; verified included excerpt boundaries, internal links and anchors,
specification source edit links, and the rendered MDX callout.
- `git diff --check` passed.
- The build emits the existing large-chunk warning from the diagram
dependencies.
- Cloudflare deployment itself has not been run from this workspace.

## Publishing settings

DNS and Cloudflare Pages setup are ready separately. The existing Pages
project should use:

| Setting | Value |
| --- | --- |
| Repository | `modelcontextprotocol/ext-skills` |
| Production branch | `main` |
| Root directory | Repository root |
| Build command | `npm run docs:build` |
| Build output directory | `.vitepress/dist` |
| Node.js | `22` (set `NODE_VERSION=22` in Pages) |
| Custom domain | `skills.extensions.modelcontextprotocol.io` |

Cloudflare installs dependencies and builds from the committed npm
lockfile. The site is served at the domain root with clean URLs.
Publishing is handled by Cloudflare's connected Git integration; no
GitHub Pages environment, Pages permissions, or Cloudflare deployment
secrets in GitHub Actions are required.

After merge, verify the production deployment and custom domain in the
existing Cloudflare Pages project. One-time publishing instructions stay
in this PR description, not in a checked-in setup document.

Fork PRs receive the CI build check. Automated Cloudflare previews for
forks require the separately discussed trusted artifact-publishing
workflow; this PR does not add that workflow.

---------

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  docs:
+    name: Build documentation
+    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 docs:build

.gitignore

@@ -1 +1,4 @@
 .claude/settings.local.json
+node_modules/
+.vitepress/cache/
+.vitepress/dist/

.vitepress/config.mts

@@ -0,0 +1,71 @@
+import { defineConfig } from "vitepress";
+import { withMermaid } from "vitepress-plugin-mermaid";
+
+const repository = "https://github.com/modelcontextprotocol/ext-skills";
+
+export default withMermaid(
+  defineConfig({
+    title: "MCP Skills Extension",
+    description:
+      "Discover and read Agent Skills over the Model Context Protocol",
+    cleanUrls: true,
+    srcExclude: [
+      "README.md",
+      "SECURITY.md",
+      "CONTRIBUTING.md",
+      "AGENTS.md",
+      "CLAUDE.md",
+      "docs/**",
+    ],
+    head: [["link", { rel: "icon", href: "/mcp.png" }]],
+
+    markdown: {
+      config(md) {
+        // Excerpts retain cross-references to the complete specification.
+        md.core.ruler.before("block", "overview-links", (state) => {
+          if (state.env.relativePath === "index.md") {
+            state.src = state.src.replace(
+              /\]\(#([^)]+)\)/g,
+              "](/specification/stable/skills#$1)",
+            );
+          }
+        });
+        // Render the existing MDX specification's callout after Markdown inclusion.
+        md.core.ruler.before("block", "mdx-notes", (state) => {
+          state.src = state.src
+            .replace(/^<Note>\s*$/gm, "::: info\n")
+            .replace(/^<\/Note>\s*$/gm, ":::\n");
+        });
+      },
+    },
+
+    themeConfig: {
+      outline: [2, 3],
+      nav: [
+        { text: "Specification", link: "/specification/stable/skills" },
+        {
+          text: "SEP-2640",
+          link: "https://modelcontextprotocol.io/seps/2640-skills-extension",
+        },
+        {
+          text: "Working Group",
+          link: "https://modelcontextprotocol.io/community/working-groups/skills-over-mcp",
+        },
+      ],
+      sidebar: {
+        "/specification/": [
+          {
+            text: "Specification",
+            items: [{ text: "Stable", link: "/specification/stable/skills" }],
+          },
+        ],
+      },
+      socialLinks: [{ icon: "github", link: repository }],
+      search: { provider: "local" },
+      editLink: {
+        pattern:
+          "https://github.com/modelcontextprotocol/ext-skills/edit/main/specification/stable/skills.mdx",
+      },
+    },
+  }),
+);

CONTRIBUTING.md

@@ -1,5 +1,37 @@
 # Contributing
 
+## Documentation Website
+
+Use Node.js 22 or later:
+
+```sh
+npm ci
+npm run docs:dev
+```
+
+Before submitting a change, build and preview the production site:
+
+```sh
+npm run docs:build
+npm run docs:preview
+```
+
+The site follows the Tasks extension layout: an overview at `/` and a separate
+specification page. `index.md` includes excerpts from the released
+`specification/stable/skills.mdx` using VitePress Markdown includes; it does not
+maintain a second copy of that text. The include ranges refer to the stable
+snapshot; update them when switching the overview to a new revision.
+The adjacent `specification/stable/skills.md` includes the full specification
+text. Follow the [specification change process](AGENTS.md#proposing-changes-to-the-specification)
+when proposing changes.
+Navigation links to the condensed overview on the
+[MCP website](https://modelcontextprotocol.io/extensions/skills/overview).
+Working Group research and historical documents under `docs/` remain available on GitHub.
+
+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`.
+
 ## How to Participate
 
 This Working Group welcomes contributions from anyone interested in skills distribution over MCP. You can participate by:

index.md

@@ -0,0 +1,29 @@
+---
+title: Overview
+---
+
+# Overview
+
+<!-- Reuse excerpts from the released specification; ranges end before the next section. -->
+<!--@include: ./specification/stable/skills.mdx{21,28}-->
+
+<!--@include: ./specification/stable/skills.mdx{35,79}-->
+
+<!--@include: ./specification/stable/skills.mdx{243,246}-->
+
+<!--@include: ./specification/stable/skills.mdx{339,342}-->
+
+<!--@include: ./specification/stable/skills.mdx{429,442}-->
+
+<!--@include: ./specification/stable/skills.mdx{481,484}-->
+
+<!--@include: ./specification/stable/skills.mdx{443,446}-->
+
+For verification requirements and the skill-loading lifecycle, see
+[Integrity and Verification](/specification/stable/skills#integrity-and-verification).
+
+## Learn More
+
+- [Specification](/specification/stable/skills) — full protocol requirements, examples, and security considerations
+- [MCP Skills overview](https://modelcontextprotocol.io/extensions/skills/overview) — condensed examples and message flow
+- [SEP-2640](https://modelcontextprotocol.io/seps/2640-skills-extension) — the accepted proposal

package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@modelcontextprotocol/ext-skills",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Documentation for the MCP Skills extension",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "docs:dev": "vitepress dev",
+    "docs:build": "vitepress build",
+    "docs:preview": "vitepress preview"
+  },
+  "devDependencies": {
+    "mermaid": "^11.17.0",
+    "vitepress": "^1.6.4",
+    "vitepress-plugin-mermaid": "^2.0.17"
+  }
+}

specification/stable/skills.md

@@ -0,0 +1,6 @@
+---
+title: Skills
+---
+
+<!-- Keep the MDX file as the single source; skip its frontmatter. -->
+<!--@include: ./skills.mdx{5,}-->