Official agent skill

Extensions API Migration

Migrates IdeaVim extensions from the old VimExtensionFacade API to the new @VimPlugin annotation-based API.

OfficialMITAuto-check passedDevelopment

Install Extensions API Migration

skills CLI

$ npx skills add JetBrains/ideavim --skill extensions-api-migration -a claude-code

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

GitHub CLI

$ gh skill install JetBrains/ideavim extensions-api-migration --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/ideavim.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/extensions-api-migration .claude/skills/extensions-api-migration && 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/

Paste into Claude Code

Install the "extensions-api-migration" agent skill from https://github.com/JetBrains/ideavim/tree/master/.claude/skills/extensions-api-migration into .claude/skills/extensions-api-migration/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "extensions-api-migration", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/JetBrains/ideavim/tree/master/.claude/skills/extensions-api-migration

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add JetBrains/ideavim --skill extensions-api-migration -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install JetBrains/ideavim extensions-api-migration --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/JetBrains/ideavim.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.claude/skills/extensions-api-migration .agents/skills/extensions-api-migration && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "extensions-api-migration" agent skill from https://github.com/JetBrains/ideavim/tree/master/.claude/skills/extensions-api-migration into .agents/skills/extensions-api-migration/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "extensions-api-migration", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add JetBrains/ideavim --skill extensions-api-migration -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install JetBrains/ideavim extensions-api-migration --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/JetBrains/ideavim.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.claude/skills/extensions-api-migration .cursor/skills/extensions-api-migration && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "extensions-api-migration" agent skill from https://github.com/JetBrains/ideavim/tree/master/.claude/skills/extensions-api-migration into .cursor/skills/extensions-api-migration/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "extensions-api-migration", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/JetBrains/ideavim.git --path .claude/skills/extensions-api-migration

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add JetBrains/ideavim --skill extensions-api-migration -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install JetBrains/ideavim extensions-api-migration --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/JetBrains/ideavim.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.claude/skills/extensions-api-migration .gemini/skills/extensions-api-migration && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "extensions-api-migration" agent skill from https://github.com/JetBrains/ideavim/tree/master/.claude/skills/extensions-api-migration into .gemini/skills/extensions-api-migration/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "extensions-api-migration", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install JetBrains/ideavim extensions-api-migration

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add JetBrains/ideavim --skill extensions-api-migration -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/JetBrains/ideavim.git skills-src && mkdir -p .github/skills && cp -r skills-src/.claude/skills/extensions-api-migration .github/skills/extensions-api-migration && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "extensions-api-migration" agent skill from https://github.com/JetBrains/ideavim/tree/master/.claude/skills/extensions-api-migration into .github/skills/extensions-api-migration/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "extensions-api-migration", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add JetBrains/ideavim --skill extensions-api-migration -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install JetBrains/ideavim extensions-api-migration --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/JetBrains/ideavim.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.claude/skills/extensions-api-migration .opencode/skills/extensions-api-migration && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "extensions-api-migration" agent skill from https://github.com/JetBrains/ideavim/tree/master/.claude/skills/extensions-api-migration into .opencode/skills/extensions-api-migration/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "extensions-api-migration", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: extensions-api-migration
GitHub stars: 10k
Token cost: ~1.7k tokens
SKILL.md length: 554 words
Files: 1
Skills in repo: 5
Repo updated: Oct 7, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

Migrates IdeaVim extensions from the old VimExtensionFacade API to the new @VimPlugin annotation-based API.

Works in 4 steps: Ensure Test Coverage → Migrate in Small Steps → Migrate Handlers One by One → …
Converting existing extensions to use the new API patterns
SKILL.md covers Key Locations, How to Use the New API and How to Migrate Existing…
Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Extensions API Migration is an agent skill from JetBrains/ideavim, published by the product's own GitHub organization. Migrates IdeaVim extensions from the old VimExtensionFacade API to the new @VimPlugin annotation-based API. Use when converting existing extensions to use the new API patterns.

Its SKILL.md is about 1.7k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Development. It works with JetBrains IDEs and Kotlin. The repository describes itself as: IdeaVim – A Vim engine for JetBrains IDEs. The licence is MIT.

When your agent uses it

Converting existing extensions to use the new API patterns

Example prompts

“Use the extensions-api-migration skill to migrate IdeaVim extensions from the old VimExtensionFacade API to the new @VimPlugin annotation-based API”
“/extensions-api-migration”

Workflow steps

4 steps, taken from the step headings in SKILL.md.

Ensure Test Coverage
Migrate in Small Steps
Migrate Handlers One by One
Handler Migration Process

What it can do on your machine

Read from SKILL.md and the folder at commit 37aeff6. 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 (its code samples are kotlin).
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

Extensions API Migration loads about 1.7k tokens when it runs. Until then it costs about 50 tokens; SKILL.md has 554 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~50
When it runs · the whole SKILL.md, loaded when a task matches: ~1.7k

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/ideavim at commit 37aeff6, republished under its MIT licence (© JetBrains). 554 words, ~1,711 tokens.

Download SKILL.mdSave it as .claude/skills/extensions-api-migration/SKILL.md (or your agent's skills folder).

name: extensions-api-migration
description: Migrates IdeaVim extensions from the old VimExtensionFacade API to the new @VimPlugin annotation-based API. Use when converting existing extensions to use the new API patterns.

Extensions API Migration

You are an IdeaVim extensions migration specialist. Your job is to help migrate existing IdeaVim extensions from the old API (VimExtensionFacade) to the new API (@VimPlugin annotation).

Key Locations

New API module: api/ folder - contains the new plugin API
Old API: VimExtensionFacade in vim-engine
Extensions location: src/main/java/com/maddyhome/idea/vim/extension/

How to Use the New API

Getting Access to the API

To get access to the new API, call the api() function from com.maddyhome.idea.vim.extension.api:

kotlin

val api = api()

Obtain the API at the start of the init() method - this is the entry point for all further work.

Registering Text Objects

Use api.textObjects { } to register text objects:

kotlin

// From VimIndentObject.kt
override fun init() {
  val api = api()
  api.textObjects {
    register("ai") { _ -> findIndentRange(includeAbove = true, includeBelow = false) }
    register("aI") { _ -> findIndentRange(includeAbove = true, includeBelow = true) }
    register("ii") { _ -> findIndentRange(includeAbove = false, includeBelow = false) }
  }
}

Registering Mappings

Use api.mappings { } to register mappings:

kotlin

// From ParagraphMotion.kt
override fun init() {
  val api = api()

  api.mappings {
    nmapPluginAction("}", "<Plug>(ParagraphNextMotion)", keepDefaultMapping = true) {
      moveParagraph(1)
    }
    nmapPluginAction("{", "<Plug>(ParagraphPrevMotion)", keepDefaultMapping = true) {
      moveParagraph(-1)
    }
    xmapPluginAction("}", "<Plug>(ParagraphNextMotion)", keepDefaultMapping = true) {
      moveParagraph(1)
    }
    // ... operator-pending mode mappings with omapPluginAction
  }
}

Defining Helper Functions

The lambdas in text object and mapping registrations typically call helper functions. Define these functions with VimApi as a receiver - this makes the API available inside:

kotlin

// From VimIndentObject.kt
private fun VimApi.findIndentRange(includeAbove: Boolean, includeBelow: Boolean): TextObjectRange? {
  val charSequence = editor { read { text } }
  val caretOffset = editor { read { withPrimaryCaret { offset } } }
  // ... implementation using API
}

// From ParagraphMotion.kt
internal fun VimApi.moveParagraph(direction: Int) {
  val count = getVariable<Int>("v:count1") ?: 1
  editor {
    change {
      forEachCaret {
        val newOffset = getNextParagraphBoundOffset(actualCount, includeWhitespaceLines = true)
        if (newOffset != null) {
          updateCaret(offset = newOffset)
        }
      }
    }
  }
}

API Features

<!-- Fill in additional API features here -->

How to Migrate Existing Extensions

What Stays the Same

The extension still inherits VimExtensionFacade - this does not change
The extension still registers in the XML file - this does not change

Migration Steps

Step 1: Ensure Test Coverage

Before starting migration, make sure tests exist for the extension:

Tests should work and have good coverage
If there aren't enough tests, create more tests first
Verify tests pass on the existing version of the plugin

Step 2: Migrate in Small Steps

Don't try to handle everything in one run
Run tests on the plugin (just the single test class to speed up things) after making smaller changes
This ensures consistency and makes it easier to identify issues
Do a separate commit for each small sensible change or migration unless explicitly told not to

Step 3: Migrate Handlers One by One

If the extension has multiple handlers, migrate them one at a time rather than all at once.

Show full SKILL.md (259 more words)Show less

Step 4: Handler Migration Process

For each handler, follow this approach:

Inject the API: Add val api = api() as the first line inside the execute function
Extract to extension function: Extract the content of the execute function into a separate function outside the ExtensionHandler class. The new function should:
- Have VimApi as a receiver
- Use the api that was obtained before
- Keep the extraction as-is (no changes to logic yet)
Verify tests pass: Run tests to ensure the extraction didn't break anything
Migrate function content: Now start migrating the content of the extracted function to use the new API
Verify tests pass again: Run tests after each significant change
Update registration: Finally, change the registration of shortcuts from the existing approach to api.mappings { } where you call the newly created function

Example Migration Flow

kotlin

// BEFORE: Old style handler
class MyHandler : ExtensionHandler {
  override fun execute(editor: VimEditor, context: ExecutionContext, operatorArguments: OperatorArguments) {
    // ... implementation
  }
}

// STEP 1: Inject API
class MyHandler : ExtensionHandler {
  override fun execute(editor: VimEditor, context: ExecutionContext, operatorArguments: OperatorArguments) {
    val api = api()
    // ... implementation
  }
}

// STEP 2: Extract to extension function (as-is)
class MyHandler : ExtensionHandler {
  override fun execute(editor: VimEditor, context: ExecutionContext, operatorArguments: OperatorArguments) {
    val api = api()
    api.doMyAction(/* pass needed params */)
  }
}

private fun VimApi.doMyAction(/* params */) {
  // ... same implementation, moved here
}

// STEP 3-5: Migrate content to new API inside doMyAction()

// STEP 6: Update registration to use api.mappings { }
override fun init() {
  val api = api()
  api.mappings {
    nmapPluginAction("key", "<Plug>(MyAction)") {
      doMyAction()
    }
  }
}
// Now MyHandler class can be removed

Handling Complicated Plugins

For more complicated plugins, additional steps may be required.

For example, there might be a separate large class that performs calculations. However, this class may not be usable as-is because it takes a Document - a class that is no longer directly available through the new API.

In this case, perform a pre-refactoring step: update this class to remove the Document dependency before starting the main migration. For instance, change it to accept CharSequence instead, which is available via the new API.

Final Verification: Check for Old API Usage

After migration, verify that no old API is used by checking imports for com.maddyhome.

Allowed imports (these are still required):

com.maddyhome.idea.vim.extension.VimExtension
com.maddyhome.idea.vim.extension.api

Any other com.maddyhome imports indicate incomplete migration.

Files

Just SKILL.md in .claude/skills/extensions-api-migration of JetBrains/ideavim.

Open the folder on GitHubat commit 37aeff6

Compare with similar skills

Extensions API Migration 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.

Extensions API Migration compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Extensions API Migration this skillJetBrains/ideavim	10k	—	~1.7k	Automated safety check: Pass	MIT	today
CodefmtAmplicode/spring-skills	126	—	~595	Automated safety check: Pass	None	1 mo ago
Compose Multiplatform Patternsmonta-app/ocpp-emulator	179	5 repos	~2k	Automated safety check: Pass	Apache-2.0	6 days ago
Drop Platform SupportJetBrains/educational-plugin	181	—	~4k	Automated safety check: Pass	Apache-2.0	yesterday
Kotlin Tooling Kotlin ToolchainKotlin/kotlin-agent-skills	1.1k	—	~2.4k	Automated safety check: Pass	Apache-2.0	8 days ago
Kotlin Exposed Patternsaffaan-m/ECC	274k	4 repos	~5.5k	Automated safety check: Pass	MIT	2 days ago

Similar skills

Codefmt
Amplicode/spring-skills
Reformat source code in this project using its own code-style settings — through the IntelliJ IDE when it's running, otherwise via the project's own formatter (Spotless / google-java-format /…
126 GitHub stars~595 tokensUpdated 1 mo ago
MobileAuto-check passed
Compose Multiplatform Patterns
monta-app/ocpp-emulator
Compose Multiplatform and Jetpack Compose patterns for KMP projects — state management, navigation, theming, performance, and platform-specific UI.
179 GitHub starsUsed in 5 repos~2k tokens
MobileAuto-check passed
Drop Platform Support
JetBrains/educational-plugin
Official
Drops support for an old IntelliJ platform version in the JetBrains Academy plugin — removes branches/<old code, moves shared platform-specific code to the main source set, and fixes BACKCOMPAT…
181 GitHub stars~4k tokensUpdated yesterday
MobileAuto-check passed
Kotlin Tooling Kotlin Toolchain
Kotlin/kotlin-agent-skills
Load when building, running, testing, packaging, linting, or configuring a Kotlin/Java project with the Kotlin Toolchain (JetBrains' unified CLI, formerly Amper), when scaffolding a new or…
1.1k GitHub stars~2.4k tokensUpdated 8 days ago
MobileAuto-check passed
Kotlin Exposed Patterns
affaan-m/ECC
JetBrains Exposed ORM patterns including DSL queries, DAO pattern, transactions, HikariCP connection pooling, Flyway migrations, and repository pattern.
274k GitHub starsUsed in 4 repos~5.5k tokens
DatabasesAuto-check passed
Migrate Intellij Util
flutter/flutter-intellij
Optimize memory usage, consistency, and performance by migrating standard Java/Kotlin classes to IntelliJ's specialized com.intellij.util implementations.
2k GitHub stars~600 tokensUpdated 2 days ago
MobileAuto-check passed

Questions about Extensions API Migration

What does Extensions API Migration do?

Migrates IdeaVim extensions from the old VimExtensionFacade API to the new @VimPlugin annotation-based API. Extensions API Migration is an agent skill from JetBrains/ideavim, published by the product's own GitHub organization. Migrates IdeaVim extensions from the old VimExtensionFacade API to the new @VimPlugin annotation-based API.

When should I use Extensions API Migration?

Extensions API Migration fits situations like: converting existing extensions to use the new API patterns.

How do I install Extensions API Migration in Claude Code?

Run `npx skills add JetBrains/ideavim --skill extensions-api-migration -a claude-code`. Or copy the skill folder (.claude/skills/extensions-api-migration in JetBrains/ideavim) into .claude/skills/extensions-api-migration in your project. Claude Code loads it when a task matches its description.

How do I install Extensions API Migration in Codex?

Run `npx skills add JetBrains/ideavim --skill extensions-api-migration -a codex`. Or copy the skill folder (.claude/skills/extensions-api-migration in JetBrains/ideavim) into .agents/skills/extensions-api-migration in your project. Codex loads it when a task matches its description.

Can I use Extensions API Migration 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/ideavim --skill extensions-api-migration -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/extensions-api-migration, .gemini/skills/extensions-api-migration, .github/skills/extensions-api-migration and .opencode/skills/extensions-api-migration in your project.

What does Extensions API Migration need to run?

SKILL.md names no scripts, command-line tools or credentials: Extensions API Migration is instructions for the agent only.

Does Extensions API Migration 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 Extensions API Migration 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 Extensions API Migration use?

Extensions API Migration is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Extensions API Migration use?

About 1.7k tokens (SKILL.md is roughly 6.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Extensions API Migration?

Skills that share tags, products or a category with Extensions API Migration: Codefmt (Amplicode/spring-skills, 126 stars), Compose Multiplatform Patterns (monta-app/ocpp-emulator, 179 stars), Drop Platform Support (JetBrains/educational-plugin, 181 stars) and Kotlin Tooling Kotlin Toolchain (Kotlin/kotlin-agent-skills, 1.1k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Extensions API Migration?

JetBrains (a GitHub organization, an official publisher) maintains it in JetBrains/ideavim, which has 10,278 GitHub stars. The repository holds 5 skills in this directory. The repository was last updated on October 7, 2026.

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

Install Extensions API Migration

Facts

At a glance

What it does

When your agent uses it

Example prompts

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Extensions API Migration

Key Locations

How to Use the New API

Getting Access to the API

Registering Text Objects

Registering Mappings

Defining Helper Functions

API Features

How to Migrate Existing Extensions

What Stays the Same

Migration Steps

Step 1: Ensure Test Coverage

Step 2: Migrate in Small Steps

Step 3: Migrate Handlers One by One

Step 4: Handler Migration Process

Example Migration Flow

Handling Complicated Plugins

Final Verification: Check for Old API Usage

Files

Compare with similar skills

Similar skills

More from JetBrains/ideavim

Related

Questions about Extensions API Migration