diff --git a/packages/dev/s2-docs/scripts/generateAgentSkills.mjs b/packages/dev/s2-docs/scripts/generateAgentSkills.mjs
index e9e019140bf..fad7543e989 100644
--- a/packages/dev/s2-docs/scripts/generateAgentSkills.mjs
+++ b/packages/dev/s2-docs/scripts/generateAgentSkills.mjs
@@ -27,6 +27,10 @@ const REPO_ROOT = path.resolve(__dirname, '../../../../');
 const MARKDOWN_DOCS_DIST = path.join(REPO_ROOT, 'packages/dev/s2-docs/dist');
 const MDX_PAGES_DIR = path.join(REPO_ROOT, 'packages/dev/s2-docs/pages');
 const MARKDOWN_DOCS_SCRIPT = path.join(__dirname, 'generateMarkdownDocs.mjs');
+const CODEMOD_S1_TO_S2_DIR = path.join(
+  REPO_ROOT,
+  'packages/dev/codemods/src/s1-to-s2'
+);
 const WELL_KNOWN_DIR = '.well-known';
 const WELL_KNOWN_SKILLS_DIR = 'skills';
 
@@ -45,6 +49,20 @@ const SKILLS = {
       website: 'https://react-spectrum.adobe.com/'
     }
   },
