Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

minecraft-plugin-dev

Create, modify, and debug server plugins for current Paper 26.x on Java 25 or legacy Bukkit-derived 1.21.x servers on Java 21. Use for JavaPlugin APIs, events, commands, schedulers, configuration, PDC, and Adventure, not client mods or vanilla datapacks.

Jahrome907 · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add Jahrome907/minecraft-agent-skills --skill minecraft-plugin-dev

About this skill


name: minecraft-plugin-dev description: "Create, modify, and debug server plugins for current Paper 26.x on Java 25 or legacy Bukkit-derived 1.21.x servers on Java 21. Use for JavaPlugin APIs, events, commands, schedulers, configuration, PDC, and Adventure, not client mods or vanilla datapacks."

Minecraft Plugin Development Skill

Platform Overview

PlatformBase APINotes
PaperBukkit/Spigot + Paper extensionsRecommended; async chunk loading, Adventure native
SpigotBukkit + Spigot extensionsLegacy; fewer APIs, slower
BukkitBase API onlyAvoid for new plugins
FoliaPaper forkRegion-threaded; requires special scheduler APIs

Paper is the recommended target. Paper includes all Bukkit and Spigot APIs plus significant performance improvements and additional APIs.

Routing Boundaries

  • Use when: the target is server-side Paper/Bukkit/Spigot plugin behavior with JavaPlugin APIs.
  • Do not use when: the task requires client-side installable mods or loader APIs (minecraft-modding / minecraft-multiloader).
  • Do not use when: the task is pure vanilla datapack/command content (minecraft-datapack / minecraft-commands-scripting).

Bundled References

  • Read references/runtime-patterns.md when the task touches scheduling, Folia support, PDC, Adventure/MiniMessage, YAML config, Vault, or Paper-specific APIs.
  • Read references/paper-plugin-commands.md for a Paper-only paper-plugin.yml project or Brigadier command registration.

Project Setup

The examples below target current Paper 26.2 and Java 25. For an existing 1.21.x plugin, preserve its 1.21.x-R0.1-SNAPSHOT dependency, Java 21 toolchain, and matching api-version until the project is intentionally ported.

settings.gradle.kts

rootProject.name = "my-plugin"

build.gradle.kts

plugins {
    java
}

group = "com.example"
version = "1.0.0-SNAPSHOT"

repositories {
    mavenCentral()
    maven("https://repo.papermc.io/repository/maven-public/")
}

dependencies {
    compileOnly("io.papermc.paper:paper-api:26.2.build.+")
}

java {
    toolchain.languageVersion.set(JavaLanguageVersion.of(25))
}

tasks {
    processResources {
        // Substitutes ${version} in plugin.yml with the Gradle project version
        filesMatching(listOf("plugin.yml", "paper-plugin.yml")) {
            expand("version" to project.version)
        }
    }
}

Add Shadow only when the plugin has runtime libraries that must be bundled and relocated. Paper and optional plugin APIs such as Vault remain compileOnly and must not be shaded into the plugin JAR.

gradle/wrapper/gradle-wrapper.properties

distributionUrl=https\://services.gradle.org/distributions/gradle-9.1.0-bin.zip

Gradle 8.8 cannot run on Java 25. Use Gradle 9.1 or newer for a current Java 25 project. Preserve the existing wrapper and Java 21 toolchain for a legacy 1.21.x project unless its build is intentionally upgraded and verified.


Project Layout

my-plugin/
├── build.gradle.kts
├── settings.gradle.kts
├── gradle/
│   └── wrapper/
│       └── gradle-wrapper.properties
└── src/main/
    ├── java/com/example/myplugin/
    │   ├── MyPlugin.java          ← main class (extends JavaPlugin)
    │   ├── listeners/
    │   │   └── PlayerListener.java
    │   ├── commands/
    │   │   └── MyCommand.java
    │   └── managers/
    │       └── DataManager.java
    └── resources/
        ├── plugin.yml            ← Bukkit-compatible descriptor
        ├── paper-plugin.yml      ← active descriptor for a Paper plugin
        └── config.yml

Core Files

plugin.yml (Bukkit-compatible default)

name: MyPlugin
version: "${version}"
main: com.example.myplugin.MyPlugin
description: An example Paper plugin
author: YourName
website: https://github.com/example/my-plugin
api-version: '26.2'

commands:
  myplugin:
    description: Main plugin command
    usage: /myplugin <subcommand>
    permission: myplugin.use
    aliases: [mp]

permissions:
  myplugin.use:
    description: Allows use of /myplugin
    default: true
  myplugin.admin:
    description: Admin access
    default: op

Match api-version to the oldest Paper API the plugin intentionally supports. Current Paper examples use 26.2; legacy 1.21 and positive 1.21.<patch> values remain valid for older servers. A server older than the declared value refuses to load the plugin.

paper-plugin.yml (experimental Paper-only format)

Prefer plugin.yml for Bukkit-compatible plugins. Use paper-plugin.yml only when the JAR is intentionally Paper-only and needs Paper-plugin behavior such as bootstrapping, loaders, or classloading isolation. It can be the only descriptor, but is not a drop-in replacement: Paper plugins do not use a commands field or getCommand(...) registration. Read references/paper-plugin-commands.md for the paired descriptor, main class, and Brigadier lifecycle registration.

When one JAR ships both descriptors, keep their shared metadata and main class aligned. Do not combine the Paper-only sample with the Bukkit-compatible MyPlugin sample below.

Bukkit-compatible main class

package com.example.myplugin;

import com.example.myplugin.commands.MyCommand;
import com.example.myplugin.listeners.PlayerListener;
import org.bukkit.plugin.java.JavaPlugin;

public final class MyPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        saveDefaultConfig();

        // Register listeners
        getServer().getPluginManager().registerEvents(new PlayerListener(), this);

        // Register commands
        var cmd = getCommand("myplugin");
        if (cmd == null) {
            throw new IllegalStateException("myplugin command is missing from plugin.yml");
        }
        var handler = new MyCommand(this);
        cmd.setExecutor(ha
Read the complete source ↗