IntelliJ IDEA Plugin Development

This Skill provides guidance for developing IntelliJ IDEA plugins using standardized templates. It covers two types of plugins: standard plugins (without AI) and AI-integrated plugins (with IntelliAI Engine).

When to Use This Skill

Use this Skill when:

• Creating a new IntelliJ IDEA plugin project
• Setting up plugin structure and configuration
• Implementing actions, settings pages, or UI components
• Integrating AI capabilities via IntelliAI Engine
• Following best practices for IntelliJ plugin development
• Working with plugin templates (

  template-without-ai

  or

  template-with-ai

  )

Plugin Types

1. Standard Plugin (template-without-ai)

Use for: Plugins that don't require AI functionality.

Features:

• Simplified Action (right-click menu)
• Icon management class
• Notification utilities
• Internationalization support
• Basic project structure

Key Components:

• ExampleAction

  - Single action example

• ExampleIcons

  - Icon management

• NotificationUtil

  - Notification helper

• ExampleBundle

  - Internationalization

2. AI-Integrated Plugin (template-with-ai)

Use for: Plugins that need AI capabilities via IntelliAI Engine.

Additional Features:

• AI provider selection in settings
• Prompt template management
• Settings page with advanced options
• Integration with IntelliAI Engine

Key Components:

• All standard plugin components

• SettingsState

  - Persistent configuration

• ExampleSettingsConfigurable

  - Settings UI

• ExampleSettingsPanel

  - Settings panel with AI provider dropdown and prompt templates

Project Structure

Standard Plugin Structure

template-without-ai/
├── src/main/java/dev/dong4j/zeka/stack/idea/plugin/example/
│   ├── action/          # Actions
│   ├── icons/           # Icon management
│   └── util/            # Utilities (Bundle, Notification)
├── src/main/resources/
│   ├── icons/           # Icon resources (SVG)
│   ├── META-INF/
│   │   └── plugin.xml   # Plugin configuration
│   └── messages*.properties  # Internationalization
├── includes/            # Plugin description and changelog
├── docs/                # User manual
├── build.gradle.kts     # Build configuration
└── gradle.properties    # Plugin properties

AI-Integrated Plugin Structure

template-with-ai/
├── src/main/java/dev/dong4j/zeka/stack/idea/plugin/example/
│   ├── action/          # Actions
│   ├── icons/           # Icon management
│   ├── settings/        # Settings (State, Configurable, Panel)
│   └── util/            # Utilities
├── ... (same as standard)
└── build.gradle.kts     # Includes AI Engine dependencies

Development Steps

Step 1: Choose Template Type

For standard plugins:

• Use

  template-without-ai

  as base
• No AI Engine dependencies needed
• Simpler configuration

For AI-integrated plugins:

• Use

  template-with-ai

  as base
• Requires IntelliAI Engine plugin
• Includes settings page and AI provider management

Step 2: Configure Project

1. Update

   gradle.properties

   :

   pluginGroup=dev.dong4j.zeka.stack
   pluginName=Your Plugin Name
   pluginVersion=2025.3.1
   kitVersion=2025.3.1
   rootProjectName=your-plugin-name
   

2. Update

   plugin.xml

   :
   • Change plugin ID
   • Update plugin name
   • Register your actions and services

3. Update package names:

   • Replace

     dev.dong4j.zeka.stack.idea.plugin.example

     with your package
   • Update all Java files
   • Update

     plugin.xml

     references

Step 3: Implement Actions

Standard Action Pattern:

public class ExampleAction extends AnAction {
    public ExampleAction() {
        super(
            ExampleBundle.message("action.example.title"),
            ExampleBundle.message("action.example.description"),
            ExampleIcons.EXAMPLE_16
        );
    }

    @Override
    public void actionPerformed(@NotNull AnActionEvent e) {
        Project project = e.getProject();
        PsiFile psiFile = e.getData(CommonDataKeys.PSI_FILE);

        if (project == null || psiFile == null) {
            NotificationUtil.showError(project, ExampleBundle.message("error.no.file"));
            return;
        }

        // Your action logic here
        NotificationUtil.showInfo(project, "Action executed");
    }
}

