kirby-content-migration
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.
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.
| name | kirby-content-migration |
|---|---|
| description | 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. |
Kirby Content Migration
Quick start
- Follow the workflow below for safe, confirm-first migrations.
KB entry points
kirby://kb/scenarios/16-batch-update-contentkirby://kb/scenarios/74-update-blocks-programmaticallykirby://kb/scenarios/34-content-file-cleanup-scriptkirby://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.jsonplan with explicit page ids/uuids and new values. - Validate the plan against blueprint and field schemas, plus a sample diff.
- Apply in batches (
confirm=falsepreview, thenconfirm=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
- Ask for exact transformations, scope (pages/templates/sections), languages, draft handling, and any derived fields that must not be written.
- Call
kirby:kirby_init, then ensure runtime availability withkirby:kirby_runtime_statusandkirby:kirby_runtime_installif needed. - Identify target pages:
- Prefer explicit page ids/uuids from the user.
- Otherwise derive a list using
kirby://rootsand the content directory structure.
- Search the KB with
kirby:kirby_searchfor related playbooks (examples: "batch update content", "update blocks programmatically", "content file cleanup script", "update file metadata"). - Read field storage rules before writing:
kirby://fields/update-schemakirby://field/{type}/update-schemafor each involved field type.
- Read a small sample with
kirby:kirby_read_page_content(orkirby://page/content/{encodedIdOrUuid}) and produce a diff-style preview. - Use
kirby://tool-examplesfor safe, copy-readykirby:kirby_update_page_contentpayloads.
Apply
- Call
kirby:kirby_update_page_contentwithconfirm=falseto preview changes (setpayloadValidatedWithFieldSchemas=true). - Ask for explicit confirmation, then re-run with
confirm=truein small batches. - Stop on first error; summarize what applied vs skipped.
Verify
- Render representative pages with
kirby:kirby_render_page(noCache=true)or re-read content to confirm the final state. - Report changes, remaining risks, and any follow-up manual checks.