statamic-addon-v5-to-v6

A Claude Code Skill that drives an end-to-end upgrade of a Statamic addon from v5 to v6.

It handles:

• composer.json + package.json bumps (PHP 8.3, Laravel 12, Statamic ^6, Vite 8, Tailwind v4)
• Mix → Vite + @statamic/cms/vite-plugin + @tailwindcss/vite
• Service provider rename (boot() → bootAddon()) and removed-method sweep
• Replacing edalzell/forma with the native UserConfig.php pattern (no third-party config dependency)
• Vue 2 Options API → Vue 3 Composition API (<script setup>)
• Custom fieldtype migration to the new Fieldtype.use(emit, props) composable
• CP Blade pages → Inertia.js pages using @statamic/cms/ui components
• API renames (events, status queries, link fieldtype shape, Carbon 3, etc.)
• Test base class switch to Statamic\Testing\AddonTestCase

CP-scope only. Frontend Livewire components are intentionally out of scope (v6's breaking changes don't materially affect them).

Install

Personal install (immediate)

cp -R /Volumes/1TB/Sites/statamic-upgrade-skill ~/.claude/skills/statamic-addon-v5-to-v6

Restart Claude Code if it's open. The skill should appear in /help skill listings.

Project install (one repo)

mkdir -p .claude/skills
cp -R /Volumes/1TB/Sites/statamic-upgrade-skill .claude/skills/statamic-addon-v5-to-v6

Commit if appropriate — anyone with Claude Code on the repo will get it.

Trigger

In Claude Code, inside a Statamic addon repo:

Upgrade this addon to Statamic v6.

Or any of: "port to Statamic 6", "migrate from Vue 2 to Vue 3 in Statamic", "replace Forma with native config", "AddonServiceProvider migration".

What's in here

.
├── SKILL.md                       # Frontmatter + orchestrator (8-phase plan)
├── README.md                      # This file
├── references/
│   ├── 00-workflow.md             # Phase order + decision tree
│   ├── 01-audit-checklist.md      # Grep recipes to inventory the v5 surface
│   ├── 02-composer-and-deps.md    # composer + package.json diffs
│   ├── 03-service-provider.md     # AddonServiceProvider, nav, permissions
│   ├── 04-vite-and-tailwind.md    # Vite 8 + Tailwind v4 setup
│   ├── 05-vue3-migration.md       # Options API → <script setup>
│   ├── 06-fieldtype-migration.md  # Fieldtype.use(emit, props) composable
│   ├── 07-cp-pages-inertia.md     # Blade → Inertia + @statamic/cms/ui
│   ├── 08-userconfig-pattern.md   # Forma → UserConfig.php replacement
│   ├── 09-api-breaking-changes.md # Event/method/tag renames
│   ├── 10-testing.md              # AddonTestCase + PHPUnit 11/Pest 4
│   └── resrv-playbook.md          # Resrv-specific file map
└── templates/
    ├── ServiceProvider.php.tpl
    ├── UserConfig.php.tpl
    ├── SettingsController.php.tpl
    ├── config-blueprint.yaml.tpl
    ├── vite.config.js.tpl
    ├── package.json-snippet.tpl
    ├── cp.js.tpl
    ├── Fieldtype-vue3.vue.tpl
    └── InertiaPage.vue.tpl

Templates use {{Namespace}}, {{addon-slug}}, {{Addon Display Name}} tokens — Claude rewrites them when applying. Lift-and-edit, don't reference verbatim.

How the workflow runs

1. Phase 1 — Audit & branch. Greps the repo for every v5 surface area and prints a report. Creates a v6-upgrade branch. Captures the test baseline.
2. Phase 2 — Dependencies. Bumps composer + npm. Verifies both resolve.
3. Phase 3 — Build tooling. Replaces Vite config, renames JS entry to cp.js, switches Tailwind to v4 + Vite plugin.
4. Phase 4 — Service provider. Renames boot() to bootAddon(), removes deprecated facade calls, migrates nav/permissions to builder syntax.
5. Phase 5 — Config. Drops Forma. Adds UserConfig.php, SettingsController, blueprint, route, settings nav item.
6. Phase 6 — Vue 3. Converts mixins → composables, then fieldtypes, then components.
7. Phase 7 — Inertia pages. Replaces each Blade CP page with a Vue page + Inertia::render controller.
8. Phase 8 — API sweep + tests. Renames events / status queries / link fieldtype usage / Carbon arithmetic; bumps test base class.

Each phase ends with a verification step (composer install succeeds, build is green, settings persist, fieldtype mounts, tests pass). The skill won't move forward until the gate passes.

Designed for, but not limited to, Resrv

The skill is generic. references/resrv-playbook.md maps Resrv's specific surface (35 Vue 2 files, 5 fieldtypes, 8 nav items, Forma config, etc.) to the generic phases so the first run on Resrv has a concrete worklist. Strip or ignore that file for other addons.

What's intentionally out of scope

• Frontend Livewire components. The skill flags global-set event renames if listeners cross paths; otherwise leaves Livewire alone.
• Payment SDK upgrades, DB migrations, third-party model changes — orthogonal to v6.
• Whether edalzell/forma or marcorieser/statamic-livewire have v6 releases. The skill removes Forma; Livewire bridge compatibility is the user's call.

Sources

The skill is built on patterns from three v6-native addons studied during research:

• statamic/seo-pro — first-party reference for service-provider chaining, nav builder, permission groups.
• duncanmcclean/statamic-cargo — third-party reference for complex addons (Stache stores, Inertia pages, prebuilt-dist distribution).
• reachweb/statamic-ai-agent — source of the UserConfig.php pattern.

Plus the official upgrade guide: https://statamic.dev/getting-started/upgrade-guide/5-to-6 and the UI components docs: https://ui.statamic.dev.

License

MIT — use, fork, contribute back.