modelcontextprotocol/ext-skills
Watch
1
0
Fork
You've already forked ext-skills
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ext-skills/CONTRIBUTING.md
Sambhav Kothari 41e7c66db2
 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>
2026-09-16 17:06:02 +02:00

6.1 KiB
Raw Permalink Blame History

Contributing

Documentation Website

Use Node.js 22 or later:

npm ci
npm run docs:dev

Before submitting a change, build and preview the production site:

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 when proposing changes. Navigation links to the condensed overview on the MCP website. 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:

  • Joining discussions in the #skills-over-mcp-wg Discord channel (info on joining the Discord server here)
  • Opening or commenting on GitHub Discussions in the main MCP repo
  • Sharing findings from your own implementations as GitHub issues
  • Contributing to documentation and pattern evaluation

Communication Channels

Channel Purpose Response Expectation
Discord #skills-over-mcp-wg Quick questions, coordination, async discussion Best effort
GitHub Discussions Meeting notes, long-form technical proposals, experimental findings Weekly triage
This repository The specification, decision log, and design rationale Updated after meetings

Coordination with the Agent Skills Spec

The Agent Skills spec is maintained in the agentskills/agentskills repository. For topics that intersect with both this WG and the Agent Skills spec (e.g., protocol design questions, proposed extensions, or alignment on terminology), the recommended channel is Discussions in that repository.

Before opening a discussion, review the Agent Skills contributing guide.

Meetings

Working Session cadence is defined in the charter; the schedule is published on meet.modelcontextprotocol.io. Meeting requirements — advance notice, agendas, and notes — follow MCP group governance.

Notes are published to Meeting Notes — Skills Over MCP WG. Scheduling surveys and between-meeting coordination happen in #skills-over-mcp-wg.

Decision-Making

Scope and per-decision-type authority are defined in the charter. The decision progression (lazy consensus → formal vote → escalation) follows MCP group governance.

Outputs include:

  • SEPs we shepherd from proposal through review (Extensions Track and related protocol changes)
  • Reference implementations demonstrating skill discovery and consumption
  • Documented requirements, evaluated approaches, and experimental findings

Contribution Guidelines

Sharing Implementation Findings

Findings from implementations are shared as GitHub issues rather than as documents in this repository. The pre-v1 findings and their template are frozen in docs/archive/. When reporting a finding:

  • Include enough detail for others to reproduce or evaluate
  • Note which clients and servers were tested, and the specification revision
  • Be explicit about what worked, what didn't, and what remains untested
  • Write "Not documented" for missing details instead of inferring them
  • Attribute community input with GitHub handles and link to the source where possible

Community Input

When adding quotes or input from community discussions:

  • Attribute to the contributor by name and GitHub handle
  • Link to the original source (Discord thread, GitHub comment, etc.) where possible
  • Present input as blockquotes to distinguish it from editorial content

Decision Log

Significant decisions made during meetings or through async discussion should be recorded in docs/decisions.md using the ADR-lite format defined there. A decision is worth logging when it:

  • Chooses one approach over alternatives
  • Sets or changes the group's scope
  • Establishes a convention or coordination mechanism

Add a new entry after the meeting where the decision was made or when consensus is reached asynchronously. Include context, the decision itself, rationale, and links to relevant issues, PRs, or discussion threads.

Filing Issues

Use GitHub Issues for:

  • Proposing new approaches or use cases
  • Reporting gaps in documentation
  • Tracking action items from meetings