Agent Skills › kaininx/PlainTab › storage-migration

storage-migration

GitHub

用于管理 PlainTab 应用存储迁移的规范，涵盖 localStorage 和 IndexedDB 的版本控制、数据迁移逻辑及清理规则，确保用户数据在跨版本升级时的安全与一致性。

.agents/skills/storage-migration/SKILL.md kaininx/PlainTab

Trigger Scenarios

修改 localStorage 或 IndexedDB 结构调整数据存储格式或版本号执行旧数据迁移或清理任务

Install

npx skills add kaininx/PlainTab --skill storage-migration -g -y

More Options

Non-standard path

npx skills add https://github.com/kaininx/PlainTab/tree/main/.agents/skills/storage-migration -g -y

Use without installing

npx skills use kaininx/PlainTab@storage-migration

指定 Agent (Claude Code)

npx skills add kaininx/PlainTab --skill storage-migration -a claude-code -g -y

安装 repo 全部 skill

npx skills add kaininx/PlainTab --all -g -y

预览 repo 内 skill

npx skills add kaininx/PlainTab --list

SKILL.md

Frontmatter

{
    "name": "storage-migration",
    "description": "Use before changing PlainTab persistent storage, including localStorage keys, IndexedDB keys or record formats, `LS_VERSION`, `DB_VERSION`, `ptab_schema_version`, migration code, backup\/import\/export storage shape, wallpaper cache cleanup, or any task that may affect old users upgrading across versions."
}

PlainTab Storage Migration

Use this skill as a red-line checklist for storage changes. User data safety and jump-upgrade behavior matter more than implementation neatness.

First Reads

Read .claude/rules/00-core.md.
Read .claude/rules/10-storage.md.
If wallpaper rendering, first paint, settings UI, language, search, or command palette storage is touched, read the matching rule file from .claude/rules/README.md.

Version Rules

DB_VERSION is only for IndexedDB structure: object stores, indexes, keyPath, or autoIncrement.
LS_VERSION / ptab_schema_version is for PlainTab application data semantics.
If an IndexedDB-only change affects key names, record shape, references, old data cleanup, or jump upgrades, bump LS_VERSION and add a WallpaperData.migrate() path.
Do not use IndexedDB version upgrades for application-level migration decisions.
Pure discardable cache changes do not need LS_VERSION if missing or stale cache cannot be misread and does not require cleanup.

Migration Discipline

Before production edits, write or update a focused check in docs/ai-tasks/ and watch it fail for the missing migration behavior.

For each migration step:

Detect from persisted data, not app release numbers. Prefer ptab_schema_version, legacy ptab_version, old key presence, and current model facts.
Make the step idempotent. A browser close midway must be safe to retry.
Write large data first, then write references.
Never write references to missing Blob records.
Remove references before deleting large data.
Mark migration complete only after required new data and cleanup succeed.
Do not overwrite non-default data already created by a newer version.
Keep runtime modules reading only the current schema after migration.

Cleanup Rules

Delete obsolete localStorage keys after successful migration.
Delete obsolete IndexedDB keys with targeted deletes. Do not delete the whole PlainTab database while current data uses the same store.
Avoid permanent top-level marker keys for one-off migrations. If cleanup truly needs an idempotent retry marker, keep it scoped to an existing owned model, document why persisted facts are insufficient, and include a cleanup/removal path.
Keep old migration code for enough releases to support users who skip versions.

Validation

Run the focused migration check, then JS syntax validation:

node docs\ai-tasks\<migration-test>.js
Get-ChildItem -Recurse js -Include *.js | ForEach-Object { node --check $_.FullName }
git diff --check -- js docs/ai-tasks .claude/rules

If storage behavior changes, update .claude/rules/10-storage.md in the same change.