feat(skill): add swc-consumer-migration skill for Spectrum 1 to 2 upgrades

[blunteshwar]

Description

Adds a new skill at 2nd-gen/packages/.ai/skills/swc-consumer-migration/ that helps consumers of Spectrum Web Components migrate their applications from 1st-gen (@spectrum-web-components/*) to 2nd-gen (@adobe/spectrum-wc).

The skill is invoked from a consumer's project (via Claude Code, Cursor, or Codex) and:

1. Runs a zero-dependency Node script that walks the consumer's node_modules, finds every Spectrum Web Components package, and copies each component's consumer-migration-guide.mdx into <cwd>/.swc-migration/guides/. A manifest.json lists every package found, with guidePath: null for packages that ship no guide. Supports both 1st-gen per-package layout and 2nd-gen single-package (@adobe/spectrum-wc) layout. Falls back to a local checkout via --repo=<path> when guides aren't shipped in node_modules yet.
2. Reads the consumer's package.json (and workspace package.jsons) to detect which Spectrum Web Components are in use, cross-references with the manifest, and surfaces the list for confirmation before any code changes.
3. Applies each component's guide to the consumer's source files component-by-component, with explicit checkpoints between components and a strict stop-conditions list (no version bumps, no lockfile edits, no installs, no out-of-scope file edits).

Files added (4):

• SKILL.md — entry point with frontmatter, preflight, three numbered steps, stop conditions, failure modes
• scripts/collect-guides.mjs — Node 18+, zero deps, supports --help, --cwd, --repo, --quiet
• references/usage.md — guide parsing rules, worked badge example, post-migration checklist
• references/template.md — canonical guide structure for component authors

Motivation and context

Consumers upgrading from Spectrum 1 to Spectrum 2 currently have to read each component's consumer-migration-guide.mdx by hand and apply changes manually. This skill turns that into a guided, automatable workflow that reuses the per-component guides authors already write under 2nd-gen/packages/swc/components/<name>/consumer-migration-guide.mdx (canonical location confirmed by inspecting badge).

The skill is opt-in and lives under 2nd-gen/packages/.ai/skills/, so it does not affect the published @adobe/spectrum-wc package or any component source.

Related issue(s)

• N/A — internal tooling addition

Screenshots (if appropriate)

N/A — no UI changes.

Author's checklist

• I have read the CONTRIBUTING and PULL_REQUESTS documents.
• I have reviewed the Accessibility Practices for this feature.
• I have added automated tests to cover my changes.
• I have included a well-written changeset if my change needs to be published.
• I have included updated documentation if my change required it.

Tests / changeset: this is an internal .ai/skills tooling addition with no shipped package effect, so no automated tests or changeset are added.

Reviewer's checklist

• Includes a Github Issue with appropriate flag or Jira ticket number without a link
• Includes thoughtfully written changeset if changes suggested include patch, minor, or major features
• Automated tests cover all use cases and follow best practices for writing
• Validated on all supported browsers
• All VRTs are approved before the author can update Golden Hash

Manual review test cases

• Help flag works

  1. From repo root: node 2nd-gen/packages/.ai/skills/swc-consumer-migration/scripts/collect-guides.mjs --help
  2. Expect a usage block listing --help, --cwd, --repo, --quiet and exit code 0.

• Repo-fallback collection works

  1. From a temp dir without Spectrum Web Components installed: node <repo>/2nd-gen/packages/.ai/skills/swc-consumer-migration/scripts/collect-guides.mjs --repo=<repo-checkout>
  2. Expect <temp>/.swc-migration/guides/badge.md to exist (badge is the only component with a guide today).
  3. Expect <temp>/.swc-migration/manifest.json to list the badge entry with a populated guidePath.

• node_modules detection works

  1. In a real consumer app whose package.json lists @spectrum-web-components/badge, run the script with no flags.
  2. Expect the badge guide to be collected from node_modules/@spectrum-web-components/badge/.

Device review

N/A — CLI script and skill markdown only.

Accessibility testing checklist

Documentation/tooling only; no component, no DOM, no interactive surface ships from this PR.

• Keyboard — N/A: no interactive parts. The skill itself instructs consumers to apply each component's documented accessibility deltas (e.g. aria-label for icon-only badges) per that component's consumer-migration-guide.mdx.
• Screen reader — N/A: no rendered content. The post-migration checklist in references/usage.md requires that every accessibility delta listed in a component's guide is either applied or flagged with a TODO(swc-migration): comment.

🤖 Generated with Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: 33b0739

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

📚 Branch Preview Links

• Documentation Site (first-gen)
• Storybook (first-gen)
• Storybook (second-gen)

🔍 First Generation Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

• Spectrum | Light | Medium | LTR
• Spectrum | Dark | Large | RTL
• Express | Light | Medium | LTR
• Express | Dark | Large | RTL
• Spectrum-two | Light | Medium | LTR
• Spectrum-two | Dark | Large | RTL
• High Contrast Mode | Medium | LTR

Deployed to Azure Blob Storage: pr-6233

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.