feat(.ai): add consumer migration skill

.ai/README.md

@@ -219,6 +219,15 @@ Skills are used on-demand. When a task matches a skill’s purpose, the agent re
 - Use when: On the analyze-rendering-and-styling step for one or more components; creating one markdown file per component at `CONTRIBUTOR-DOCS/03_project-planning/03_components/[component-name]/rendering-and-styling-migration-analysis.md`
 - Provides: Workflow summary (specs from CSS + SWC, three-way DOM comparison, CSS⇒SWC mapping table, summary). Full instructions in `CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_analyze-rendering-and-styling/cursor_prompt.md`
 
+#### Consumer migration guide
+
+- **purpose**: Create per-component migration guides for application developers upgrading from 1st-gen Spectrum Web Components to 2nd-gen components
+- **How to invoke**: Say “create a consumer migration guide for [component]”, “write an upgrade guide for [component]”, or “document how consumers migrate [component] from 1st-gen to 2nd-gen”.
+- Use when: Writing one Storybook-renderable MDX file per component at `2nd-gen/packages/swc/components/[component-name]/consumer-migration-guide.mdx` with code updates, styling guidance, accessibility notes, testing changes, and rollout advice
+- Provides: Workflow summary (verified source inputs, required section order, before/after examples, migration checklist, rollout guidance). Full instructions in `.ai/skills/consumer-migration-guide/references/consumer-migration-guide-prompt.md`
+
+#### Washing machine migration workflow
+
 #### Migration — phase 1: prep (`migration-prep`)
 
 - **purpose**: Understand the component, plan breaking changes, and define scope before any refactoring begins

