jetbrains-plugin-development

Files (121)

• SKILL.md
• README.md · examples/
• DynamicGreetingsGroup.kt · examples/action_basics/
• HelloAction.kt · examples/action_basics/
• plugin.xml · examples/action_basics/
• ExampleFoldingBuilder.kt · examples/folding_builder/
• plugin.xml · examples/folding_builder/
• ExampleInlineCompletionProvider.kt · examples/inline_completion_provider/
• plugin.xml · examples/inline_completion_provider/
• MyAppSettings.kt · examples/settings_persistence/
• MyConfigurable.kt · examples/settings_persistence/
• plugin.xml · examples/settings_persistence/
• Simple.bnf · examples/simple_language_plugin/
• Simple.flex · examples/simple_language_plugin/
• SimpleAnnotator.kt · examples/simple_language_plugin/
• SimpleColorSettingsPage.kt · examples/simple_language_plugin/
• SimpleCommenter.kt · examples/simple_language_plugin/
• SimpleCompletionContributor.kt · examples/simple_language_plugin/
• SimpleFile.kt · examples/simple_language_plugin/
• SimpleFileType.kt · examples/simple_language_plugin/
• SimpleLanguage.kt · examples/simple_language_plugin/
• SimpleParserDefinition.kt · examples/simple_language_plugin/
• SimpleSyntaxHighlighter.kt · examples/simple_language_plugin/
• plugin.xml · examples/simple_language_plugin/
• 00_public_api_baseline.md · references/
• 01_core_dependencies.md · references/
• 01_core_extension_diagnostics.md · references/
• 01_core_extensions.md · references/
• 01_core_gradle_project.md · references/
• 01_core_plugin_xml.md · references/
• 01_core_split_mode_remote_development.md · references/
• 02_runtime_actions.md · references/
• 02_runtime_deprecated_api_migrations.md · references/
• 02_runtime_legacy_component_migration.md · references/
• 02_runtime_listeners_message_bus.md · references/
• 02_runtime_services.md · references/
• 02_runtime_typed_handlers_editor_actions.md · references/
• 03_lifecycle_disposer.md · references/
• 03_lifecycle_leak_diagnostics.md · references/
• 04_threading_background_work_progress.md · references/
• 04_threading_coroutines_2024.md · references/
• 04_threading_diagnostics.md · references/
• 04_threading_model.md · references/
• 04_threading_read_write_actions.md · references/
• 04_threading_thread_to_coroutine_migration.md · references/
• 05_file_model_documents.md · references/
• 05_file_model_indexing_stubs.md · references/
• 05_file_model_psi_basics.md · references/
• 05_file_model_psi_diagnostics.md · references/
• 05_file_model_psi_references_caching.md · references/
• 05_file_model_uast.md · references/
• 05_file_model_vfs.md · references/
• 06_code_insight_diagnostics.md · references/
• 06_code_insight_documentation_target_api.md · references/
• 06_code_insight_editor_markup_lifecycle.md · references/
• 06_code_insight_editor_model.md · references/
• 06_code_insight_file_editor_provider.md · references/
• 06_code_insight_folding.md · references/
• 06_code_insight_formatter_commenter.md · references/
• 06_code_insight_inspection_options_suppression.md · references/
• …and 61 more

SKILL.md (first lines)

# JetBrains IDE Plugin Development (IntelliJ Platform SDK)

This skill carries the IntelliJ Platform SDK domain knowledge needed to write, debug, and modify
JetBrains IDE plugins using only APIs supported for external plugins. The source baseline is
IntelliJ Community tag `idea/2026.2.2`, commit `1c7e601c0423e544917046c23763b15d0282e2a3`.
Guidance for 2024.1+ remains version-conditioned; this source baseline does not raise a
plugin's minimum supported IDE version automatically.

## How to use this skill

1. Establish the target IDE product/build, minimum supported version, IntelliJ Platform
   Gradle Plugin version, and Java/Kotlin toolchain from the project. Read the **Public API
   boundary** and **mental model** below before selecting APIs.
2. Pick the reference file from the **Capability index** that matches the task and read it before editing.
3. For end-to-end shapes — how the registrations, classes, and `plugin.xml` of a feature line up — open the matching folder under `examples/`.
4. Before declaring any plugin-modifying task done, walk the **Pre-flight checklist**.

Do not invent extension point names, attribute names, or API signatures. The Platform is highly
specific about strings (`language="JAVA"` vs `"java"`, EP IDs, attribute spellings); a wrong
character is enough to silently disable a feature. When unsure, surface the question to the user
with the relevant reference cited — and verify the spelling in the IDE's `plugin.xml` editor,
which auto-completes valid EP names from the loaded plugin set and underlines unknown ones.

## Public API boundary

This rule applies to every reference, example, API call, base type, implementation, and EP
registration in this package. Use only APIs supported for external plugins. Java/Kotlin
`public` visibility alone does not establish that support.

- Reject `private`, `@ApiStatus.Internal`, `@IntellijInternalApi`, internal EPs, and
  implementation classes not intended for external use. Inspect the exact member, containing
  types, supertypes, package annotations, module visibility, documentation, and EP declaration metadata in the
  target version. Respect `NonExtendable` and `OverrideOnly` contracts as well.
- Never bypass this boundary with reflection, accessibility overrides, internal casts,
  copied internal implementations, or suppressed inspections. Risk acceptance is not an exception.
- Internal source is evidence for understanding behavior only. If no supported API can
  implement the requested feature, explain the limitation and offer the nearest public API
  alternative; do not fabricate an equivalent capability.
- Evaluate external availability and stability separately. An `Experimental` API is eligible
  only after external use is confirmed; state its applicable versions and instability and
  prefer a stable public alternative. Neither a missing annotation nor successful compilation
  proves that an API is supported or stable.
- For changed API guidance, record the source tag, commit, source links, public-status evidence,
  and applicable versions. Check the minimum version separately from the baseline. If status
  remains unverified, keep that candidate out of recommended examples.

Read [00_public_api_baseline.md](references/00_public_api_baseline.md) for the pinned evidence
and version boundaries. IDE completion and Plugin Verifier supplement this review; neither
grants permission to use an internal API.

## Mental model — five invariants you must hold

These five invariants explain almost every "why doesn't this work?" question.

1. **`plugin.xml` is the contract.** A class is invisible to the IDE until it is registered.
   `@Service`, `@Service(cs)` annotations and a few `META-INF/` filename conventions are the
   only exceptions; everything else (extensions, listeners, actions, EPs you define, dependencies)
   must appear in `plugin.xml` (or a `config-file` of an `<depends optional>` block).
2. **Extensions are stateless; services hold state.** EP implementations are constructed once
   per scope and shared across all calls and threads. Storing mutable state on an extension
   leaks across projects, threads, and dynamic reloads. Put state in a service
   (`@Service` / `@Service(Service.Level.PROJECT)`), and have extensions look it up on demand.
3. **Threading is non-negotiable.** Reading platform model state (PSI, VFS, Document, project model)
   needs the API's documented read access. Writing needs the documented write context;
   dispatcher and suspending write behavior depend on the target version (see `04_threading_model.md`). Long work belongs on a background thread
   with progress and cancellation. EDT freezes are user-visible; lock violations are immediate
   exceptions or data corruption. New code on 2024.1+ uses Kotlin coroutines
   (`cs.launch { }`, `readAction { }`, and the target-version dispatcher and write API).
4. **`Disposer` is how lifecycle works.** Resources tie into a `Disposable` parent and the
   platform calls `dispose()` post-order when the parent goes away. Services are usually the
   right parent. Never use `Application` or `Project` directly as a parent — that traps
   resources past plugin unload and leaks the classloader. `CoroutineScope` injection on a
   `@Service` is the modern alternative to `Disposable`.
5. **Dynamic plugin reload imposes hard constraints.** The default since 2020.1 is
   `require-restart="false"`. To stay reloadable: every EP your plugin contributes to and
   defines must be dynamic, no static caches of plugin classes, no `object` singletons holding
   state, no listeners parented to `Application`/`Project`, no `overrides="true"` services.

## Capability index

Use this section as a router. Do not bulk-read every reference. Start with the single most specific reference below, then add companion references only when the task crosses that boundary.

Reference filenames are prefixed by category for fast scanning: `01_core`, `02_runtime`,
`03_lifecycle`, `04_threading`, `05_file_model`, `06_code_insight`, `07_language`,
`08_ui`, `09_project`, `10_execution`, and `11_distribution`.

- [01_core_gradle_project.md](references/01_core_gradle_project.md): Project setup, IntelliJ Platform Gradle Plugin 2.x, sandbox IDE, generated helper tasks, multi-module project shape.
- [01_core_plugin_xml.md](references/01_core_plugin_xml.md): `plugin.xml`, required descriptor elements, file naming conventions, and descriptor blocks for listeners/actions.
- [01_core_dependencies.md](references/01_core_dependencies.md): `<depends>`, optional dependency config files, `sinceBuild`, `untilBuild`, and platform branch targeting.
- [01_core_extensions.md](references/01_core_extensions.md): Using, ordering, iterating, defining, or discovering extension points.
- [01_core_extension_diagnostics.md](references/01_core_extension_diagnostics.md): Plugin loading lifecycle and diagnosing extensions that are registered but ignored.
- [01_core_split_mode_remote_development.md](references/01_core_split_mode_remote_development.md): Split Mode, Remote Development, frontend/backend/shared modules, RPC boundaries, and split sandbox runs.
- [02_runtime_services.md](references/02_runtime_services.md): Light services, constructor rules, state holders, service-scoped `CoroutineScope`, and persistent-state handoff.
- [02_runtime_listeners_message_bus.md](references/02_runtime_listeners_message_bus.md): Declarative listeners, `MessageBus`, `Topic`, manual subscriptions, and listener lifetime.
- [02_runtime_actions.md](references/02_runtime_actions.md): `AnAction`, `update`, `ActionUpdateThread`, action groups, keymaps, and action skeletons.
- [02_runtime_typed_handlers_editor_actions.md](references/02_runtime_typed_handlers_editor_actions.md): `TypedHandlerDelegate`, `EditorActionHandler`, typing interception, autopopup routing, and multi-caret editor actions.
- [02_runtime_legacy_component_migration.md](references/02_runtime_legacy_component_migration.md): Migrating `ApplicationComponent`, `ProjectComponent`, or `ModuleComponent` to services, extensions, listeners, and startup activities.
- [02_runtime_deprecated_api_migrations.md](references/02_runtime_deprecated_api_migrations.md): Deprecated listener, coroutine-scope, action, and Plugin DevKit migration checks.
- [03_lifecycle_disposer.md](references/03_lifecycle_disposer.md): `Disposable` trees, safe parent selection, cleanup patterns, `Alarm`, and disposal triggers.
- [03_lifecycle_leak_diagnostics.md](references/03_lifecycle_leak_diagnostics.md): Disposer leak debugging, sandbox and heap checks, and leak-prone patterns without internal test APIs.
- [04_threading_model.md](references/04_threading_model.md): EDT/BGT mental model, lock rules, dumb mode overview, and threading invariants.
- [04_threading_read_write_actions.md](references/04_threading_read_write_actions.md): Classic read/write actions, `ReadAction.nonBlocking`, `WriteCommandAction`, `invokeLater`, modality, and annotations.
- [04_threading_background_work_progress.md](references/04_threading_background_work_progress.md): `Task.Backgroundable`, progress indicators, cancellation, synchronous progress, and fire-and-forget work.
- [04_threading_coroutines_2024.md](references/04_threading_coroutines_2024.md): 2024.1+ coroutine APIs, `Dispatchers.EDT`, suspending read/write actions, progress, and `runBlockingCancellable`.
- [04_threading_thread_to_coroutine_migration.md](references/04_threading_thread_to_coroutine_migration.md): Replacing `Thread`, `ExecutorService`, and `Task.Backgroundable` with coroutine-based code.
- [04_threading_diagnostics.md](references/04_threading_diagnostics.md): Threading symptoms, common mistakes, best practices, and import map for suspending APIs.
- [05_file_model_vfs.md](references/05_file_model_vfs.md): `VirtualFile`, file lookup, refresh, listeners, VFS lifecycle, and identity.
- [05_file_model_documents.md](references/05_file_model_documents.md): `Document`, document lookup, reads, writes, synchronization with PSI, listeners, and guarded ranges.
- [05_file_model_psi_basics.md](references/05_file_model_psi_basics.md): `PsiElement`, PSI lookup, tree walking, modifications, whitespace, and formatting.
- [05_file_model_psi_references_caching.md](references/05_file_model_psi_references_caching.md): `SmartPsiElementPointer`, `PsiReference`, named elements, multi-language files, and `CachedValue`.
- [05_file_model_uast.md](references/05_file_model_uast.md): UAST for cross-JVM-language analysis (one inspection/line marker covering Java, Kotlin, Scala, Groovy), `UElement`/`UMethod`/`UCallExpression`, `sourcePsi` vs `javaPsi`, `AbstractBaseUastLocalInspectionTool`, and `UastHintedVisitorAdapter`.
- [05_file_model_indexing_stubs.md](references/05_file_model_indexing_stubs.md): Dumb Mode, smart mode, `FileBasedIndex`, stub indexes, and `AstLoadingFilter`.
- [05_file_model_psi_diagnostics.md](references/05_file_model_psi_diagnostics.md): Common VFS, Document, PSI, index, and cache failure modes.
- [06_code_insight_editor_model.md](references/06_code_insight_editor_model.md): `Editor`, caret, selection, multi-caret behavior, and editor coordinate systems.
- [06_code_insight_editor_markup_lifecycle.md](references/06_code_insight_editor_markup_lifecycle.md): `RangeMarker`, `MarkupModel`, `RangeHighlighter`, scrolling, editor lifecycle, console filters, and guarded blocks.
- [06_code_insight_file_editor_provider.md](references/06_code_insight_file_editor_provider.md): `FileEditorProvider`, custom editor tabs, preview editors, fake files, and editor disposal.
- [06_code_insight_line_markers.md](references/06_code_insight_line_markers.md): `LineMarkerProvider`, gutter icons, leaf-element rules, slow markers, and Dumb Mode behavior.
- [06_code_insight_folding.md](references/06_code_insight_folding.md): `FoldingBuilder`, descriptors, callbacks, custom folding settings, non-owned languages, and missing-fold diagnostics.
- [06_code_insight_formatter_commenter.md](references/06_code_insight_formatter_commenter.md): `FormattingModelBuilder` + `Block` (indent/wrap/`SpacingBuilder`/`getChildAttributes`) for `Ctrl+Alt+L`, and `Commenter` for `Ctrl+/` line/block comment toggles.

From buYoung/skills, MIT.

More from buYoung/skills