Publish Skills documentation with VitePress and Cloudflare Pages - #143
Conversation
There was a problem hiding this comment.
🟡 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.
There was a problem hiding this comment.
🔵 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-15says 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
ttlMsandcacheScoperequired onskills/get(specification/stable/skills.mdx:366,427-432). Final SEP-2640 explicitly leaves those fields open, and the corresponding local record is stillStatus: 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.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
🔵 Needs a closer look
It spans site configuration, dependencies, and GitHub Pages deployment, warranting final human review.
Review details
- Files reviewed: 8/11 changed files
- Comments generated: 0 new
- Review effort level: Lite (auto)
Note
Copilot is running an experiment and ran this review at Lite.
There was a problem hiding this comment.
🟡 Changes recommended
The overview presents a still-proposed skills/get caching requirement as normative protocol behavior.
Get a fresh assessment by requesting another Copilot review.
Review details
Suppressed comments (1)
index.md:167
- This repeats the proposed
skills/getcaching requirement as settled protocol. SEP-2640 only guarantees the skill entry (and showsresultType); whetherttlMsandcacheScopebelong on this result remains open there, while the local decision that adds them is still Proposed. Remove those two fields from the normative overview until that decision is accepted, or mark the extension explicitly as proposed.
The response contains a skill entry under `result.skill`, with the same shape
as an entry in `skills/list`, alongside `resultType: "complete"`, `ttlMs`,
and `cacheScope`. Clients can also use this method to refresh an existing entry.
- Files reviewed: 8/11 changed files
- Comments generated: 1
- Review effort level: Balanced
|
@copilot resolve the merge conflicts in this pull request |
# Conflicts: # README.md Co-authored-by: sambhav <16130816+sambhav@users.noreply.github.com>
Resolved by merging |
There was a problem hiding this comment.
🟡 Changes recommended
Contributor guidance and the specification edit link incorrectly encourage direct edits to the immutable stable snapshot.
Get a fresh assessment by requesting another Copilot review.
Review details
- Files reviewed: 7/10 changed files
- Comments generated: 2
- Review effort level: Balanced
There was a problem hiding this comment.
🔵 Needs a closer look
The specification edit link currently directs contributors to modify a released snapshot contrary to repository governance.
Review details
Suppressed comments (1)
.vitepress/config.mts:60
- The stable specification is a released snapshot that must not be edited in place (
AGENTS.md:10-16), but this special case sends the page’s “Edit this page” action directly to that snapshot. Point the action to the decision log—the required proposal vehicle—or disable it for this page so the published UI does not encourage bypassing the repository’s specification-change process.
editLink: {
pattern: ({ relativePath }) =>
`https://github.com/modelcontextprotocol/ext-skills/edit/main/${relativePath === "specification/stable/skills.md" ? "specification/stable/skills.mdx" : relativePath}`,
},
- Files reviewed: 7/10 changed files
- Comments generated: 0 new
- Review effort level: Balanced
Deploying ext-skills with
|
| Latest commit: |
1132f6d
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://4b99215a.ext-skills.pages.dev |
| Branch Preview URL: | https://docs-github-pages.ext-skills.pages.dev |
sambhav
changed the title
There was a problem hiding this comment.
🟢 Approval recommended
The configuration consistently implements the documented root-domain publishing workflow without altering the normative specification.
Review details
- Files reviewed: 5/8 changed files
- Comments generated: 0 new
- Review effort level: Balanced
There was a problem hiding this comment.
🟢 Approval recommended
The publishing configuration, source wrapper, redirects, dependency metadata, and CI workflow are consistent with the stated deployment design.
Review details
- Files reviewed: 6/9 changed files
- Comments generated: 0 new
- Review effort level: Balanced
There was a problem hiding this comment.
🟢 Approval recommended
The site configuration, redirects, dependency metadata, documentation, and read-only CI are consistent and preserve the normative specification unchanged.
Review details
- Files reviewed: 6/9 changed files
- Comments generated: 0 new
- Review effort level: Balanced
There was a problem hiding this comment.
🟡 Changes recommended
The overview’s edit link currently directs contributors to the specification source instead of index.md.
Get a fresh assessment by requesting another Copilot review.
Review details
- Files reviewed: 6/9 changed files
- Comments generated: 1
- Review effort level: Balanced
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.
/and a separate stable specification page. The smallindex.mduses native VitePress includes to reuse excerpts from the released specification, rather than duplicating its prose.specification/stable/skills.mdxthrough a small Markdown include, preserving the released specification unchanged./specification/stable/skills.Validation
npm run docs:buildpassed with VitePress 1.6.4.git diff --checkpassed.Publishing settings
DNS and Cloudflare Pages setup are ready separately. The existing Pages project should use:
modelcontextprotocol/ext-skillsmainnpm run docs:build.vitepress/dist22(setNODE_VERSION=22in Pages)skills.extensions.modelcontextprotocol.ioCloudflare 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.