ref(skills): remove sentry-sdk-upgrade and dissolve the workflow router

[evanpurkhiser]

Major-version SDK upgrades are docs-shaped, not skill-shaped — and that's now an explicit call rather than an inference. In this thread Lukas asked whether the planned v10→v11 JS migration skill should still ship; the answer was no, point users and agents at the docs migration guide instead:

Follow the instructions there https://docs.sentry.io/platforms/javascript/migration/v10-to-v11.md to upgrade my sdk

Span streaming went the same way this week — #306 removed those skills once getsentry/sentry-docs#18906 added a copy-prompt to the migration guides. sentry-sdk-upgrade is the same class of thing, so it gets the same treatment. Retiring it also empties the sentry-workflow router — it was the only child left after the code-review skills were removed in #283 — so this dissolves the router too.

What moves where. sentry-sdk-upgrade moves under skills-legacy/ rather than being deleted, the way #265 retired the other superseded skills: out of the plugin build and the drift automation, still resolvable for anything pointing at the old path. Its four version-migration references (v7-to-v8, v8-to-v9, v9-to-v10, upgrade-patterns) move with it, so nothing that was written down is lost while the docs guides become the forward path. The router itself is deleted rather than moved — a router that fronts nothing has nothing to serve.

One caveat on that choice: #265's rationale for the legacy tree was that skills.sentry.dev still serves it for existing URL consumers, and that's shakier than it was a day ago — the product onboarding prompts (getsentry/sentry#120939) and the docs copy-prompts (getsentry/sentry-docs#18897) have had skills.sentry.dev stripped out, and the domain's future is unsettled in the thread. Moving is still the right default since it's reversible and loses nothing, but if the call is that legacy is dead too, this collapses into a delete — which is what #306 chose.

Also drops the README/AGENTS listings and the workflow entries in the AGENTS skill-tree navigation, then regenerates SKILL_TREE.md. sentry-feature-setup is the last remaining router after this (dissolved in a follow-up), leaving 7 skills as the library migrates toward flat standalone skills. build-skill-tree.sh --check passes.

Two coordination notes:

• This and ref(skills): retire sentry-setup-ai-monitoring into sentry-instrument #286 both regenerate SKILL_TREE.md, so whichever merges second needs a trivial regen of that generated file.
• ref(skills): optimize the skill library — retire duplication, fix shipped dangling pointers #299 takes the opposite path for this skill — c089add0 renames it to sentry-js-sdk-upgrade and c545b256 fixes its v10 logger detection, keeping it shipping. The thread decision above is the tiebreaker: if migrations point at docs, there's no skill left to rename, so those two commits should come out of ref(skills): optimize the skill library — retire duplication, fix shipped dangling pointers #299.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want reviews to match your repository better? Bugbot Learning can learn team-specific rules from PR activity. A team admin can enable Learning in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit ef57592. Configure here.}

[cursor]

Upgrade prompt lacks skill

Medium Severity

After removing sentry-sdk-upgrade, the regenerated SKILL_TREE.md still tells agents to offer Upgrade Sentry SDK in “Start Here,” but the Workflows table below has no matching skill row. Users who pick that option get no skill to load from the index.

Additional Locations (1)

• src/SKILL_TREE.md#L33-L39

 

^{Reviewed by Cursor Bugbot for commit ef57592. Configure here.}

[sergical]

fwiw i pulled some stats before this skill was created that suggested that a large chunk of installs were on versions 7, 8 and 9 trailing behind the latest major.

i think theres a place for SDK upgrade skill somewhere as its pretty action oriented, but ill let you make the call.

[evanpurkhiser]

Both bot reports are valid — fixed. scripts/build-skill-tree.sh hardcodes the "Start Here" menu in its HEADER heredoc, and nothing validates those entries against the skill tables, so retiring the skill left - **Upgrade Sentry SDK** — Migrate to a new major version pointing at nothing. That line is gone and SKILL_TREE.md is regenerated.

Looking at that menu, it had drifted twice more:

• Configure a feature — AI/LLM monitoring, alerts, OpenTelemetry pipelines — AI monitoring is no longer a feature skill, so the AI wording moves up to "Set up Sentry" where sentry-instrument owns it. Fixed in ref(skills): retire sentry-setup-ai-monitoring into sentry-instrument #286, since that's the PR that caused it.
• Review code — Resolve Sentry bot comments or check for predicted bugs — dead since ref(skills): remove sentry-code-review and sentry-pr-code-review #283 removed those skills; pre-existing, and ref(skills): optimize the skill library — retire duplication, fix shipped dangling pointers #299 already fixes it in 198454e. Left alone here to avoid a third overlapping change.

The underlying gap is that the validator checks frontmatter, breadcrumbs and router tables but not the hardcoded menu, which is why this only surfaced via review. Worth adding a check that every menu entry resolves to a shipped skill — happy to do it as a follow-up rather than widen this PR.

[evanpurkhiser]

@sergical on the install-version stats — the demand signal is real, but the call went the other way this week, and not on frequency grounds: SDK migrations are docs-shaped, not skill-shaped.

In this thread Lms24 asked whether the planned v10→v11 JS migration skill should still ship and the answer was no — point users and agents at the migration guide instead:

Follow the instructions there https://docs.sentry.io/platforms/javascript/migration/v10-to-v11.md to upgrade my sdk

Span streaming went the same way: #306 removed those skills once getsentry/sentry-docs#18906 added the copy-prompt to the migration guides. So the trailing-major population still gets served, just through the docs guide rather than a skill we maintain in parallel — which is also why the four version references move to skills-legacy/ here instead of being deleted.

That does make c089add0 / c545b256 in #299 (rename to sentry-js-sdk-upgrade + the v10 logger-detection fix) mutually exclusive with this PR — if migrations point at docs there's no skill left to rename, so I think those two come out of #299.

[sentry]

Bug: Breadcrumb links in legacy skill files are broken because the parent sentry-workflow/SKILL.md file was deleted instead of being moved to the legacy directory.
_{Severity: LOW}

Suggested Fix

To fix the broken breadcrumb links, either update the links in the legacy skill files to remove the reference to the non-existent parent, or move the deleted sentry-workflow skill into the skills-legacy/ directory to restore the path.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: src/SKILL_TREE.md#L36-L41

Potential issue: The deletion of the `sentry-workflow` skill directory breaks breadcrumb
links in legacy skill files that depended on it. Specifically, files like
`skills-legacy/sentry-sdk-upgrade/SKILL.md` and
`skills-legacy/sentry-fix-issues/SKILL.md` contain a relative link
`../sentry-workflow/SKILL.md` which now points to a non-existent location. While these
skills are now in a `skills-legacy` directory and excluded from the main build, any user
or system accessing these legacy pages directly will encounter a broken link (404 error)
when trying to navigate to the parent skill. This degrades the user experience for
anyone accessing preserved legacy content.

Also affects:

• skills-legacy/sentry-sdk-upgrade/SKILL.md:10