MPS: Skill for Claude Code

MPS Migrations Aspect

Loading companion skills

Companion names in this skill are lazy dependencies: load only those relevant to the current task. If this skill came from an MCP server, use the host's skill loader to resolve the companion's unique discovered entry URI on the same host-assigned originating server. If the host has no server-backed skill loader, stop and report that limitation; do not silently fall back to a filesystem copy. If this skill came from a filesystem catalog, load the named sibling from that same catalog at <skills-root>/<skill-name>/SKILL.md, even if remote skill loaders are also available. Do not invent a tool name or server endpoint.

Two complementary languages upgrade user models when language definitions change:

• jetbrains.mps.lang.migration (l:90746344-04fd-4286-97d5-b46ae6a81709) — core migration language with MigrationScript (class-based, programmatic) and PureMigrationScript (declarative, structural).
• jetbrains.mps.lang.script (l:0eddeefa-c2d6-4437-bc2c-de50fd4ce470) — Enhancement Scripts that apply concept-instance transformations, used for richer per-node updates.

These address the same problem at different abstraction levels: lang.migration handles structural language refactorings (concept moves/renames, removed concepts); lang.script handles content transformations (modifying properties, children, references of existing instances).

Critical Directives

• Before deleting, tightening or retyping an element of a language that is published or has instances, read references/language-evolution.md. A language is published unless the user or the task says it is local. Such changes break existing models although the structure tools answer ok:true. A published language deprecates and replaces instead, with a migration; a local one migrates its values with the Console.
• Do not confuse the two MigrationScript concepts. One is in lang.migration (BL ClassConcept, version-gated). The other (alias "Enhancement Script") is in lang.script (instance-level transformer). Always disambiguate by language ref.
• fromVersion is the version migrated FROM, not to — and both forms get it from a node factory. Both MigrationScript and PureMigrationScript have a node factory: creating either through a factory-running path (mps_mcp_create_root_node, mps_mcp_insert_root_node_from_json, the IDE's New root, replace with new initialized) sets fromVersion to the language's current version and bumps that version by 1 — do not set fromVersion yourself. Paths that skip factories — dryRun, copies (COPY_NODE, copy/paste, .copy), SNodeBuilder/quotations/plain new node<>()/add new root, and update_root_node_from_json on an existing root — do not bump, so a copied script duplicates its source's fromVersion ("Multiple scripts for version N"); fix the copy's fromVersion, then SYNC_VERSION. The language version is never set by hand: SYNC_VERSION derives it from the scripts, is idempotent, and is safe to repeat. Do not hand-edit the .mpl: MPS holds the descriptor in memory and would overwrite the edit.
• Any "language version" mismatch from the checker or the generator → SYNC_VERSION. The mismatch error also carries a "Set correct language version" quick fix (FixLanguageVersion), attached to the script(s) with the highest fromVersion in both directions — but it is not auto-applicable, so check_root_node_problems(autoApplyQuickFixes = true) will not apply it; apply it explicitly with mps_mcp_apply_intention when you want that route instead of SYNC_VERSION. Duplicate or missing versions carry no quick fix: SYNC_VERSION reports them in migrationProblems without fixing them — correct the offending script's fromVersion, then sync again.
• A version change is not effective for migration execution until the language module is rebuilt. The checker compares against the descriptor, but the migration executor reads the version off the generated LanguageRuntime, so a bumped-but-unbuilt language silently never offers the migration. SYNC_VERSION reports this as runtimeStale: true with a runtimeRecoveryAction (the factory's bump needs the same make); clear it with mps_mcp_alter_nodes MAKE (rebuild=true) on the language module.
• The language's own version is not the languageVersions stamp. usedLanguages[].version / dependencyVersions in a module descriptor record which version of another language that module was last migrated against. SYNC_VERSION deliberately leaves them alone — refreshing them marks pending migrations as already applied.
• Model naming is convention-driven and load-bearing. lang.migration scripts live in <language.fqn>.migration. lang.script Enhancement Scripts live in <language.fqn>.scripts. MPS discovers them by these names at startup.
• Migration scripts run in dependency order, determined by OrderDependency / ExecuteAfterDeclaration. Always declare ordering when the result of one script feeds the next.
• Do not hand-edit serialized .mps migration files. Use MPS MCP node tools.