SKILL.md
Kirby Upgrade and Maintenance
Quick start
- Follow the workflow below for safe, incremental upgrades.
KB entry points
kirby://kb/panel/compat-k5-k6-migrationkirby://kb/panel/tooling-kirbyupkirby://kb/glossary/kirbyupkirby://kb/glossary/plugin
Required inputs
- Current and target Kirby versions.
- Environment constraints and downtime tolerance.
- Plugin compatibility risks and rollback expectations.
Default upgrade checklist
- Read the target version guide and note breaking changes.
- Update
composer.jsonconstraints, then review the lockfile diff. - Run project scripts and render representative pages.
- Verify runtime commands and CLI version match.
Rollback note
- Keep a copy of the previous
composer.lockandvendor/state.
Rollback checklist
- Restore the previous
composer.lock. - Reinstall dependencies and re-run smoke tests.
- Re-render representative pages to confirm behavior.
Staged upgrade pattern
- Upgrade a single environment/site first, then roll out to others.
- Validate plugins and custom code before multi-site rollout.
Common pitfalls
- Skipping plugin compatibility checks.
- Upgrading multiple major versions in one jump.
Workflow
- Call
kirby:kirbyinitor gather baseline data withkirby:kirbyinfoandkirby:kirbycomposeraudit. - Inventory plugins for compatibility risks:
kirby:kirbypluginsindex. - Use
kirby:kirbyonlineto find official upgrade guides and breaking changes for the target version (preferkirby:kirbysearchfirst). - Build a project-specific checklist of required code/config changes.
- Ask for confirmation before dependency updates that change the lockfile.
- Verify:
- run project scripts discovered in the composer audit - call kirby:kirbycliversion to confirm the installed version - ensure runtime commands are in sync: kirby:kirbyruntimestatus and kirby:kirbyruntimeinstall if needed - render representative pages with kirby:kirbyrenderpage(noCache=true)
- Summarize changes, remaining risks, and a short manual QA checklist.