kirby-upgrade-and-maintenance
Upgrades Kirby and maintains dependencies safely using composer audit, plugin compatibility checks, and official docs. Use when updating Kirby versions or making maintenance changes that affect runtime.
When & Why to Use This Skill
This Claude skill automates the complex process of upgrading Kirby CMS and maintaining its dependencies. It ensures system stability by integrating composer audit, plugin compatibility checks, and official documentation into a safe, staged workflow. Designed for developers and system administrators, it minimizes the risk of breaking changes during runtime updates through structured rollback procedures and comprehensive environment validation.
Use Cases
- Case 1: Safely upgrading a Kirby CMS installation from one major version to another (e.g., K5 to K6) while verifying plugin compatibility and breaking changes.
- Case 2: Performing routine security maintenance by auditing Composer dependencies and applying updates without disrupting the production environment.
- Case 3: Executing a staged rollout of CMS updates across multiple environments, ensuring each stage is validated before proceeding to the next.
- Case 4: Troubleshooting and recovering from failed updates using the automated rollback checklist to restore the previous stable state of the vendor directory and lockfile.
| name | kirby-upgrade-and-maintenance |
|---|---|
| description | Upgrades Kirby and maintains dependencies safely using composer audit, plugin compatibility checks, and official docs. Use when updating Kirby versions or making maintenance changes that affect runtime. |
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:kirby_initor gather baseline data withkirby:kirby_infoandkirby:kirby_composer_audit. - Inventory plugins for compatibility risks:
kirby:kirby_plugins_index. - Use
kirby:kirby_onlineto find official upgrade guides and breaking changes for the target version (preferkirby:kirby_searchfirst). - 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:kirby_cli_versionto confirm the installed version - ensure runtime commands are in sync:
kirby:kirby_runtime_statusandkirby:kirby_runtime_installif needed - render representative pages with
kirby:kirby_render_page(noCache=true)
- Summarize changes, remaining risks, and a short manual QA checklist.