+  'react-spectrum-v3-to-s2-migration': {
+    name: 'react-spectrum-v3-to-s2-migration',
+    description:
+      'Migrate React Spectrum v3 codebases to Spectrum 2. Use when upgrading from @adobe/react-spectrum or @react-spectrum/* packages to @react-spectrum/s2, running the s1-to-s2 codemod, or resolving TODO(S2-upgrade) follow-ups.',
+    license: 'Apache-2.0',
+    sourceDir: 's2',
+    compatibility:
+      'Requires a React project migrating from React Spectrum v3 to @react-spectrum/s2.',
+    metadata: {
+      author: 'Adobe',
+      website: 'https://react-spectrum.adobe.com/'
+    },
+    mode: 'migration'
+  },
   'react-aria': {
     name: 'react-aria',
     description:
@@ -283,11 +301,8 @@ function categorizeEntries(entries, sourceDir) {
   return categories;
 }
 
-/**
- * Generate the SKILL.md content
- */
-function generateSkillMd(skillConfig, categories, isS2) {
-  const frontmatter = `---
+function getSkillFrontmatter(skillConfig) {
+  return `---
 name: ${skillConfig.name}
 description: ${skillConfig.description}
 license: ${skillConfig.license}
@@ -298,6 +313,13 @@ metadata:
 ---
 
 `;
+}
+
+/**
+ * Generate the SKILL.md content
+ */
+function generateSkillMd(skillConfig, categories, isS2) {
+  const frontmatter = getSkillFrontmatter(skillConfig);
 
   let content = frontmatter;
 
@@ -386,6 +408,393 @@ The \`references/\` directory contains detailed documentation organized as follo
   return content.trimEnd() + '\n';
 }
 
+function generateMigrationSkillMd(skillConfig) {
+  let content = getSkillFrontmatter(skillConfig);
+
+  content += `# React Spectrum v3 to S2 Migration
+
+Use this skill when upgrading a React Spectrum v3 codebase to Spectrum 2.
+
+> **Tip:** For full S2 component API documentation, install the \`react-spectrum-s2\` skill or the React Spectrum S2 MCP server alongside this migration skill.
+
+## Prerequisites (check before starting)
+
+- **Install \`@react-spectrum/s2\` FIRST** — the codemod requires it at runtime to resolve the list of available S2 components. Without it, the codemod silently produces 0 transformations.
+- **Verify npm/yarn registry access** — in corporate environments with private registries, you may need to configure your scoped registry for \`@react-spectrum\`, or use \`--registry https://registry.npmjs.org\` for public packages.
+- **Yarn PnP users**: use \`yarn dlx\` instead of \`npx\`. Ensure \`@react-spectrum/s2\` is resolvable by jscodeshift workers (you may need \`nodeLinker: node-modules\` or a symlink workaround, since PnP virtual resolution is not visible to jscodeshift subprocesses).
+
+## Migration workflow
+
+1. Install \`@react-spectrum/s2\` in each workspace that uses React Spectrum.
+2. Run a dry codemod pass to preview migration edits.
+3. Run the codemod in apply mode.
+4. Optionally scope to specific components with \`--components\`.
+5. Resolve remaining \`TODO(S2-upgrade)\` comments manually (see the resolution guide below).
+6. Migrate components the codemod skips (see the skipped components section below).
+7. Configure bundler for style macro support.
+8. Add \`page.css\` import to app entrypoints.
+9. Migrate icons from \`@spectrum-icons/workflow/*\` to \`@react-spectrum/s2/icons/*\`, and illustrations from \`@spectrum-icons/illustrations/*\` to \`@react-spectrum/s2/illustrations/linear/<Name>\` or \`@react-spectrum/s2/illustrations/gradient/generic1/<Name>\`.
+10. Clean up imports (see the import cleanup section below).
+11. Update Provider/theme setup and verify (see the verification section below).
+
+## Codemod commands
+
+\`\`\`bash
+# Install S2 first (required for codemod to work)
+npm install @react-spectrum/s2
+# or: yarn add @react-spectrum/s2
+
+# Preview changes without writing files
+npx @react-spectrum/codemods s1-to-s2 --agent --dry --path .
+
+# Apply migrations
+npx @react-spectrum/codemods s1-to-s2 --agent --path .
+
+# Scope to specific components
+npx @react-spectrum/codemods s1-to-s2 --agent --path . --components=Button,TextField
+\`\`\`
+
+## Monorepo considerations
+
+- In a monorepo, run the codemod per-workspace or use \`--path ./packages\` to target all workspaces at once. Ensure \`@react-spectrum/s2\` is hoisted or available in each workspace's resolution scope.
+- The codemod spawns jscodeshift workers as subprocesses. These workers must be able to \`require.resolve('@react-spectrum/s2')\` — ensure it is in \`node_modules\`, not only in PnP virtual resolution.
+- The \`--agent\` flag skips interactive prompts, package installation, and macro setup, but still requires \`@react-spectrum/s2\` to be installed and resolvable.
+
+## Known codemod limitations
+
+- Does NOT update \`package.json\` (add S2, remove v3 packages).
+- Does NOT migrate all individual \`@react-spectrum/*\` package imports (e.g., \`@react-spectrum/toast\`, \`@react-spectrum/utils\`). Rewrite these manually to \`@react-spectrum/s2\` where S2 equivalents exist.
+- Does NOT handle \`@react-types/*\` imports — audit and remove after migration since types are re-exported from \`@react-spectrum/s2\`.
+- \`@react-aria/*\` and \`@react-stately/*\` packages remain compatible with S2 and do not need migration.
+
+## Components the codemod skips
+
+The following components have no automated transform and require fully manual migration:
+
+- **Accordion** — restructure to use \`Disclosure\`, \`DisclosureTitle\`, and \`DisclosurePanel\`:
+  \`\`\`jsx
+  // Before (v3)
+  <Accordion>
+    <Item key="one" title="Section One">Content one</Item>
+  </Accordion>
+
+  // After (S2)
+  <Accordion allowsMultipleExpanded>
+    <Disclosure id="one">
+      <DisclosureTitle>Section One</DisclosureTitle>
+      <DisclosurePanel>Content one</DisclosurePanel>
+    </Disclosure>
+  </Accordion>
+  \`\`\`
+- **ActionBar** — remove \`ActionBarContainer\` and move \`ActionBar\` to the \`renderActionBar\` prop of \`TableView\` or \`CardView\`. Convert \`Item\` children to \`ActionButton\`, and move \`onAction\` to individual \`onPress\` handlers.
+- **Card / CardView** — no automated transform yet; migrate manually.
+- **Well** — replace with a \`<div>\` and apply styles using the style macro:
+  \`\`\`jsx
+  // Before (v3)
+  <Well>Content</Well>
+
+  // After (S2)
+  <div className={style({
+    padding: 16, minWidth: 160, marginTop: 4,
+    borderWidth: 1, borderRadius: 'sm', borderStyle: 'solid',
+    borderColor: 'transparent-black-75', font: 'body-sm'
+  })}>Content</div>
+  \`\`\`
+
+## Resolving TODO(S2-upgrade) comments
+
+After the codemod runs, search for \`TODO(S2-upgrade)\` comments. Each comment pattern has a specific resolution:
+
+### Style prop spreads
+\`TODO(S2-upgrade): check this spread for style props\`
+
+The codemod found a JSX spread attribute (\`{...props}\`) and cannot determine whether it contains v3 style props. Inspect the spread source — if it contains v3 style props (\`margin\`, \`padding\`, \`width\`, etc.), extract them into a \`style()\` macro call and remove them from the spread.
+
+### Dynamic prop values
+\`TODO(S2-upgrade): Prop X could not be automatically updated because Y could not be followed.\`
+
+The prop value is a variable or expression the codemod cannot statically analyze. Trace the variable to its source and apply the same transformation manually. Common examples:
+
+\`\`\`jsx
+// validationState variable → isInvalid
+// Before
+const state = hasError ? 'invalid' : 'valid';
+<TextField validationState={state} />
+// After
+<TextField isInvalid={hasError} />
+
+// Dynamic variant
+// Before
+<Button variant={isPrimary ? 'cta' : 'secondary'} />
+// After
+<Button variant={isPrimary ? 'accent' : 'secondary'} />
+\`\`\`
+
+### Removed prop with dynamic value
+\`TODO(S2-upgrade): X could not be automatically removed because Y could not be followed.\`
+
+A deprecated prop (like \`isQuiet\`) has a dynamic value the codemod cannot safely remove. Verify the prop is no longer needed and remove it manually, updating any related logic.
+
+### Icons without S2 equivalent
+\`TODO(S2-upgrade): A Spectrum 2 equivalent to 'IconName' was not found. Please update this icon manually.\`
+
+Check the S2 icons list for a semantic match. Import from \`@react-spectrum/s2/icons/IconName\`. If no suitable icon exists, consider using a custom SVG icon.
+
+### Illustrations without S2 equivalent
+\`TODO(S2-upgrade): A Spectrum 2 equivalent to 'IllustrationName' was not found. Please update this illustration manually.\`
+
+Choose from available S2 illustrations:
+- Linear variant: \`@react-spectrum/s2/illustrations/linear/<Name>\`
+- Gradient variant: \`@react-spectrum/s2/illustrations/gradient/generic1/<Name>\` or \`@react-spectrum/s2/illustrations/gradient/generic2/<Name>\`
+
+### Unconvertible CSS units
+\`TODO(S2-upgrade): Unable to convert CSS unit to a pixel value\`
+
+Units like \`%\`, \`vw\`, \`vh\`, \`rem\`, \`auto\` cannot be auto-converted. Rewrite using the \`style()\` macro with an appropriate S2 token or the escape-hatch syntax \`'[value]'\`:
+
+\`\`\`jsx
+// Before
+<View width="100%" />
+// After — use 'full' for 100%, or escape-hatch for other values
+<div className={style({width: 'full'})} />
+<div className={style({width: '[50vw]'})} />
+\`\`\`
+
+### Style props that could not be converted
+\`TODO(S2-upgrade): update this style prop\`
+
+A v3 dimension value couldn't be mapped. Convert it manually using the dimension table in the [Codemod UPGRADE notes](references/codemod/UPGRADE.md).
+
+### UNSAFE_style / UNSAFE_className
+\`TODO(S2-upgrade): check this UNSAFE_style\` or \`check this UNSAFE_className\`
+
+Review whether the custom styling is still needed in S2. Prefer migrating to the \`style()\` macro. If the styling must remain, keep it as \`UNSAFE_className\` or \`UNSAFE_style\`.
+
+### Collection item type detection
+\`TODO(S2-upgrade): Couldn't automatically detect what type of collection component this is rendered in.\`
+
+The codemod couldn't determine the parent collection for an \`Item\` or \`Section\`. Rename based on context:
+- Inside \`Menu\` or \`ActionMenu\` → \`MenuItem\`
+- Inside \`Picker\` → \`PickerItem\`
+- Inside \`ComboBox\` → \`ComboBoxItem\`
+- Inside \`TagGroup\` → \`Tag\`
+- Inside \`Breadcrumbs\` → \`Breadcrumb\`
+- Inside \`ListView\` → \`ListViewItem\`
+- Inside \`TabList\` → \`Tab\`
+
+### Table row header
+\`TODO(S2-upgrade): You'll need to add isRowHeader to one of the columns manually.\`
+
+Add \`isRowHeader\` to the \`<Column>\` that contains the primary identifying content (usually the first text column like "Name").
+
+### Table row IDs
+\`TODO(S2-upgrade): If the items do not have id properties, you'll need to add an id prop to the Row.\`
+
+Add an explicit \`id\` prop to \`<Row>\` using a unique identifier from your data.
+
+### Dialog render props
+\`TODO(S2-upgrade): Could not automatically move the render props.\` or \`update this dialog to move the close function inside\`
+
+Move the \`close\` function from \`DialogTrigger\`'s render prop to \`Dialog\`'s render prop:
+
+\`\`\`jsx
+// Before (v3)
+<DialogTrigger>
+  <Button>Open</Button>
+  {(close) => (
+    <Dialog>
+      <Content>...</Content>
+      <ButtonGroup>
+        <Button onPress={close}>Done</Button>
+      </ButtonGroup>
+    </Dialog>
+  )}
+</DialogTrigger>
+
+// After (S2)
+<DialogTrigger>
+  <Button>Open</Button>
+  <Dialog>
+    {({close}) => (
+      <>
+        <Content>...</Content>
+        <ButtonGroup>
+          <Button onPress={close}>Done</Button>
+        </ButtonGroup>
+      </>
+    )}
+  </Dialog>
+</DialogTrigger>
+\`\`\`
+
+### Dynamic imports
+\`TODO(S2-upgrade): check this dynamic import\`
+
+Dynamic \`import()\` statements from v3 packages cannot be automatically rewritten. Update the import path manually to \`@react-spectrum/s2\`.
+
+### Link with custom element
+\`TODO(S2-upgrade): You may have been using a custom link component here.\`
+
+If you had a custom element (not \`<a>\`) inside \`Link\`, remove it and apply props directly to \`Link\`. S2 \`Link\` renders its own anchor element.
+
+### Breadcrumbs nav element
+\`TODO(S2-upgrade): S2 Breadcrumbs no longer includes a nav element.\`
+
+S2 \`Breadcrumbs\` no longer wraps in \`<nav>\`. If you need the navigation landmark, wrap it yourself:
+
+\`\`\`jsx
+<nav aria-label="Breadcrumbs">
+  <Breadcrumbs>...</Breadcrumbs>
+</nav>
+\`\`\`
+
+## Common manual migration patterns
+
+These patterns come up frequently and the codemod cannot handle them because they involve dynamic expressions.
+
+### isLoading to loadingState
+
+\`\`\`jsx
+// Before (v3)
+<Picker isLoading={loading} />
+
+// After (S2)
+<Picker loadingState={loading ? 'loading' : 'idle'} />
+\`\`\`
+
+### Collection render function to array.map
+
+\`\`\`jsx
+// Before (v3)
+<ActionGroup items={actions} onAction={onAction}>
+  {(item) => <Item key={item.id}>{item.label}</Item>}
+</ActionGroup>
+
+// After (S2) — using ActionButtonGroup (no selection)
+<ActionButtonGroup>
+  {actions.map((item) => (
+    <ActionButton key={item.id} onPress={() => onAction(item.id)}>
+      {item.label}
+    </ActionButton>
+  ))}
+</ActionButtonGroup>
+
+// After (S2) — using ToggleButtonGroup (with selection)
+<ToggleButtonGroup selectionMode="single" onSelectionChange={onSelectionChange}>
+  {actions.map((item) => (
+    <ToggleButton key={item.id} id={item.id}>
+      {item.label}
+    </ToggleButton>
+  ))}
+</ToggleButtonGroup>
+\`\`\`
+
+### DialogTrigger type to separate component
+
+\`\`\`jsx
+// Before (v3) — popover dialog
+<DialogTrigger type="popover" placement="bottom">
+  <ActionButton>Info</ActionButton>
+  <Dialog><Content>Details here</Content></Dialog>
+</DialogTrigger>
+
+// After (S2) — use Popover component
+<DialogTrigger>
+  <ActionButton>Info</ActionButton>
+  <Popover placement="bottom">
+    <Dialog><Content>Details here</Content></Dialog>
+  </Popover>
+</DialogTrigger>
+
+// Before (v3) — fullscreen dialog
+<DialogTrigger type="fullscreen">
+  <Button>Open</Button>
+  <Dialog>...</Dialog>
+</DialogTrigger>
+
+// After (S2) — use FullscreenDialog component
+<DialogTrigger>
+  <Button>Open</Button>
+  <FullscreenDialog>...</FullscreenDialog>
+</DialogTrigger>
+\`\`\`
+
+### Flex/Grid/View to div with style macro
+
+\`\`\`jsx
+// Before (v3)
+<Flex direction="column" gap="size-200" marginTop="size-100">
+  <View padding="size-250" backgroundColor="gray-50" borderRadius="medium">
+    Content
+  </View>
+</Flex>
+
+// After (S2)
+<div className={style({display: 'flex', flexDirection: 'column', gap: 16, marginTop: 8})}>
+  <div className={style({padding: 20, backgroundColor: 'layer-1', borderRadius: 'lg'})}>
+    Content
+  </div>
+</div>
+\`\`\`
+
+## Import cleanup
+
+After migration, clean up package imports:
+
+**Remove these packages** from \`package.json\` if they are no longer needed:
+- \`@adobe/react-spectrum\`
+- \`@react-spectrum/provider\`, \`@react-spectrum/button\`, and other individual \`@react-spectrum/*\` component packages
+- \`@spectrum-icons/workflow\` (replaced by \`@react-spectrum/s2/icons/*\`)
+- \`@spectrum-icons/illustrations\` (replaced by \`@react-spectrum/s2/illustrations/*\`)
+- \`@spectrum-icons/ui\` (no direct S2 equivalent — migrate manually)
+
+**Keep these packages** (still compatible with S2):
+- \`@react-aria/*\`
+- \`@react-stately/*\`
+
+**Audit and likely remove**:
+- \`@react-types/*\` — most types are re-exported from \`@react-spectrum/s2\`
+
+## Bundler setup
+
+Configure style macro support for your bundler:
+- **Parcel 2.12+**: macros are built in — no plugin needed. Add \`manualSharedBundles\` config to root \`package.json\` for CSS optimization.
+- **Vite**: install \`unplugin-parcel-macros\` and add \`macros.vite()\` to \`vite.config.ts\`.
+- **Webpack**: install \`unplugin-parcel-macros\`, \`mini-css-extract-plugin\`, and \`css-minimizer-webpack-plugin\`.
+
+Add \`import '@react-spectrum/s2/page.css';\` in your app entry files.
+
+Update Provider setup: S2 does not require a \`Provider\` component. Remove v3 \`Provider\` + \`defaultTheme\` usage, or replace with S2 \`Provider\` if you need to configure settings.
+
+See [Getting Started](references/guides/getting-started.md) for more information.
+
+## Verification
+
+After completing the migration, verify with these steps:
+
+1. **Type check** — run \`npx tsc --noEmit\` to catch type errors from removed or renamed props.
+2. **Search for remaining TODOs** — \`grep -r "TODO(S2-upgrade)" --include="*.tsx" --include="*.ts" --include="*.jsx" --include="*.js"\`
+3. **Search for leftover v3 imports**:
+  - \`grep -r "from '@adobe/react-spectrum'" --include="*.tsx" --include="*.ts"\`
+  - \`grep -r "from '@react-spectrum/" --include="*.tsx" --include="*.ts" | grep -v "@react-spectrum/s2"\`
+4. **Search for leftover icon imports** — \`grep -r "from '@spectrum-icons/" --include="*.tsx" --include="*.ts"\`
+5. **Verify page.css import** — confirm \`import '@react-spectrum/s2/page.css'\` exists in your app entry files.
+6. **Run tests** — run the project's test suite to catch runtime regressions.
+7. **Run linter/formatter** — the codemod may leave formatting inconsistencies; run Prettier or ESLint to clean up.
+
+## References
+
+- [Migrating guide](references/guides/migrating.md): comprehensive per-component migration details
+- [Style macro guide](references/guides/style-macro.md): how to use the \`style()\` macro
+- [Styling guide](references/guides/styling.md): S2 styling concepts and patterns
+- [Getting started](references/guides/getting-started.md): S2 setup and installation
+- [Codemod README](references/codemod/README.md): codemod CLI options and usage
+- [Codemod UPGRADE notes](references/codemod/UPGRADE.md): per-component prop changes and dimension mapping tables
+`;
+
+  return content.trimEnd() + '\n';
+}
+
 /**
  * Copy documentation files to the skill's references directory
  */
@@ -463,6 +872,45 @@ function copyDocumentation(skillConfig, categories, skillDir) {
   }
 }
 