Register in

plugin.xml

:

<action id="your.package.action.ExampleAction"
        class="your.package.action.ExampleAction">
    <add-to-group group-id="EditorPopupMenu" anchor="last"/>
</action>

Step 4: Icon Management

Create Icon Class:

public class ExampleIcons {
    @NotNull
    private static Icon load(@NotNull String iconPath) {
        return IconLoader.getIcon(iconPath, ExampleIcons.class);
    }

    public static final Icon EXAMPLE_16 = load("/icons/example_16.svg");
}

Add Icon Resources:

• Place SVG files in

  src/main/resources/icons/

• Use 16x16 for actions, 24x24 for notifications, 32x32 for dialogs

Step 5: Internationalization

Add Messages:

messages.properties

(English):

action.example.title=Example Action
action.example.description=Execute example action
error.no.file=No file found

messages_zh_CN.properties

(Chinese):

action.example.title=示例操作
action.example.description=执行示例操作
error.no.file=未找到文件

Use in Code:

String message = ExampleBundle.message("action.example.title");

Step 6: Settings Page (AI-Integrated Only)

Create SettingsState:

@State(
    name = "ExamplePluginSettings",
    storages = @Storage("example-settings.xml")
)
public class SettingsState implements PersistentStateComponent<SettingsState> {
    public AIProviderConfig providerConfig;
    public boolean showAdvancedSettings = false;
    public String systemPrompt = getDefaultSystemPrompt();
    public String exampleTemplate = getDefaultExampleTemplate();

    public static SettingsState getInstance() {
        return ApplicationManager.getApplication().getService(SettingsState.class);
    }
}

Create Settings Panel:

public class ExampleSettingsPanel {
    private JComboBox<AIProviderConfig> providerComboBox;
    private JBTextArea systemPromptTextArea;

    // Create AI provider selection panel
    private JPanel createAIProviderSelectionPanel() {
        List<AIProviderConfig> providers = getAiProviderTypes();
        // Build UI with FormBuilder
    }
}

Register in

plugin.xml

:

<applicationService serviceImplementation="your.package.settings.SettingsState"/>
<applicationConfigurable
    parentId="tools"
    instance="your.package.settings.ExampleSettingsConfigurable"
    id="your.package.settings.ExampleSettingsConfigurable"
    displayName="Your Plugin"/>

Step 7: Build Configuration

Standard Plugin (

build.gradle.kts

):

dependencies {
    intellijPlatform {
        create(providers.gradleProperty("platformType"),
               providers.gradleProperty("platformVersion"))
        bundledPlugin("com.intellij.java")
        // No AI Engine dependency
    }
}

AI-Integrated Plugin (

build.gradle.kts

):

dependencies {
    intellijPlatform {
        // ... same as standard
        // plugin("dev.dong4j.zeka.stack.idea.plugin.common.ai")  // Uncomment for marketplace
    }
    compileOnly("dev.dong4j.zeka.stack:intelli-ai-engine:1.1.0")
}

tasks {
    // Add buildAiCommonPlugin and copyAiCommonPlugin tasks
    // for local development
}

Step 8: Testing

1. Build plugin:

   ./gradlew buildPlugin
   

2. Run in sandbox:

   ./gradlew runIde
   

3. Verify:

   • Action appears in right-click menu
   • Settings page loads (AI-integrated)
   • Notifications work
   • Internationalization works

Best Practices

Code Organization

1. Package Structure:

   • action/

     - User actions

   • icons/

     - Icon management

   • settings/

     - Settings (AI-integrated only)

   • util/

     - Utilities (Bundle, Notification)

2. Naming Conventions:

   • Actions:

     *Action.java

   • Settings:

     *SettingsState.java

     ,

     *SettingsConfigurable.java

     ,

     *SettingsPanel.java

   • Icons:

     *Icons.java

   • Bundles:

     *Bundle.java

