41e7c66db2Publish 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>
110 lines
6.1 KiB
Markdown
110 lines
6.1 KiB
Markdown
# 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:
|
|
|
|
- Joining discussions in the [#skills-over-mcp-wg Discord channel](https://discord.com/channels/1358869848138059966/1464745826629976084) (info on joining the Discord server [here](https://modelcontextprotocol.io/community/communication#discord))
|
|
- Opening or commenting on [GitHub Discussions](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/categories/meeting-notes-skills-over-mcp-wg) 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](https://discord.com/channels/1358869848138059966/1464745826629976084) | Quick questions, coordination, async discussion | Best effort |
|
|
| [GitHub Discussions](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/categories/meeting-notes-skills-over-mcp-wg) | 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](https://agentskills.io/) is maintained in the [agentskills/agentskills](https://github.com/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](https://github.com/agentskills/agentskills/discussions) in that repository.
|
|
|
|
Before opening a discussion, review the [Agent Skills contributing guide](https://github.com/agentskills/agentskills/blob/main/CONTRIBUTING.md).
|
|
|
|
## Meetings
|
|
|
|
Working Session cadence is defined in the [charter](https://modelcontextprotocol.io/community/skills-over-mcp/charter#operations); the schedule is published on [meet.modelcontextprotocol.io](https://meet.modelcontextprotocol.io). Meeting requirements — advance notice, agendas, and notes — follow MCP [group governance](https://modelcontextprotocol.io/community/working-interest-groups#meeting-requirements).
|
|
|
|
Notes are published to [Meeting Notes — Skills Over MCP WG](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/categories/meeting-notes-skills-over-mcp-wg). Scheduling surveys and between-meeting coordination happen in [#skills-over-mcp-wg](https://discord.com/channels/1358869848138059966/1464745826629976084).
|
|
|
|
## Decision-Making
|
|
|
|
Scope and per-decision-type authority are defined in the [charter](https://modelcontextprotocol.io/community/skills-over-mcp/charter#authority-decision-rights). The decision progression (lazy consensus → formal vote → escalation) follows MCP [group governance](https://modelcontextprotocol.io/community/working-interest-groups#decision-making-process).
|
|
|
|
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](https://github.com/modelcontextprotocol/ext-skills/issues) rather than as documents in this repository. The pre-v1 findings and their template are frozen in [`docs/archive/`](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](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
|