+function copyMigrationReferences(skillDir) {
+  const refsDir = path.join(skillDir, 'references');
+  const guidesSourceDir = path.join(MARKDOWN_DOCS_DIST, 's2');
+  const guidesDir = path.join(refsDir, 'guides');
+  const codemodDir = path.join(refsDir, 'codemod');
+
+  fs.mkdirSync(guidesDir, {recursive: true});
+  fs.mkdirSync(codemodDir, {recursive: true});
+
+  const guideFiles = [
+    'migrating.md',
+    'style-macro.md',
+    'styling.md',
+    'getting-started.md'
+  ];
+
+  for (const file of guideFiles) {
+    const sourcePath = path.join(guidesSourceDir, file);
+    const targetPath = path.join(guidesDir, file);
+    if (!fs.existsSync(sourcePath)) {
+      throw new Error(`Missing migration guide file: ${sourcePath}`);
+    }
+    fs.copyFileSync(sourcePath, targetPath);
+  }
+
+  const codemodFiles = [
+    {source: path.join(CODEMOD_S1_TO_S2_DIR, 'README.md'), target: 'README.md'},
+    {source: path.join(CODEMOD_S1_TO_S2_DIR, 'UPGRADE.md'), target: 'UPGRADE.md'}
+  ];
+
+  for (const file of codemodFiles) {
+    const targetPath = path.join(codemodDir, file.target);
+    if (!fs.existsSync(file.source)) {
+      throw new Error(`Missing codemod reference file: ${file.source}`);
+    }
+    fs.copyFileSync(file.source, targetPath);
+  }
+}
+
 function collectSkillFiles(skillDir) {
   const files = [];
 
@@ -511,6 +959,21 @@ function generateSkill(skillConfig, wellKnownRoot) {
   // Create skill directory
   fs.mkdirSync(skillDir, {recursive: true});
 
+  if (skillConfig.mode === 'migration') {
+    const skillMdContent = generateMigrationSkillMd(skillConfig);
+    fs.writeFileSync(path.join(skillDir, 'SKILL.md'), skillMdContent);
+    console.log(
+      `Generated ${path.relative(REPO_ROOT, path.join(skillDir, 'SKILL.md'))}`
+    );
+
+    copyMigrationReferences(skillDir);
+    console.log(
+      `Copied migration references to ${path.relative(REPO_ROOT, path.join(skillDir, 'references'))}`
+    );
+
+    return skillDir;
+  }
+
   // Parse documentation entries
   const llmsTxtPath = path.join(
     MARKDOWN_DOCS_DIST,
@@ -573,6 +1036,7 @@ async function main() {
       indexEntries.push({
         name: config.name,
         description: config.description,
+        available_files: files,
         files
       });
     }