UI Components

1. Use IntelliJ UI Components:

   • JBLabel

     ,

     JBTextField

     ,

     JBCheckBox

     (not JLabel, JTextField)

   • FormBuilder

     for layouts

   • ToolbarDecorator

     for tables

   • JBTable

     for data tables

2. Settings Page:

   • Use

     FormBuilder

     for consistent layout
   • Add emojis to labels for better UX (🤖, ⚙️, 📝, etc.)
   • Support collapsible advanced settings
   • Use

     JBTabbedPane

     for multiple prompt templates

Internationalization

1. Always use Bundle:

   • Never hardcode strings
   • Use

     ExampleBundle.message(key, params...)

   • Provide both English and Chinese

2. Key Naming:

   • action.*

     - Action labels

   • settings.*

     - Settings labels

   • error.*

     - Error messages

   • success.*

     - Success messages

Configuration

1. Persistent State:

   • Use

     @State

     annotation
   • Implement

     PersistentStateComponent

   • Initialize collections to avoid null

2. Settings UI:

   • Implement

     Configurable

     or

     SearchableConfigurable

   • Check

     isModified()

     before save
   • Reset UI in

     reset()

     method

Common Patterns

Notification Pattern

// Success
NotificationUtil.showInfo(project, ExampleBundle.message("success.action.executed"));

// Error
NotificationUtil.showError(project, ExampleBundle.message("error.no.file"));

// Warning
NotificationUtil.showWarning(project, ExampleBundle.message("warning.message"));

Action Update Pattern

@Override
public void update(@NotNull AnActionEvent e) {
    Project project = e.getProject();
    PsiFile file = e.getData(CommonDataKeys.PSI_FILE);
    e.getPresentation().setEnabled(project != null && file != null);
}

Settings Validation Pattern

@Override
public void apply() throws ConfigurationException {
    if (!validateSettings()) {
        throw new ConfigurationException("Invalid settings");
    }
    settingsPanel.apply(settings);
}

Differences: Standard vs AI-Integrated

Feature	Standard Plugin	AI-Integrated Plugin
AI Engine Dependency	❌ No	✅ Yes (compileOnly)
Settings Page	❌ No	✅ Yes
AI Provider Selection	❌ No	✅ Yes
Prompt Templates	❌ No	✅ Yes
Build Tasks	Basic	+ buildAiCommonPlugin, copyAiCommonPlugin
plugin.xml	Actions only	+ SettingsState, SettingsConfigurable

Troubleshooting

Plugin doesn't load

• Check

  plugin.xml

  syntax
• Verify package names match
• Check for missing dependencies

Settings not persisting

• Verify

  @State

  annotation
• Check

  getState()

  and

  loadState()

  methods
• Ensure fields are

  public

AI provider not available

• Check IntelliAI Engine plugin is installed
• Verify provider is configured and tested
• Check

  AIProviderSettings.getInstance().getVerifiedProviders()

Icons not showing

• Verify icon path starts with

  /icons/

• Check SVG file exists in resources
• Ensure

  IconLoader.getIcon()

  path is correct

References

• Template projects:

  template-without-ai/

  and

  template-with-ai/

• IntelliJ Platform SDK: https://plugins.jetbrains.com/docs/intellij/
• IntelliAI Engine: See

  intelli-ai-engine/

  project
• Example implementations:

  intelli-ai-changelog/

  ,

  intelli-ai-javadoc/

Examples

Creating a Standard Plugin

1. Copy

   template-without-ai

   to your project
2. Update

   gradle.properties

   with your plugin info
3. Rename package from

   example

   to your package
4. Implement your action in

   action/

   package
5. Add icons and internationalization
6. Build and test

Creating an AI-Integrated Plugin

1. Copy

   template-with-ai

   to your project
2. Follow standard plugin steps
3. Configure AI provider in settings
4. Implement prompt templates
5. Use

   AIService.getInstance()

   to call AI
6. Build and test (ensure IntelliAI Engine is available)