Intellij platform sdk

IntelliJ Platform SDK Skill

Use this skill for IntelliJ Platform plugin development based on the modern v2 SDK.

This skill is intentionally split into focused references so the main file stays small and the model can load only the material relevant to the task.

What this skill helps with

• creating or updating IntelliJ Platform plugins
• configuring build.gradle.kts, settings.gradle.kts, and plugin.xml
• implementing actions, services, tool windows, settings, and notifications
• working with PSI, references, indexing, VFS, and dumb mode
• building custom language support
• implementing inspections, intentions, quick fixes, completion, formatting, and documentation
• implementing run configurations, program runners, and execution consoles
• providing live templates, file templates, and postfix completion
• creating or extending IDE themes and color schemes
• integrating Language Servers (LSP) in plugin-development context
• contributing MCP tools and toolsets
• testing plugins and preparing Marketplace publication
• handling version compatibility and Gradle plugin migration

How to use this skill

First, identify the user’s real task. Then read only the relevant reference files.

Read references/getting-started.md when the task is about

• creating a new IntelliJ Platform plugin project
• setting up IntelliJ Platform Gradle Plugin 2.x for a plugin project
• choosing target IDEs or bundled plugins for plugin development
• adding optional plugin/module dependencies in plugin.xml (see also plugin-registration.md for full <depends> semantics)
• writing or fixing plugin-project plugin.xml metadata (high-level — see plugin-registration.md for the complete element/attribute reference)

Read references/plugin-registration.md when the task is about

• writing or fixing the plugin.xml descriptor structure
• <idea-plugin> root attributes (url, require-restart)
• metadata elements (<id>, <name>, <vendor>, <description>, <change-notes>, <product-descriptor>)
• <idea-version> since/until/strict-until-build and the Gradle pluginConfiguration relationship
• <depends> required vs optional, config-file merge semantics, additional descriptor naming, <incompatible-with>
• declarative listeners (<applicationListeners> / <projectListeners> <listener> attributes)
• <actions> full sub-elements (<add-to-group>, <mouse-shortcut>, <override-text>, <synonym>, <abbreviation>, <reference>, <separator>)
• <extensionPoint> qualifiedName/area/<with> and <extensions> id/order/os basic attributes
• <resource-bundle>, <xi:include>, service registration XML (testServiceImplementation/headlessImplementation)
• dynamic-plugin registration requirements, require-restart, paid-plugin limitation
• plugin logo file placement (pluginIcon.svg / pluginIcon_dark.svg)

Read references/platform-basics.md when the task is about

• AnAction, action groups, menus, toolbars
• services (@Service, project/application/module services)
• logging (Logger, logger<T>(), thisLogger())
• background tasks (Task.Backgroundable, ProgressManager, ProgressIndicator)
• debouncing and batching updates (DebouncedUpdates, 2026.2+)
• Virtual File System (VirtualFile, VFS listeners)
• threading, read/write actions, dumb mode, modality
• Kotlin coroutine patterns in plugins (readAction, writeAction, CoroutineScope)
• dynamic plugin loading/unloading
• disposable lifecycle management
• messaging infrastructure (MessageBus, Topic)
• general plugin architecture decisions
• split mode concepts and modular plugin organization (see split-mode-rpc.md for full RPC/frontend-backend details)
• Workspace Model high-level overview (see workspace-model.md for the complete API reference)

Read references/split-mode-rpc.md when the task is about

• setting up split/remote-development plugin modules (shared/frontend/backend)
• @Rpc interfaces, RemoteApi, RemoteApiProviderService, durable {} for cross-side communication
• which APIs belong in frontend vs backend vs shared
• split-mode PSI/index/VFS/execution constraints
• serializable ID types (ProjectId, VirtualFileId, EditorId)
• remote topics (ApplicationRemoteTopic / ProjectRemoteTopic) for backend-to-frontend push
• DTO patterns and kotlinx-serialization version compatibility
• Gradle split-mode setup (splitMode, pluginInstallationTarget, bundledModule per side)
• debugging split mode (runIdeBackend / runIdeFrontend, latency emulation)

Read references/workspace-model.md when the task is about

