Repository navigation
Docs/migration skill - #2968
Docs/migration skill#2968KKonstantinov wants to merge 4 commits into
Conversation
Move the guide's text into skills/mcp-typescript-sdk-upgrade-to-v2/ (SKILL.md plus one reference file per subsystem) and assemble docs/migration/upgrade-to-v2.md from it with VitePress includes. The rendered page is unchanged. Add pnpm check:skills to validate the skill's frontmatter and internal links.
The migration guides link headings GitHub-style (#packaging--runtime), which is what GitHub and skills.sh render, but VitePress slugs punctuation differently (#packaging-runtime): 24 of 56 in-page links on the upgrade guide and 6 on the 2026-07-28 guide went nowhere on the site. Map each such anchor to the heading id VitePress generated, in the same core rule that now resolves the skill's links, and share the slug function with check:skills.
…cription GitHub renders frontmatter as a table and does not render include comments, so a source: field tells GitHub readers to edit the skill files; the site and llms.ts do not display it. The description, which llms.txt shows, no longer reads as a skill trigger.
|
@modelcontextprotocol/client
@modelcontextprotocol/codemod
@modelcontextprotocol/core
@modelcontextprotocol/server
@modelcontextprotocol/server-legacy
@modelcontextprotocol/express
@modelcontextprotocol/fastify
@modelcontextprotocol/hono
@modelcontextprotocol/node
commit: |
…s line count support-2026-07-28.md links into the upgrade guide with a GitHub-style anchor (#client-connection--dispatch). The page_links rule only maps in-page anchors, so the link still opened the guide at the top. It now uses the VitePress id. On GitHub, upgrade-to-v2.md shows only its Contents list, so the GitHub-style anchor no longer lands anywhere there. check:skills counted the empty element after the trailing newline, so it reported every SKILL.md one line long. It now counts the file's lines and enforces the spec's "under 500 lines". check:skills derives its root from import.meta.url, as skill.ts does: import.meta.dirname is undefined before Node 20.11, which engines allows, and the script runs in lint:all on pre-push. Three JSDoc blocks are now one line each. expandIncludes no longer claims that VitePress silently leaves the comment: that holds for a missing file, but for a missing region VitePress 1.6 includes the whole file. The throw catches both. Included content is trimmed of edge blank lines because the including page owns the spacing.
There was a problem hiding this comment.
Thanks for 007c199 — I re-read it and found no new bugs: the import.meta.url root, the trailing-newline line count with the >= 500 / "under 500" wording, the one-line JSDoc, and the #client-connection-dispatch anchor in support-2026-07-28.md all do what the commit message says. Because this is a ~1,900-line guide move plus new build tooling (page_links markdown-it rule, expandIncludes, check-skills.ts) that ships without tests, a maintainer's look at the skill-as-source design is still worthwhile.
What was reviewed this run: the four files in the fix commit against the earlier inline threads; the link-resolution path in scripts/check-skills.ts (fenced-code skipping, frontmatter field parsing, relative-link containment) for regressions from the root change — none found.
Extended reasoning...
The latest push (007c199) touches only docs/.vitepress/llms.ts, docs/.vitepress/skill.ts, scripts/check-skills.ts and docs/migration/support-2026-07-28.md, and each change matches the earlier inline feedback it cites. The PR as a whole moves the v1-to-v2 upgrade guide into skills/mcp-typescript-sdk-upgrade-to-v2/ and adds VitePress include/anchor-rewrite machinery plus a new lint wired into lint:all and check:all; it touches no auth, crypto or runtime SDK code. It is not approved because the change is large, introduces a new content-ownership model for the docs, and its new build scripts have no tests; two earlier optional inline threads (CRLF handling, cross-file duplicate heading ids) are not changed by this push.
Still open from earlier reviews (3):
- Unresolved: 3 minor or pre-existing.
Publish the v1→v2 upgrade guide as an Agent Skill that
npx skills addand skills.sh can find, without a second copy of the guide: its text moves intoskills/mcp-typescript-sdk-upgrade-to-v2/, anddocs/migration/upgrade-to-v2.mdassembles it with VitePress includes. The rendered page does not change.Motivation and Context
#2360 folded
docs/migration-SKILL.mdinto the guide ("this file IS the agent skill") because the two-file model had drifted. One source was the right call, but the guide never became installable:SKILL.mdin a folder named after itsname:.upgrade-to-v2.mdis neither, sonpx skills addfinds nothing and skills.sh lists no TypeScript SDK skill. What agents find instead are copies of the pre-docs: restructure migration guide — codemod-first, two-journey split, SKILL folded into upgrade-to-v2 #2360migration-SKILL.mdin other repos, and third-party skills that never mention the codemod.This keeps #2360's single source and reverses only "the guide file is the skill": the skill is now the source, and the docs page is a view of it.
Changes:
skills/mcp-typescript-sdk-upgrade-to-v2/—SKILL.md(167 lines: intro, quick path, what the codemod does and does not handle, a "read this reference when…" table, Need help) and onereferences/file per subsystem (32–286 lines). The text moved verbatim. Links between sections now cross files (references/auth.md#auth), and links to other docs pages are site URLs, so they work wherever the skill is installed.docs/migration/upgrade-to-v2.md—<!--@include-->directives (#regions ofSKILL.md, whole reference files) plus the Contents list. Asource:frontmatter field, which GitHub shows and the site does not, says where to edit. Thedescription:is reworded forllms.txtnow that the page is no longer the skill.docs/.vitepress/skill.ts,config.mts— on the assembled page, the skill's links map back to in-page anchors and relative links.docs/.vitepress/llms.ts— expands the includes for the markdown renditions, and throws on a missing file or region, where VitePress would leave the comment in the page (missing file) or include the whole file (missing region).pnpm check:skills(incheck:allandlint:all) —namematches the directory,descriptionis 1–1024 characters,SKILL.mdis under 500 lines, and every link inside the skill resolves (file and heading) without leaving it.docs/migration/index.md,CONTRIBUTING.md,docs/behavior-surface-pins.md— the install command, and where the guide is edited now.Anchor fix (second commit). The guides link headings GitHub-style (
#packaging--runtime), but VitePress slugs punctuation differently (#packaging-runtime). So 24 of the 56 in-page links on the upgrade guide, 5 of them in its Contents list, and 7 links onsupport-2026-07-28.mdwent nowhere on the site. They work on GitHub, which is how this went unnoticed. The skill has to keep GitHub-style anchors, since GitHub and skills.sh render it, so a markdown-it core rule points each in-page anchor that matches no heading id, but matches a heading's GitHub slug, at the id VitePress generated. Links that already resolve are untouched. The one link among them that points into another page, from the support page into the upgrade guide, now uses the VitePress id directly.How Has This Been Tested?
mainand on this branch and compared the output:migration/upgrade-to-v2.html: after the move, identical except the page's chunk hash (its frontmatter lostname:). After the anchor fix, exactly the 24 broken hrefs changed, each to the matching heading id.llms.txtchanges only in this page's description line, andllms-full.txtonly in the migration index section.#link on every built guide page, including links into other pages, against the target page's heading ids: 31 broken before, 0 after.npx skills@1.7.1 add <repo> --listfinds exactly one skill, with this name and description.check:skillsfails on a deliberately broken copy: name not matching the directory, missing heading, missing file, and a link leaving the skill.pnpm docs:devrenders the included content, and editing a skill file logs[vitepress] page reloadand reloads the open page.pnpm check:allpasses.Breaking Changes
None. The page's URL and all its anchors are unchanged. Contributors now edit the guide in
skills/mcp-typescript-sdk-upgrade-to-v2/rather than indocs/migration/upgrade-to-v2.md.No changeset: no package changes.
Types of changes
Checklist
Additional context
main'supgrade-to-v2.mdis in exactly one skill file, apart from the frontmatter, the Contents list and the---separators between sections, which stay in the page.docs/migration/upgrade-to-v2.mdshows only its frontmatter, including thesource:pointer, and the Contents list. The READMEs link the rendered site.mcp-typescript-sdk-upgrade-to-v2:npx skills addinstalls into a flat directory such as~/.claude/skills/, so the name carries the namespace;typescript-sdkkeeps it apart from a Python counterpart. A rename after publishing is costly, since skills.sh keeps old names listed.npx skills add modelcontextprotocol/typescript-sdk --skill mcp-typescript-sdk-upgrade-to-v2against the public repo.handlerRegistration.ts) and an error string inauth.tscite the repo pathdocs/migration/upgrade-to-v2.md; switch them to site URLs.@modelcontextprotocol/sdkshows, at the skill.