// HeroUI v2 to v3 migration guide for agents. Use when migrating HeroUI v2 apps to v3, upgrading components, or accessing migration documentation. Keywords: HeroUI migration, v2 to v3, migration guide, upgrade HeroUI.
| name | heroui-migration |
| description | HeroUI v2 to v3 migration guide for agents. Use when migrating HeroUI v2 apps to v3, upgrading components, or accessing migration documentation. Keywords: HeroUI migration, v2 to v3, migration guide, upgrade HeroUI. |
| metadata | {"author":"heroui","version":"2.0.0","status":"preview"} |
This skill helps agents migrate HeroUI v2 applications to v3. HeroUI v3 introduces breaking changes: compound components, no Provider, Tailwind v4, and removed hooks.
curl -fsSL https://heroui.com/install | bash -s heroui-migration
Do NOT assume v2 patterns work in v3. Always fetch migration guides before implementing changes.
| Feature | v2 (Migrate From) | v3 (Migrate To) |
|---|---|---|
| Provider | <HeroUIProvider> required | No Provider needed |
| Component API | Flat props: <Card title="x"> | Compound: <Card><Card.Header> |
| Event handlers | onClick | onPress |
| Styling | classNames prop | className prop |
| Hooks | useSwitch, useDisclosure, etc. | Compound components, useOverlayState |
| Packages | @heroui/system, @heroui/theme | @heroui/react, @heroui/styles |
For migration details, examples, and step-by-step guides, always fetch documentation:
# List all available component migration guides
node scripts/list_migration_guides.mjs
# Get main migration workflow (full or incremental)
node scripts/get_migration_guide.mjs full
node scripts/get_migration_guide.mjs incremental
# Get component-specific migration guides
node scripts/get_component_migration_guides.mjs button
node scripts/get_component_migration_guides.mjs button card modal
# Get styling migration guide
node scripts/get_styling_migration_guide.mjs
# Get hooks migration guide
node scripts/get_hooks_migration_guide.mjs
Migration docs (preview): https://heroui-git-docs-migration-heroui.vercel.app/docs/react/migration/{filename}
Examples:
.../agent-guide-full.mdx.../agent-guide-incremental.mdx.../button.mdx.../styling.mdx.../hooks.mdxOverride base URL with HEROUI_MIGRATION_DOCS_BASE when docs are merged to production.
When using Cursor or other MCP clients, configure the Migration MCP server for tool-based access:
{
"mcpServers": {
"heroui-migration": {
"url": "https://migration-mcp.heroui.com"
}
}
}
Always fetch the agent guide before starting: node scripts/get_migration_guide.mjs full or incremental
Card.Header, Card.Title, Button with children—not flat propsHeroUIProvider when migratingonPressnode scripts/get_migration_guide.mjs fullnode scripts/get_styling_migration_guide.mjsThis skill targets the staging deployment of the docs/migration branch. Once docs are merged to main and live on heroui.com, set HEROUI_MIGRATION_DOCS_BASE=https://heroui.com/docs/react/migration or update the default in scripts.
Compress natural language memory files (CLAUDE.md, todos, preferences) into caveman format to save input tokens. Preserves all technical substance, code, URLs, and structure. Compressed version overwrites the original file. Human-readable backup saved as FILE.original.md. Trigger: /caveman-compress FILEPATH or "compress memory file"
Specialized Preact development skill for standards-based web applications with native-first architecture and minimal dependency footprint. Use when building Preact projects, particularly those involving data visualization, interactive applications, single-page apps with HTM syntax, Web Components integration, CSV/JSON data parsing, WebGL shader visualizations, or zero-build solutions with vendored ESM imports.
HeroUI v3 React component library (Tailwind CSS v4 + React Aria). Use when building UIs with HeroUI — creating Buttons, Modals, Forms, Cards; installing @heroui/react; configuring dark/light themes with oklch variables; or fetching component docs. Keywords: HeroUI, Hero UI, heroui, @heroui/react, @heroui/styles.
Implements Manus-style file-based planning to organize and track progress on complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Supports automatic session recovery after /clear.
Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
Use when creating new skills, editing existing skills, or verifying skills work before deployment