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>
This commit is contained in:
Sambhav Kothari 2026-09-16 17:06:02 +02:00 • committed by GitHub
commit 41e7c66db2
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -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: