# Intellij Platform Sdk > IntelliJ Platform plugin development with the v2 SDK / IntelliJ Platform Gradle Plugin 2.x. Trigger for plugin code in JetBrains IDEs involving plugin.xml, org.jetbrains.intellij.platform, AnAction, PSI, extension points, Inspection/CompletionContributor, ParserDefinition, ToolWindowFactory, PersistentStateComponent, plugin verifier, Marketplace publishing, custom language support, Gradle plugin 2.x setup/migration, ConfigurationType, live templates/postfix completion, IconLoader/AllIcons, IDE theme, LSP/MCP integration, //, dynamic plugin requirements, JCEF/JBCefBrowser/JBCefJSQuery/webview, or pluginIcon. Do not trigger for general JetBrains IDE usage, ordinary run configurations, generic Gradle/logging, or language-server discussions outside plugin-dev context. - Skill: `gadfly3173/intellij-platform-sdk` (Agent Skill, multi-file: 24 files) - Install (CLI): `npx skillmds@latest add gadfly3173/intellij-platform-sdk` - Raw SKILL.md: https://api.skillmd.com/api/skills/gadfly3173/intellij-platform-sdk/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: gadfly3173 (https://skillmd.com/u/gadfly3173) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/gadfly3173/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 `` 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 - `` root attributes (`url`, `require-restart`) - metadata elements (``, ``, ``, ``, ``, ``) - `` since/until/strict-until-build and the Gradle `pluginConfiguration` relationship - `` required vs optional, `config-file` merge semantics, additional descriptor naming, `` - declarative listeners (`` / `` `` attributes) - `` full sub-elements (``, ``, ``, ``, ``, ``, ``) - `` `qualifiedName`/`area`/`` and `` `id`/`order`/`os` basic attributes - ``, ``, 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()`, `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`