• reading project structure with WorkspaceModel.getInstance(project).currentSnapshot
• modifying entities via workspaceModel.update("label") { builder -> ... }
• bulk-replacing project structure from external systems (replaceBySource())
• declaring custom @Entity types with @EntityProperty
• entity sources (JpsFileEntitySource, ExternalEntitySource, GradleEntitySource)
• event listening via WorkspaceModelTopics.CHANGED
• bridging Workspace Model entities to traditional Module/Library/Facet APIs
• VirtualFileUrl and SymbolicEntityId for cross-entity references

Read references/psi-and-indexing.md when the task is about

• PSI traversal or modification
• references, resolve, rename, find usages, safe delete
• code generation using PSI factories
• file-based indexes, stub indexes, gists
• file view providers (multi-language PSI trees in a single file)
• IndexNotReadyException, dumb mode, PSI performance
• PSI cookbook (Java-specific common operations)
• caching with CachedValuesManager

Read references/language-support-and-analysis.md when the task is about

• custom language plugins
• lexer, parser, ParserDefinition
• syntax highlighting, annotators, completion
• inspections, intentions, quick fixes
• rename refactoring, rename validation, safe delete
• formatter, folding, structure view, documentation provider
• parameter info, spell checking, navigation bar integration
• inlay hints, code vision
• language injection
• Symbols API and declarations/references model
• Poly Symbols and Web Types for web-framework metadata
• DocumentationTarget API
• OptPane, declarative inspection options, OptionController
• element patterns (PlatformPatterns, PsiElementPattern) for completion/reference contributors
• color scheme management, TextAttributesKey dependency chaining

Read references/ui-settings-and-toolwindows.md when the task is about

• Kotlin UI DSL v2 (panel { row { } }, BoundConfigurable)
• dialogs and IntelliJ UI components
• tool windows
• settings/configurables (including parentId/settings groups hierarchy)
• persistent state
• notifications
• popups (JBPopup, ListPopup, chooser popups)
• new project wizard, module type, project view integration
• status bar widgets
• editor notification banners
• persisting sensitive data (PasswordSafe)
• embedded editor components (EditorTextField)
• internationalization (i18n) and localization
• accessibility (keyboard navigation, screen readers)
• plugin UX principles

Read references/testing-and-publishing.md when the task is about

• test fixtures and plugin tests
• integration tests or UI tests
• Starter/Driver-based test setup
• parser/completion/inspection tests
• plugin verifier
• verifyPluginProjectConfiguration / verifyPluginStructure
• signing and publishing to Marketplace

Read references/compatibility.md when the task is about

• build compatibility
• sinceBuild / untilBuild
• migrating from legacy Gradle plugin 1.x to 2.x
• API changes across platform versions
• Java/Kotlin version expectations
• Workspace Model migration or newer platform API transitions

Read references/extension_points.md when the task is about

• exact plugin.xml registration syntax
• locating the right extension point
• action group IDs and XML patterns
• MCP extension points such as com.intellij.mcpServer.*

Read references/code_samples.md when the task is about

• finding the closest official SDK sample
• copying an official implementation pattern
• understanding what each JetBrains sample demonstrates

Read references/lsp.md when the task is about

• integrating a Language Server into an IntelliJ Platform plugin
• LspServerSupportProvider / LspIntegrationProvider, LspServerDescriptor / LspClientDescriptor, or LSP-specific plugin.xml dependencies
• LSP setup for supported JetBrains IDE products and platform versions in plugin-development context
• LSP feature support timeline inside the IntelliJ Platform
• deciding between LSP integration and native IntelliJ language support for a plugin

Read references/mcp-and-ai-integration.md when the task is about

• MCP-related plugin integration in an IntelliJ Platform plugin
• contributing MCP tools or defining MCP toolsets
• understanding MCP-related extension points such as com.intellij.mcpServer.*
• MCP guidance in areas where the official SDK docs are still sparse

Read references/execution-and-run-configs.md when the task is about

• implementing custom run configurations (ConfigurationType, RunConfigurationBase)
• run configuration producers (auto-detecting configurations from context)
• program runners and execution environments
• execution consoles and console filters
• run configuration macros
• before/after launch tasks

Read references/webview-jcef.md when the task is about

• embedding a Chromium-based browser (JBCefBrowser) inside the IDE for rendering HTML or custom web components
• checking JCEF availability with JBCefApp.isSupported() and graceful fallback
• JS ⇄ Java bidirectional communication (JBCefJSQuery, JBCefJavaScriptFunction)
• JCEF lifecycle, disposal, threading (handlers fire on dedicated threads, not EDT)
• plugin.xml and JBR requirements for JCEF (no com.intellij.modules.jcef module — runtime JBR variant is the real constraint)
• Remote Development / Gateway constraints (JCEF runs on the thin client, not the backend)
• creating JBCefBrowserBuilder with custom clients and handlers
• debugging JCEF (DevTools integration, registry keys)
• common pitfalls: dispose leaks, thread violations, access after disposal

