skills.rest
timcsy
timcsyCOMMUNITY
Explore all skills by this author →
GitHub

migrate-storage

Migrate persisted storage schemas across versions without losing user data.

9|Updated Mar 4, 2026
Search Tags:#typescript#localstorage#data persistence#backward compatibility#schema versioning#storage migration#idempotent upgrade
One-click install
npx skills add https://github.com/timcsy/semorphe --skill migrate-storage-timcsy
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: migrate-storage
Source: https://github.com/timcsy/semorphe/tree/main/knowledge/skills/migrate-storage
Command: npx skills add https://github.com/timcsy/semorphe --skill migrate-storage-timcsy

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Changing a saved-state format risks silently destroying user data: fields get dropped, renames hit unrelated structures, and upgrade steps run twice on already-migrated files. This Skill turns a schema change into a safe, idempotent upgrade procedure grounded in nine real migrations recorded in the repository. ## Core Features & Use Cases - Field ownership classification: Separates saved fields into file-owned, appearance-owned, and user-owned categories before touching anything, with an explicit "undecided" bucket instead of guessing. - Idempotent migration rules: Enforces rename tables that skip already-migrated names, restricts recursion to known structures (blocks, inputs, next chains), and forbids blanket field renames. - Consistency and guardrails: Requires both load paths (auto-load and file import) to share one version judgment, keeps SAVED_STATE_FIELDS authoritative via TypeScript satisfies, and mandates running the audit-storage-integrity injection tests plus a real old-save browser test. - Use Case: When bumping CURRENT_VERSION from 9 to 10 because a block field was renamed, follow the checklist to write an idempotent upgrade step, verify the guardrail metrics, and confirm a v9 save still loads intact. ## Quick Start Ask the AI to apply the migrate-storage skill to plan a safe storage schema upgrade for the field change you are making, listing every affected field and its fate.

Frequently Asked Questions about migrate-storage

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I migrate a saved data schema without losing user data?▼

List every field the change touches and decide where each one goes before writing the upgrade step. Classify fields by ownership (file, appearance, or user), write an idempotent rename that skips already-migrated names, and test with a real previous-version save.

How do I make a storage migration step idempotent?▼

Make the rename table check whether a field already has its new name and skip it instead of treating it as unknown. Export bugs can re-feed already-migrated content into the upgrade step, so any conversion that only works once will eventually run twice.

Why did my field rename corrupt unrelated saved data?▼

Identically named fields can exist on unrelated types where TypeScript cannot distinguish them. Only recurse into known structures like blocks, inputs, and next chains, and never apply a global rename to every field sharing a name.

Should old save formats be allowed to break before release?▼

No. A no-backward-compatibility policy may cover projections and generated code, but saved user data is excluded. Old saves must keep loading through a complete, unbroken chain of version upgrade steps.

When is removing a saved field an architecture decision instead of a format change?▼

When the field is the primary restoration source at load time, it is behaviorally real, so removing it changes where truth lives. That requires a roadmap decision first, not just a version bump.

Related Skills

Explore More Software Engineering Skills→
samcdavidsamcdavid
4

context-audit

Audit session context and report largest contributors to usage.

Community
Advanced
chanhee-kangchanhee-kang
2

auto-deploy

Automate oh-my-gemini deployment to npm and GitHub releases.

Community
Advanced
zinohomezinohome
1

data-integrity-auditor

Audit and rectify database integrity issues using SQL and Prisma ORM.

Community
Advanced
kirvinkirvin

migrating-code

Plan code migrations with backward compatibility and reversibility patterns.

Community
Advanced