Official agent skill

Mps Aspect Migrations

by JetBrains in JetBrains/MPS

A skill your agent uses when authoring or debugging MPS migration scripts that upgrade user models after a language definition changes — covers jetbrains.mps.lang.migration (MigrationScript…

OfficialApache-2.0Auto-check passedDevelopment

Install Mps Aspect Migrations

skills CLI
$ npx skills add JetBrains/MPS --skill mps-aspect-migrations -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install JetBrains/MPS mps-aspect-migrations --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/JetBrains/MPS.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/mps-aspect-migrations .claude/skills/mps-aspect-migrations && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
mps-aspect-migrations
GitHub stars
1.7k
Token cost
~2.6k tokens
SKILL.md length
1,058 words
Files
10 (incl. references)
Skills in repo
41
Repo updated
First seen
Licence
Apache-2.0

At a glance

A skill your agent uses when authoring or debugging MPS migration scripts that upgrade user models after a language definition changes — covers jetbrains.mps.lang.migration (MigrationScript…

  • Works in 6 steps: Decide form: PureMigrationScript for… → Create or locate the migration model… → Both forms: creating the script through… → …
  • PureMigrationScript declarative
  • SKILL.md covers Loading companion skills, Critical Directives, Workflow and Related Skills, plus 1 more section
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Mps Aspect Migrations is an agent skill from JetBrains/MPS, published by the product's own GitHub organization. Use when authoring or debugging MPS migration scripts that upgrade user models after a language definition changes — covers jetbrains.mps.lang.migration (MigrationScript class-based, PureMigrationScript declarative, MoveConcept/MoveContainmentLink/MoveReferenceLink/MoveProperty, ordering via OrderDependency, data exchange via putData/getData, RefactoringLog, ConceptMigrationReference) and jetbrains.mps.lang.script Enhancement Scripts (MigrationScript with MigrationScriptPartInstance, ExtractInterfaceMigration…

Its SKILL.md is about 2.6k tokens, which your agent loads only when the skill is triggered. The skill folder holds 10 other files, including reference files (for example `references/aspect-model-stereotypes.md`, `references/concept-ids.md` and `references/enhancement-scripts.md`).

It sits in Development, covering Database migrations. It works with JetBrains IDEs and Model Context Protocol. The repository describes itself as: JetBrains Meta programming System. The licence is Apache-2.0.

When your agent uses it

  • PureMigrationScript declarative
  • MoveConcept/MoveContainmentLink/MoveReferenceLink/MoveProperty
  • Ordering via OrderDependency
  • Data exchange via putData/getData

Example prompts

  • “/mps-aspect-migrations”

Workflow steps

6 steps, taken from the first numbered list in SKILL.md.

  1. Decide form: PureMigrationScript for structural moves/renames/removals; MigrationScript for programmatic transforms; Enhancement Script…
  2. Create or locate the migration model with mps_mcp_create_model (moduleName: "" plus modelName): .migration for lang.migration (aspect ID…
  3. Both forms: creating the script through a factory-running MCP write tool (step 4) sets fromVersion and bumps languageVersion via the…
  4. Build the script body (declarative parts, BL execute() method, or MigrationScriptPart_Instance updater) using the JSON blueprints in…
  5. Wire ordering (OrderDependency / ExecuteAfterDeclaration) and data flow (putData / getData) if needed.
  6. Validate via mps_mcp_check_root_node_problems, then MAKE the language module (rebuild=true) so the generated LanguageRuntime carries the…

What it can do on your machine

Read from SKILL.md and the folder at commit 3e9cfcd. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Mps Aspect Migrations loads about 2.6k tokens when it runs, and up to ~13k if it reads all its reference files. Until then it costs about 189 tokens; SKILL.md has 1,058 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~189
When it runs · the whole SKILL.md, loaded when a task matches
~2.6k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~13k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from JetBrains/MPS at commit 3e9cfcd, republished under its Apache-2.0 licence (© JetBrains). 1,058 words, ~2,613 tokens.

Download SKILL.mdSave it as .claude/skills/mps-aspect-migrations/SKILL.md (or your agent's skills folder). This skill also uses 9 other files; get the full folder from GitHub.
name
mps-aspect-migrations
description
Use when authoring or debugging MPS migration scripts that upgrade user models after a language definition changes — covers jetbrains.mps.lang.migration (MigrationScript class-based, PureMigrationScript declarative, MoveConcept/MoveContainmentLink/MoveReferenceLink/MoveProperty, ordering via OrderDependency, data exchange via putData/getData, RefactoringLog, ConceptMigrationReference) and jetbrains.mps.lang.script Enhancement Scripts (MigrationScript with MigrationScriptPart_Instance, ExtractInterfaceMigration, FactoryMigrationScriptPart, CommentMigrationScriptPart) — when a model needs version-gated upgrade, concept rename or removal, link or property rename, instance-level transformation, or composition of migration steps.
type
reference

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

  • 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.
Show full SKILL.md (468 more words)Show less

Workflow

  1. Decide form: PureMigrationScript for structural moves/renames/removals; MigrationScript for programmatic transforms; Enhancement Script for instance-level updates. See references/form-selection.md.
  2. Create or locate the migration model with mps_mcp_create_model (moduleName: "<language.fqn>" plus modelName): <language.fqn>.migration for lang.migration (aspect ID migration); <language.fqn>.scripts for Enhancement Scripts (aspect ID scripts). Both aspect IDs are case-sensitive and carry no @ suffix — see aspect-model-stereotypes.md. Add the used languages required for that form.
  3. Both forms: creating the script through a factory-running MCP write tool (step 4) sets fromVersion and bumps languageVersion via the concept's node factory — leave both alone. After the insert, or after editing/deleting/copying a script, or on any version-mismatch error, call mps_mcp_update_module(moduleName = "<language>", operation = "SYNC_VERSION"). If migrationProblems in its response is not empty, fix the listed scripts' fromVersion and sync again.
  4. Build the script body (declarative parts, BL execute() method, or MigrationScriptPart_Instance updater) using the JSON blueprints in references/json-blueprints.md.
  5. Wire ordering (OrderDependency / ExecuteAfterDeclaration) and data flow (putData / getData) if needed.
  6. Validate via mps_mcp_check_root_node_problems, then MAKE the language module (rebuild=true) so the generated LanguageRuntime carries the new version, then run the migration on a test model. Skipping the make leaves runtimeStale: true and the migration is never offered.
  • mps-aspect-typesystem, mps-aspect-constraints — when a migration depends on or alters typesystem rules.
  • mps-aspect-generator — when version changes also touch generator templates.
  • mps-quotations — for QuotationConsequence consequence bodies inside MigrationScript.execute().
  • mps-model-manipulation — BL + smodel constructs used inside MigrationScript.execute() and Enhancement Script updaters; for the rewrite itself open only references/property-and-mutation-ops.md in the mps-model-manipulation skill root after loading that companion skill from the same origin.

Reference Index

Start here — most common case: if the form is not decided yet, read only references/form-selection.md — it routes you to the single file for the chosen form (declarative rename/move → references/pure-migration-parts.md; programmatic body → references/migration-script-body.md; instance sweep → references/enhancement-scripts.md), plus references/json-blueprints.md when inserting through MCP.

  • Form selection guide — open before authoring to pick between PureMigrationScript, MigrationScript, and Enhancement Script for the change at hand. Covers ordering, data flow, and model setup. See references/form-selection.md.
  • lang.migration concept reference — open when you need exact members, cardinalities, properties, or concept IDs for MigrationScript, PureMigrationScript, IMigrationUnit, ordering and data-exchange concepts, and RefactoringLog. See references/lang-migration-reference.md.
  • PureMigrationPart, node references, and move specializations — open when defining concept/link/property renames or composing migration units via IncludeMigrationPart. See references/pure-migration-parts.md.
  • MigrationScript execute-body constructs — open when writing the BL body of a programmatic MigrationScript: pattern variable references, ConsequenceFunction vs QuotationConsequence, ConceptMigrationReference. See references/migration-script-body.md.
  • lang.script Enhancement Scripts — open when iterating over concept instances to update properties/children/references, or when wiring ExtractInterfaceMigration, FactoryMigrationScriptPart, or CommentMigrationScriptPart. See references/enhancement-scripts.md.
  • Verified JSON blueprints — open when constructing a real migration as JSON for MCP tools. Includes MigrateReferences, SNodeTypeCastExpression_completelyRemoved, and Migrate_ParametrizedIntentions. See references/json-blueprints.md.
  • Concept ID quick reference — open when assembling JSON that requires conceptReference strings for lang.migration and lang.script. See references/concept-ids.md.
  • FIND_INSTANCES recipes — open to enumerate existing migration scripts or enhancement scripts in the project. See references/find-instances.md.

© JetBrains, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 9 other files (references) in .agents/skills/mps-aspect-migrations of JetBrains/MPS.

  • SKILL.md
  • references/aspect-model-stereotypes.md
  • references/concept-ids.md
  • references/enhancement-scripts.md
  • references/find-instances.md
  • references/form-selection.md
  • references/json-blueprints.md
  • references/lang-migration-reference.md
  • references/migration-script-body.md
  • references/pure-migration-parts.md

Open the folder on GitHubat commit 3e9cfcd

Compare with similar skills

Mps Aspect Migrations next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Mps Aspect Migrations compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Mps Aspect Migrations this skillJetBrains/MPS1.7k—~2.6kAutomated safety check: PassApache-2.0
LangBot Core Developmentlangbot-app/LangBot18k—~1.4kAutomated safety check: NotesApache-2.0
Idea MCPdtprj/dongting208—~698Automated safety check: PassApache-2.0
Java DebugAmplicode/spring-skills128—~2.7kAutomated safety check: PassNone
Supabase Development and Debuggingsupabase/agent-skills2.7k3 repos~3.6kAutomated safety check: PassMIT
Planningn8n-io/n8n207k—~2.5kAutomated safety check: PassCustom licence

Similar skills

  • LangBot Core Development

    langbot-app/LangBot

    Covers developing the LangBot core backend and web UI: dev setup, repo layout, API auth types, adding endpoints, migrations and keeping the MCP server in step.

    18k GitHub stars~1.4k tokensUpdated today
    DevelopmentAuto-check: notes
  • Idea MCP

    dtprj/dongting

    IntelliJ IDEA MCP for Java code analysis, testing, refactoring, and project navigation.

    208 GitHub stars~698 tokensUpdated today
    DevelopmentAuto-check passed
  • Java Debug

    Amplicode/spring-skills

    Safety rules, workflows, and tool reference for debugging applications via IntelliJ debugger: breakpoints, debug sessions, stepping, evaluating expressions, inspecting runtime state.

    128 GitHub stars~2.7k tokensUpdated 1 mo ago
    DevelopmentAuto-check passed
  • Official

    General Supabase skill for database, auth, Edge Functions, Realtime and storage work, plus client libraries, migrations, security audits, debugging and reading logs.

    2.7k GitHub starsUsed in 3 repos~3.6k tokens
    Backend & APIsAuto-check passed
  • Planning

    n8n-io/n8n

    Official

    ONLY for coordinated multi-artifact work: multiple workflows with dependencies, shared data-table schema/migration across tasks, or the user explicitly asked to review a plan first.

    207k GitHub stars~2.5k tokensUpdated today
    Productivity & AutomationAuto-check passed
  • Neon Postgres

    smontlouis/bible-strong

    Guides and best practices for working with Lakebase Postgres, the database behind Neon.

    171 GitHub starsUsed in 1 repo~2.3k tokens
    DatabasesAuto-check: notes

More from JetBrains/MPS

All 41 skills in this repo
  • Official

    Analyze an MPS language by name — discover concepts, properties, references, children, aspects (editor/constraints/behavior), metadata, and answer type questions (is A a subtype of B, common…

    1.7k GitHub stars~1.8k tokensUpdated today
    Auto-check passed
  • Mps Node Editing

    JetBrains/MPS

    Official

    Add, update, or delete MPS nodes using JSON blueprints — covers the unified blueprint format, staged construction for large subtrees, validation, and reference repair.

    1.7k GitHub stars~5.1k tokensUpdated today
    Auto-check passed
  • Official

    Open an MPS project in a running or freshly started MPS instance when MCP tools fail because no project is open (welcome screen), close an open project with mpsmcpcloseproject, or create a new empty…

    1.7k GitHub stars~2.2k tokensUpdated today
    Auto-check passed
  • Mps MCP Workflow

    JetBrains/MPS

    Official

    Complete JetBrains MPS workflow guide for DSL projects — models, languages, generators, node JSON blueprints, type queries, validation, MPS MCP tool usage, and the index of companion skills.

    1.7k GitHub stars~6.6k tokensUpdated today
    Auto-check passed
  • Bugfix Workflow

    JetBrains/MPS

    Official

    Structured MPS bugfix workflow driven by a YouTrack issue ID — preflight tool checks, version/branch derivation, parallel-agent problem analysis, solution design, branch creation, implementation…

    1.7k GitHub stars~4.4k tokensUpdated today
    Auto-check passed
  • Official

    Define concepts, interface concepts, enumerations, and constrained data types in an MPS language's structure aspect.

    1.7k GitHub stars~2.8k tokensUpdated today
    Auto-check passed

Questions about Mps Aspect Migrations

What does Mps Aspect Migrations do?

A skill your agent uses when authoring or debugging MPS migration scripts that upgrade user models after a language definition changes — covers jetbrains.mps.lang.migration (MigrationScript…. Mps Aspect Migrations is an agent skill from JetBrains/MPS, published by the product's own GitHub organization.

When should I use Mps Aspect Migrations?

Mps Aspect Migrations fits situations like: pureMigrationScript declarative; moveConcept/MoveContainmentLink/MoveReferenceLink/MoveProperty; ordering via OrderDependency; data exchange via putData/getData.

How do I install Mps Aspect Migrations in Claude Code?

Run `npx skills add JetBrains/MPS --skill mps-aspect-migrations -a claude-code`. Or copy the skill folder (.agents/skills/mps-aspect-migrations in JetBrains/MPS) into .claude/skills/mps-aspect-migrations in your project. Claude Code loads it when a task matches its description.

How do I install Mps Aspect Migrations in Codex?

Run `npx skills add JetBrains/MPS --skill mps-aspect-migrations -a codex`. Or copy the skill folder (.agents/skills/mps-aspect-migrations in JetBrains/MPS) into .agents/skills/mps-aspect-migrations in your project. Codex loads it when a task matches its description.

Can I use Mps Aspect Migrations in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add JetBrains/MPS --skill mps-aspect-migrations -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/mps-aspect-migrations, .gemini/skills/mps-aspect-migrations, .github/skills/mps-aspect-migrations and .opencode/skills/mps-aspect-migrations in your project.

What does Mps Aspect Migrations need to run?

SKILL.md names no scripts, command-line tools or credentials: Mps Aspect Migrations is instructions for the agent only.

Does Mps Aspect Migrations access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Mps Aspect Migrations safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Mps Aspect Migrations use?

Mps Aspect Migrations is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Mps Aspect Migrations use?

About 2.6k tokens (SKILL.md is roughly 10k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 11k tokens, read only when the agent opens those files.

What are the alternatives to Mps Aspect Migrations?

Skills that share tags, products or a category with Mps Aspect Migrations: LangBot Core Development (langbot-app/LangBot, 18k stars), Idea MCP (dtprj/dongting, 208 stars), Java Debug (Amplicode/spring-skills, 128 stars) and Supabase Development and Debugging (supabase/agent-skills, 2.7k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Mps Aspect Migrations?

JetBrains (a GitHub organization, an official publisher) maintains it in JetBrains/MPS, which has 1,661 GitHub stars. The repository holds 41 skills in this directory. The repository was last updated on October 9, 2026.

Source: JetBrains/MPS on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.