kirby-content-migration

bnomei's avatarfrom bnomei

Plans and applies safe Kirby content migrations using runtime content tools, update schemas, and explicit confirmation. Use when users need to rename/move/transform fields, clean up content, or bulk-update pages/files across languages.

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

When & Why to Use This Skill

This Claude skill automates safe Kirby CMS content migrations, enabling developers and content managers to rename fields, transform data structures, and perform bulk updates across multi-language sites using a secure, validation-first workflow.

Use Cases

  • Bulk-renaming or moving content fields across hundreds of pages to match updated blueprint schemas without manual editing.
  • Automating the cleanup of legacy content and transforming data formats during Kirby website migrations or structural redesigns.
  • Performing batch updates on file metadata and page content across multiple languages while ensuring data integrity through explicit safety confirmations.
  • Programmatically updating Kirby blocks and fields by validating changes against runtime schemas to prevent data loss or formatting errors.
namekirby-content-migration
descriptionPlans and applies safe Kirby content migrations using runtime content tools, update schemas, and explicit confirmation. Use when users need to rename/move/transform fields, clean up content, or bulk-update pages/files across languages.

Kirby Content Migration

Quick start

  • Follow the workflow below for safe, confirm-first migrations.

KB entry points

  • kirby://kb/scenarios/16-batch-update-content
  • kirby://kb/scenarios/74-update-blocks-programmatically
  • kirby://kb/scenarios/34-content-file-cleanup-script
  • kirby://kb/scenarios/75-update-file-metadata

Required inputs

  • Source and target fields plus transform rules.
  • Scope (templates/ids/sections) and batch size.
  • Language and draft handling rules.
  • Exclusions or derived fields that must not change.

Plan template

  • List source field, target field, transform rule, and a before/after example.
  • Specify scope (templates/ids), languages, and draft handling.
  • Note exclusions (derived fields, computed values, or generated files).

Plan-validate-execute

  • Write a changes.json plan with explicit page ids/uuids and new values.
  • Validate the plan against blueprint and field schemas, plus a sample diff.
  • Apply in batches (confirm=false preview, then confirm=true).

Verification checklist

  • Preview diffs for each field type before writing.
  • Confirm language scope and batch boundaries.
  • Re-render representative pages after apply.

Common pitfalls

  • Writing updates before reading field update schemas.
  • Migrating large batches without confirm previews.

Workflow

  1. Ask for exact transformations, scope (pages/templates/sections), languages, draft handling, and any derived fields that must not be written.
  2. Call kirby:kirby_init, then ensure runtime availability with kirby:kirby_runtime_status and kirby:kirby_runtime_install if needed.
  3. Identify target pages:
    • Prefer explicit page ids/uuids from the user.
    • Otherwise derive a list using kirby://roots and the content directory structure.
  4. Search the KB with kirby:kirby_search for related playbooks (examples: "batch update content", "update blocks programmatically", "content file cleanup script", "update file metadata").
  5. Read field storage rules before writing:
    • kirby://fields/update-schema
    • kirby://field/{type}/update-schema for each involved field type.
  6. Read a small sample with kirby:kirby_read_page_content (or kirby://page/content/{encodedIdOrUuid}) and produce a diff-style preview.
  7. Use kirby://tool-examples for safe, copy-ready kirby:kirby_update_page_content payloads.

Apply

  1. Call kirby:kirby_update_page_content with confirm=false to preview changes (set payloadValidatedWithFieldSchemas=true).
  2. Ask for explicit confirmation, then re-run with confirm=true in small batches.
  3. Stop on first error; summarize what applied vs skipped.

Verify

  1. Render representative pages with kirby:kirby_render_page(noCache=true) or re-read content to confirm the final state.
  2. Report changes, remaining risks, and any follow-up manual checks.