feat: add Agent Skill for S1 to S2 migration

packages/dev/codemods/src/s1-to-s2/README.md

@@ -9,6 +9,9 @@ Run `npx @react-spectrum/codemods s1-to-s2` from the directory you want to upgra
 ### Options
 
 - `-c, --components <components>`: Comma separated list of components to upgrade (ex: `Button,TableView`). If not specified, all available components will be upgraded.
+- `--path <path>`: The path to the directory to run the codemod in. Defaults to the current directory (`.`).
+- `-d, --dry`: Run the codemod without writing any changes to disk. Use this to preview migrations before applying.
+- `--agent`: Run in non-interactive mode. Skips interactive prompts, package installation, and macro setup. Required when running in CI or from an agent tool. Note: `@react-spectrum/s2` must still be installed and resolvable.
 
 ## How it works
 

packages/dev/codemods/src/s1-to-s2/UPGRADE.md

@@ -265,7 +265,7 @@ Example:
 
 ### Border width
 
-Affected style props: `borderWidth`, `borderStartWidth`, `borderEndWidth`, `borderTopWidth`, `orderBottomWidth`, `borderXWidth`, `borderYWidth`.
+Affected style props: `borderWidth`, `borderStartWidth`, `borderEndWidth`, `borderTopWidth`, `borderBottomWidth`, `borderXWidth`, `borderYWidth`.
 
 Example:
 

packages/dev/s2-docs/migration-references/focused-manual-fixes.md

@@ -0,0 +1,143 @@
+# Manual fixes after the codemod
+
+## Icons and illustrations
+
+- If the codemod leaves `TODO(S2-upgrade)` next to an icon or illustration import, pick the nearest S2 replacement manually.
+
+## Layout components
+
+`Flex`, `Grid`, `View`, and `Well` are not part of S2. These should be updated to `div` elements styled with the macro.
+
+### Flex example
+
+Before:
+
+```jsx
+<Flex direction="column">
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</Flex>
+```
+
+After:
+
+```jsx
+import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
+
+<div className={style({display: 'flex', flexDirection: 'column'})}>
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</div>
+```
+
+### Grid example
+
+Before:
+
+```jsx
+<Grid justifyContent="center">
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</Grid>
+```
+
+After:
+
+```jsx
+import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
+
+<div className={style({display: 'grid', justifyContent: 'center'})}>
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</div>
+```
+
+### View example
+
+Before:
+
+```jsx
+<View>
+  Content
+</View>
+```
+
+After:
+
+```jsx
+<div>
+  Content
+</div>
+```
+
+### Well example
+
+Before:
+
+```jsx
+<Well>
+  Content
+</Well>
+```
+
+After:
+
+```jsx
+import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
+
+<div className={style({
+  display: 'block',
+  textAlign: 'start',
+  padding: 16,
+  minWidth: 160,
+  marginTop: 4,
+  borderWidth: 1,
+  borderRadius: 'sm',
+  borderStyle: 'solid',
+  borderColor: 'transparent-black-75',
+  font: 'body-sm'
+})}>
+  Content
+</div>
+```
+
+## UNSAFE_style and UNSAFE_className
+
+Move `UNSAFE_style` usage to the S2 style macro when possible.
+
+Move `UNSAFE_className` usage to the S2 style macro when possible.
+
+Reference the S2 styling docs to see the supported CSS properties.
+
+## Dialogs
+
+- `DialogContainer` and `useDialogContainer` still exist in S2, but the dismiss logic may need to move between `Dialog`, `DialogTrigger`, and `DialogContainer`. See the S2 Dialog documentation for more details.
+
+## Collections
+
+- When `Item` survives the codemod, rename it based on its parent component:
+
+  | Parent component | v3 child | S2 child |
+  |---|---|---|
+  | Menu / ActionMenu | Item | MenuItem |
+  | Picker | Item | PickerItem |
+  | ComboBox | Item | ComboBoxItem |
+  | Tabs | Item | Tab / TabPanel |
+  | TagGroup | Item | Tag |
+  | Breadcrumbs | Item | Breadcrumb |
+
+- Preserve React `key` when mapping arrays, but ensure collection data items expose `id` when S2 expects it. See the S2 Collections documentation for more details.
+- Table and ListView migrations often need manual review for row headers, nested columns, and explicit item ids.
+
+## Toast migration
+
+- Move `ToastContainer` and `ToastQueue` imports from `@react-spectrum/toast` to `@react-spectrum/s2`.
+- Keep a shared `ToastContainer` mounted near the app root or test harness, then update all queue calls to use the S2 import path.
+- S2 supports `ToastQueue.neutral`, `positive`, `negative`, and `info`.
+- Re-check options such as `timeout`, `actionLabel`, `onAction`, `shouldCloseOnAction`, and `onClose` after the import move.
+- The queue methods still return a close function. Keep programmatic dismissal logic when the existing UX depends on it.
+- Search for every `ToastContainer` mount and every `ToastQueue` usage after moving imports. Shared app roots, secondary entrypoints, and test harnesses are easy to miss.