Read references/templates.md when the task is about

• providing live templates bundled in a plugin
• custom live template macros/functions
• file and code templates (Velocity-based)
• postfix completion templates
• surround-with descriptors

Read references/themes.md when the task is about

• creating or extending IDE UI themes
• theme JSON descriptor format
• editor color scheme integration
• icon customization in themes
• Islands theme compatibility
• deploying and publishing theme plugins

Read references/icons.md when the task is about

• adding or organizing icons in a plugin
• icon file naming conventions (dark variants, HiDPI)
• icon holder classes (by-path vs by-class referencing)
• New UI (expui) icon requirements and icon mappings
• animated icons (AnimatedIcon, AsyncProcessIcon)
• icon tooltips via resource bundles

Read references/patterns.md when the task is about

• reusable implementation patterns
• editor/document helpers (caret position, selection, scrolling)
• editor coordinate system (offsets, logical/visual positions)
• editor FAQ (get active editor, listen for events, custom tab title/color)
• progress handling
• dialog/tool-window patterns
• PSI/editor/VFS utilities
• icon loading and rendering patterns

Read references/troubleshooting.md when the task is about

• you are not yet sure which troubleshooting bucket the issue belongs to
• actions not appearing
• threading assertions
• service initialization failures
• PSI write-action errors
• verifier warnings
• test setup failures

Read references/troubleshooting-build-runtime.md when the task is about

• Gradle or repository resolution failures
• plugin.xml wiring or class loading issues
• action registration/runtime visibility issues
• verifier/signing/release failures

Read references/troubleshooting-psi-ui-testing.md when the task is about

• PSI validity or write-action assertions
• IndexNotReadyException
• editor/document synchronization
• UI refresh or EDT access errors
• fixture/test-data/debugging problems

Working principles

When solving IntelliJ Platform tasks:

1. Prefer official platform concepts over ad-hoc hacks.
2. Put reusable logic in services, not in actions.
3. Keep AnAction.update() extremely fast.
4. Respect threading and dumb mode before optimizing behavior.
5. Use PSI-aware approaches for structural code tasks.
6. Use platform UI components and conventions for user-facing surfaces.
7. Keep plugin dependencies and target IDE scope as small as practical.

High-value reminders

• AnAction implementations should not store request-specific state in fields.
• When targeting IntelliJ Platform 2022.3 or later, actions must implement getActionUpdateThread().
• PSI modifications must run on EDT inside a write action and command; coordinate document changes with the PSI/document APIs used by the platform.
• Not every feature is safe in dumb mode; do not mark things DumbAware casually.
• For Kotlin plugins targeting 2024.1+ or newer platform baselines, prefer coroutine-based read/write APIs when appropriate.
• Light services must be final; constructor injection of dependency services is unsupported, and services should not be looked up in constructors only to cache them in fields.
• Avoid internal APIs unless there is no viable public alternative and the tradeoff is explicit.

Typical response strategy

When a user asks for implementation help:

1. Determine the feature surface: action, service, PSI, UI, language support, test, or publishing.
2. Read the matching reference files.
3. Follow the closest official sample or extension-point pattern.
4. Implement the smallest correct solution that matches IntelliJ Platform rules.
5. If publishing or compatibility matters, also review verifier/signing/build-range concerns.

Reference map

• references/getting-started.md
• references/plugin-registration.md
• references/platform-basics.md
• references/split-mode-rpc.md
• references/workspace-model.md
• references/psi-and-indexing.md
• references/language-support-and-analysis.md
• references/ui-settings-and-toolwindows.md
• references/testing-and-publishing.md
• references/compatibility.md
• references/extension_points.md
• references/code_samples.md
• references/lsp.md
• references/mcp-and-ai-integration.md
• references/execution-and-run-configs.md
• references/webview-jcef.md
• references/templates.md
• references/themes.md
• references/icons.md
• references/patterns.md
• references/troubleshooting.md
• references/troubleshooting-build-runtime.md
• references/troubleshooting-psi-ui-testing.md