kirby-upgrade-and-maintenance

bnomei's avatarfrom bnomei

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.

⭐17stars🔀0forks📁View on GitHub🕐Updated Jan 10, 2026⬇️4downloads

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.
namekirby-upgrade-and-maintenance
descriptionUpgrades 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-migration
  • kirby://kb/panel/tooling-kirbyup
  • kirby://kb/glossary/kirbyup
  • kirby://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.json constraints, 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.lock and vendor/ 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

  1. Call kirby:kirby_init or gather baseline data with kirby:kirby_info and kirby:kirby_composer_audit.
  2. Inventory plugins for compatibility risks: kirby:kirby_plugins_index.
  3. Use kirby:kirby_online to find official upgrade guides and breaking changes for the target version (prefer kirby:kirby_search first).
  4. Build a project-specific checklist of required code/config changes.
  5. Ask for confirmation before dependency updates that change the lockfile.
  6. Verify:
    • run project scripts discovered in the composer audit
    • call kirby:kirby_cli_version to confirm the installed version
    • ensure runtime commands are in sync: kirby:kirby_runtime_status and kirby:kirby_runtime_install if needed
    • render representative pages with kirby:kirby_render_page(noCache=true)
  7. Summarize changes, remaining risks, and a short manual QA checklist.