.ai/skills/consumer-migration-guide/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: consumer-migration-guide
+description: Use when creating a per-component migration guide for application developers upgrading from Spectrum 1 Web Components to Spectrum 2 components.
+globs: 2nd-gen/packages/swc/components/*/consumer-migration-guide.mdx
+alwaysApply: false
+---
+
+# Component migration: consumer guide
+
+Create per-component migration guidance for application developers upgrading app code from Spectrum 1 Web Components to Spectrum 2 components. The output should be practical and consumer-facing: what changed, what to update, how to test it, and how to roll it out safely.
+
+## When to use this skill
+
+- The user asks for a migration guide, upgrade guide, or consumer-facing migration doc for one or more components
+- You are documenting what application developers need to change when replacing a Spectrum 1 component with its Spectrum 2 equivalent
+- The guide needs rollout advice in addition to code updates, such as styling, accessibility, testing, and fallback considerations
+
+## How to invoke
+
+- Say "create a consumer migration guide for [component]"
+- Or say "write an upgrade guide for [component]" or "document how consumers migrate [component] from Spectrum 1 to Spectrum 2"
+- If the request is about maintainer-facing implementation analysis, use the migration-analysis skills instead
+
+## Quick reference
+
+### Output
+
+- **One `.mdx` file per component** at:
+  `2nd-gen/packages/swc/components/[component-name]/consumer-migration-guide.mdx`
+- The file is Storybook-renderable MDX. Start every guide with this template so it picks up the `Components` title prefix wired in `2nd-gen/packages/swc/.storybook/main.ts`:
+
+  ```mdx
+  import { Meta } from '@storybook/addon-docs/blocks';
+
+  <Meta title="[Component name]/Consumer migration guide" />
+
+  # [Component name] consumer migration guide
+  ```
+
+  Use sentence case for `[Component name]` (for example `Badge`, `Action button`). Do **not** include `Components/` in the `<Meta title>` — `titlePrefix` already adds it, so the doc renders at `Components/[Component name]/Consumer migration guide`.
+
+- Consumer migration guides live alongside the Spectrum 2 component source so the doc ships with the component code. Do **not** add them to `CONTRIBUTOR-DOCS/`.
+- **Do not link to project-planning / `CONTRIBUTOR-DOCS` docs** from the guide. Those are maintainer-facing; consumers don't need them. Link only to public consumer docs (e.g. the Spectrum 1 README on npm or the Spectrum 2 component Storybook page) when a link genuinely helps.
+- **Nav:** The guide lives in the component directory, so the `CONTRIBUTOR-DOCS` `update-nav.js` script does not manage it. Do not register it in `CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md`, and do not include auto-generated breadcrumbs or TOC markers intended for that script.
+- **MDX gotchas:** Keep bare tag names (`<sp-badge>`, `<swc-badge>`, etc.) wrapped in backticks in prose, and keep HTML/JS examples inside fenced code blocks. Avoid loose `{` / `}` outside code blocks; MDX parses them as JS expressions.
+
+### Required source inputs
+
+Verify claims against the real implementation and docs before writing:
+
+- **Spectrum 1 docs and source:** `1st-gen/packages/[component-name]/README.md`, public element files such as `sp-*.ts`, stories, and tests when needed
+- **Spectrum 2 docs and source:** `2nd-gen/packages/swc/components/[component-name]/src/`, stories, tests, and any package README or docs that describe the public API
+- **Related migration docs:** the component's `rendering-and-styling-migration-analysis.md` and `accessibility-migration-analysis.md` when present
+
+### Important
+
+- Write for **application developers upgrading their code**, not only for component maintainers
+- Prefer **before/after examples**, explicit upgrade actions, and rollout guidance over implementation detail
+- Ask clarifying questions for uncertain mappings instead of guessing
+
+### Scope: minimal, public API only
+
+The guide must be **short, direct, and consumer-focused**. Optimize for scannability: a consumer should be able to complete a simple migration in under 5 minutes of reading. Prefer tables, short numbered steps, and before/after snippets over prose. Cut anything that is not strictly required to update product code.
+
+**Spectrum 2 supersedes Spectrum 1.** Verify every claim — especially styling hooks and public custom property names — against the actual Spectrum 2 source (`2nd-gen/packages/swc/components/[component-name]/` and `2nd-gen/packages/core/components/[component-name]/`). Do not carry Spectrum 1 conventions (e.g. `--mod-*` prefixes) into the guide unless the Spectrum 2 implementation actually uses them.
+
+**Testing is out of scope.** Do not include sections on test selector updates, ARIA snapshot changes, or VRT approval. Consumers own their own tests; the guide's job is to explain what changed in the component, not how to re-test a consumer's app.
+
+**Accessibility bullets do not duplicate code examples.** If an a11y action is already covered as a numbered step in `## Update your code` (which must include before/after snippets), the Accessibility bullet links to that step instead of repeating the snippet. Only include a code example in `## Accessibility` for an action that is not covered in `## Update your code`.
+
+**Do not include an `### Unchanged` sub-section in `## What changed`.** Unchanged API requires no consumer action and adds noise. Limit `## What changed` to `### Renamed`, `### Added in Spectrum 2`, and `### Removed in Spectrum 2` (omit any sub-section with no entries).
+
+**Include (public API):**
+
+- Tag name and import path changes
+- Attributes, properties, and their values
+- Slots and slot names
+- Events
+- Supported CSS custom properties (`--mod-*` and documented theming hooks)
+- Accessibility expectations that affect the consumer's markup (e.g. `aria-label` on icon-only variants)
+- Behavior changes the consumer can observe (focus, wrapping, positioning)
+
+**Exclude (implementation detail):**
+
+- Internal shadow DOM structure or how it changed
+- Internal class-name renames (e.g. `spectrum-*` → `swc-*`); a single short "do not target internal classes or shadow DOM" caution is enough
+- `::part()` shadow parts unless one is explicitly part of the public API
+- Maintainer-facing rationale, migration sequencing, or implementation notes — link to the `rendering-and-styling-migration-analysis.md` instead
+
+**Structure the steps logically.** In "Update your code", present numbered steps in the order a consumer would actually perform them (for example: 1. update imports, 2. rename tags, 3. fix any consumer-facing accessibility gaps, 4. optionally adopt new attributes). Do not split content into parallel subsections when a short numbered flow reads better.
+
+## Full instructions
+
+For the exact document structure, required sections, source-verification expectations, writing rules, and checklist format, read:
+
+**.ai/skills/consumer-migration-guide/references/consumer-migration-guide-prompt.md**