packages/dev/s2-docs/migration-references/focused-prerequisites.md

@@ -0,0 +1,23 @@
+# Inspection checklist
+
+## Minimum tool versions
+
+These tools are not all strictly required, but if the project uses them they must be at these minimum versions to avoid issues with the `with {type: 'macro'}` import syntax:
+
+- **TypeScript 5.3+** — required for the import attributes syntax (`with {type: 'macro'}`).
+- **Babel 7.27.0+** or the `@babel/plugin-syntax-import-attributes` plugin — enables Babel to parse import attributes. Alternatively, `@babel/preset-env` with `shippedProposals: true` also enables import attribute parsing.
+- **ESLint 9.14.0+** with `@typescript-eslint/parser`.
+- **Prettier 3.1.1+** — needed to format `with {type: 'macro'}` import syntax correctly.
+
+## What to look for
+
+- Search package manifests and source for `@adobe/react-spectrum`, `@react-spectrum/*`, and `@spectrum-icons/*`.
+- In monorepos or mixed-tooling repos, inspect the target package or app first instead of assuming the root manifest represents the runtime target being migrated.
+- Determine the package manager from the relevant lockfile or workspace setup.
+- Detect the bundler at the migration target level. The workspace root may include Storybook, Vite, or other tooling that does not represent the runtime bundler for the package being migrated.
+  - **Parcel v2.12.0+** already supports S2 style macros natively.
+  - **Vite, webpack, Next.js, Rollup, ESBuild** and similar toolchains need `unplugin-parcel-macros`. Keep plugin ordering correct so macros run before the rest of the toolchain.
+  - If the repo already has a framework-specific S2 or macro setup, preserve it instead of layering a second macro configuration on top.
+- Find **all** app entrypoints, including standalone pages, alternate render roots, embedded sub-apps, utility apps, and test-only render targets. Do not assume there is only one entry.
+- Locate root providers, shared test wrappers, toast setup, and any direct `defaultTheme` usage.
+- Search for `ToastContainer`, `ToastQueue`, `DialogContainer`, `useDialogContainer`, `ClearSlots`, style props, and `UNSAFE_style`. These are common follow-up areas after the codemod.

packages/dev/s2-docs/package.json

@@ -49,6 +49,8 @@
     "json5": "^2.2.3",
     "lz-string": "^1.5.0",
     "markdown-to-jsx": "^6.11.0",
+    "mdast-util-mdx": "^1.0.0",
+    "mdast-util-to-markdown": "^1.0.0",
     "react": "^19.2.0",
     "react-aria": "^3.40.0",
     "react-aria-components": "^1.7.1",

packages/dev/s2-docs/pages/s2/migrating.mdx

@@ -2,6 +2,7 @@ import {Layout} from '../../src/Layout';
 import {PendingBadge} from '../../src/PendingBadge';
 import {InstallCommand} from '../../src/InstallCommand';
 import {StaticTable} from '../../src/StaticTable';
+import {Command} from '../../src/Command';
 export default Layout;
 
 export const section = 'Guides';
@@ -12,6 +13,18 @@ export const description = 'How to migrate from React Spectrum v3 to Spectrum 2.
 
 <PageDescription>Learn how to migrate from React Spectrum v3 to Spectrum 2.</PageDescription>
 
+## AI-assisted migration (recommended)
+
+If you're using an AI coding tool that supports [Agent Skills](https://agentskills.io/home), React Spectrum now includes a dedicated skill for guiding v3 to S2 upgrades.
+
+To install the migration skill and the general S2 skill, run:
+
+<Command command="npx skills add https://react-spectrum.adobe.com --skill migrate-react-spectrum-v3-to-s2 --skill react-spectrum-s2" />
+
+Then ask your agent to use the `migrate-react-spectrum-v3-to-s2` skill to migrate your project.
+
+## Command-line tool
+
 An automated upgrade assistant is available by running the following command in the project you want to upgrade:
 
 <InstallCommand isCommand pkg="@react-spectrum/codemods" flags="s1-to-s2" />
@@ -25,6 +38,7 @@ The following arguments are also available:
 - `--path` - Path to apply the upgrade changes to. Defaults to the current directory (`.`)
 - `--dry` - Runs the upgrade assistant without making changes to components
 - `--ignore-pattern` - Ignore files that match the provided glob expression. Defaults to `'**/node_modules/**'`
+- `--agent` - Runs the upgrade assistant non-interactively for AI tools. This skips prompts, package installation, and macro setup, so `@react-spectrum/s2` must already be installed and resolvable
 
 For cases that the upgrade assistant doesn't handle automatically or where you'd rather upgrade some components manually, use the guide below.