К основному содержанию
скилл CX Codex

minecraft-plugin-dev — скилл для Claude Code

Скилл minecraft-plugin-dev помогает создавать, менять и отлаживать серверные плагины для Paper и Bukkit-производных серверов. Пригодится при работе с JavaPlugin, событиями и командами.

MIT 267 установок ★ 211 обновлён 2026-10-30

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add Jahrome907/minecraft-agent-skills --skill minecraft-plugin-dev -a claude-code
Открыть на GitHub

Что делает minecraft-plugin-dev

Скилл ориентирован на серверные плагины Minecraft: работу с JavaPlugin API, событиями, командами, планировщиками, конфигурацией, PDC и Adventure. Он описывает структуру проекта и настройку Gradle, а также регистрацию обработчиков событий и команд. Для задач по планированию, Folia, YAML или Paper API предусмотрены справочные файлы.

Для актуального Paper примеры рассчитаны на Java 25 и Paper 26.3; для существующих серверов 1.21.x нужно сохранять Java 21 и соответствующую зависимость до переноса проекта. Gradle 8.8 не запускается на Java 25, поэтому для такой сборки нужен Gradle 9.1 или новее. Скилл не предназначен для клиентских модов и ванильных датапаков.

Какие задачи решает

  • создать структуру серверного плагина Minecraft на Java
  • настроить Gradle и дескриптор plugin.yml
  • зарегистрировать обработчики событий и команды
  • разобраться с планировщиками, PDC и Adventure
  • отладить плагин для Paper или Bukkit-производного сервера

Примеры запросов агенту

  • Создай серверный плагин для Paper 26.3 с командой /myplugin и обработчиком входа игрока.
  • Проверь мой плагин для сервера 1.21.x и сохрани настройки Java 21.
  • Разбери, как перенести обработку задачи на планировщик Folia.

Как установить minecraft-plugin-dev

1Через Skills CLI (Vercel)

npx skills add Jahrome907/minecraft-agent-skills --skill minecraft-plugin-dev -a claude-code

2Вручную: положить файлы

~/.claude/skills/minecraft-plugin-dev/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/minecraft-plugin-dev/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о minecraft-plugin-dev

Как установить minecraft-plugin-dev в Claude Code?

Выполни npx skills add Jahrome907/minecraft-agent-skills --skill minecraft-plugin-dev -a claude-code. Файл скилла будет доступен по пути ~/.claude/skills/minecraft-plugin-dev/SKILL.md.

Что делает minecraft-plugin-dev?

Скилл помогает создавать, менять и отлаживать серверные плагины Minecraft. Он охватывает JavaPlugin API, события, команды, конфигурацию и другие серверные механики.

Какие версии Java нужны для Paper и серверов 1.21.x?

Для примеров с Paper 26.3 используется Java 25. Для существующего проекта на сервере 1.21.x следует сохранить Java 21 до намеренного переноса.

Исходный текст

SKILL.md · MIT
---
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

| Platform | Base API | Notes |
|----------|----------|-------|
| **Paper** | Bukkit/Spigot + Paper extensions | Recommended; async chunk loading, Adventure native |
| **Spigot** | Bukkit + Spigot extensions | Legacy; fewer APIs, slower |
| **Bukkit** | Base API only | Avoid for new plugins |
| **Folia** | Paper fork | Region-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.3 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`
```kotlin
rootProject.name = "my-plugin"
```

### `build.gradle.kts`
```kotlin
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.3.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`
```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)
```yaml
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.3'

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.3`; 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`](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
```java
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(handler);
        cmd.setTabCompleter(handler);

        getLogger().info("MyPlugin enabled!");
    }

    @Override
    public void onDisable() {
        getLogger().info("MyPlugin disabled.");
    }

}
```

---

## Event Listeners

```java
package com.example.myplugin.listeners;

import net.kyori.adventure.text.Component;
import net.kyori.adventure.text.format.NamedTextColor;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.Listener;
import org.bukkit.event.entity.PlayerDeathEvent;
import org.bukkit.event.player.PlayerJoinEvent;
import org.bukkit.event.player.PlayerQuitEvent;

public class PlayerListener implements Listener {

    @EventHandler(priority = EventPriority.NORMAL)
    public void onPlayerJoin(PlayerJoinEvent event) {
        event.joinMessage(
            Component.text(event.getPlayer().getName() + " joined!", NamedTextColor.GREEN)
        );
    }

    @EventHandler
    public void onPlayerQuit(PlayerQuitEvent event) {
        event.quitMessage(
            Component.text(event.getPlayer().getName() + " left.", NamedTextColor.YELLOW)
        );
    }

    @EventHandler
    public void onPlayerDeath(PlayerDeathEvent event) {
        // Modify death message using Adventure components
        event.deathMessage(
            Component.text("☠ ", NamedTextColor.RED)
                .append(Component.text(event.getPlayer().getName(), NamedTextColor.WHITE))
                .append(Component.text(" died!", NamedTextColor.RED))
        );
    }
}
```

### EventPriority order
`LOWEST → LOW → NORMAL → HIGH → HIGHEST → MONITOR`  
Use `MONITOR` for logging only (never modify outcome). On events that implement
`Cancellable`, use `ignoreCancelled = true` unless you need cancelled events.

### Cancellable events
```java
@EventHandler
public void onBlockBreak(BlockBreakEvent event) {
    if (event.getPlayer().hasPermission("myplugin.break.deny")) {
        event.setCancelled(true);
        event.getPlayer().sendMessage(Component.text("You cannot break blocks!", NamedTextColor.RED));
    }
}
```

---

## Commands

This section is for the `plugin.yml` path above. Its declared command enables
`getCommand("myplugin")`. For a Paper-only descriptor, use the Brigadier
lifecycle example in [`references/paper-plugin-commands.md`](references/paper-plugin-commands.md).

```java
package com.example.myplugin.commands;

import com.example.myplugin.MyPlugin;
import net.kyori.adventure.text.Component;
import net.kyori.adventure.text.format.NamedTextColor;
import org.bukkit.command.Command;
import org.bukkit.command.CommandExecutor;
import org.bukkit.command.CommandSender;
import org.bukkit.command.TabCompleter;
import org.bukkit.entity.Player;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

import java.util.List;
import java.util.Locale;

public class MyCommand implements CommandExecutor, TabCompleter {

    private final MyPlugin plugin;

    public MyCommand(MyPlugin plugin) {
        this.plugin = plugin;
    }

    @Override
    public boolean onCommand(@NotNull CommandSender sender, @NotNull Command command,
                             @NotNull String label, @NotNull String[] args) {
        if (!(sender instanceof Player player)) {
            sender.sendMessage(Component.text("Only players can use this command.", NamedTextColor.RED));
            return true;
        }

        if (!player.hasPermission("myplugin.use")) {
            player.sendMessage(Component.text("No permission.", NamedTextColor.RED));
            return true;
        }

        if (args.length == 0) {
            player.sendMessage(Component.text("Usage: /myplugin <reload|info>", NamedTextColor.YELLOW));
            return true;
        }

        return switch (args[0].toLowerCase(Locale.ROOT)) {
            case "reload" -> {
                if (!player.hasPermission("myplugin.admin")) {
                    player.sendMessage(Component.text("No permission.", NamedTextColor.RED));
                    yield true;
                }
                plugin.reloadConfig();
                player.sendMessage(Component.text("Config reloaded.", NamedTextColor.GREEN));
                yield true;
            }
            case "info" -> {
                player.sendMessage(Component.text("Version: " + plugin.getDescription().getVersion(), NamedTextColor.AQUA));
                yield true;
            }
            default -> {
                player.sendMessage(Component.text("Unknown subcommand.", NamedTextColor.RED));
                yield true;
            }
        };
    }

    @Override
    public @Nullable List<String> onTabComplete(@NotNull CommandSender sender, @NotNull Command command,
                                                @NotNull String label, @NotNull String[] args) {
        if (!sender.hasPermission("myplugin.use")) return List.of();
        if (args.length == 1) {
            var subcommands = sender.hasPermission("myplugin.admin")
                ? List.of("reload", "info") : List.of("info");
            return subcommands.stream()
                .filter(s -> s.startsWith(args[0].toLowerCase(Locale.ROOT)))
                .toList();
        }
        return List.of();
    }
}
```

---

## Schedulers

For classic Paper plugins, `BukkitScheduler` is still fine. If you claim Folia support,
route player, entity, region, global, and async work through the matching Folia-aware
scheduler. Keep scheduling behind a small project-local interface when one plugin must
support both Paper and Folia.

See `references/runtime-patterns.md` for copy-ready sync, async, cancelable, and
Folia-safe scheduler examples.

---

## Persistent Data Container (PDC)

PDC stores arbitrary data on any `PersistentDataHolder` (players, entities, items, chunks).
Data is saved with the world and persists across restarts.

Create `NamespacedKey` instances once, keep data types stable after release, and use
PDC for small metadata rather than large datasets. Prefer config files or a database
for large or query-heavy plugin state.

See `references/runtime-patterns.md` for player, item, chunk, and world PDC examples.

---

## Adventure Text Components

Paper uses [Adventure](https://docs.advntr.dev/) natively for all text. No legacy chat colors.
Use `Component` builders for code-owned messages and MiniMessage for config-driven
messages. Avoid legacy `ChatColor` unless the target project already depends on it
for compatibility.

See `references/runtime-patterns.md` for simple messages, hover/click events,
MiniMessage parsing, titles, and action bars.

---

## Configuration (YAML)

### `src/main/resources/config.yml`
```yaml
# Default config
settings:
  max-players: 20
  welcome-message: "<green>Welcome to the server!"
  cooldown-seconds: 30

database:
  host: localhost
  port: 3306
  name: myplugin_db
```

### Accessing config values
Call `saveDefaultConfig()` in `onEnable()`, provide explicit defaults when reading
values, and validate config shape before starting long-running tasks.

### Custom config file
Use custom YAML files only when separating user config from mutable plugin data is
worth the extra file handling. Keep blocking disk writes off hot event paths.

See `references/runtime-patterns.md` for config read/write and custom YAML examples.

---

## Vault Integration (Economy / Permissions)

Declare Vault as `compileOnly`, soft-depend on it in plugin metadata, and disable
economy features cleanly when the service provider is unavailable. Never assume a
Vault-compatible economy plugin is installed just because Vault itself is present.

When Vault support is required, add the JitPack repository and
`compileOnly("com.github.MilkBowl:VaultAPI:1.7")` to the Gradle build.

See `references/runtime-patterns.md` for a minimal economy setup and charge example.

---

## Paper-Specific APIs

Use Paper APIs when they remove main-thread blocking or simplify Adventure-native
behavior. Keep optional plugin integrations behind presence checks and metadata
soft-dependencies.

See `references/runtime-patterns.md` for async chunk loading, custom item meta,
profile lookup, and protection-plugin integration examples.

---

## Common Tasks Checklist

### Creating a new event listener
- [ ] Create class implementing `Listener`
- [ ] Annotate methods with `@EventHandler`
- [ ] Call `getServer().getPluginManager().registerEvents(listener, plugin)` in `onEnable()`
- [ ] On cancellable events, add `ignoreCancelled = true` unless you need cancelled events

### Adding a new command
- [ ] For a Bukkit-compatible plugin, define the command in `plugin.yml`, create a `CommandExecutor`, and register it with `getCommand("name")`
- [ ] For a Paper-only plugin, register the command through `LifecycleEvents.COMMANDS`; do not add a `commands` field

### Saving plugin data
- [ ] For simple values: use `config.yml` via `getConfig()` / `saveConfig()`
- [ ] For per-entity data: use PDC with a `NamespacedKey`
- [ ] For large datasets: use async scheduler + file I/O or a database

### Scheduling a repeating task
- [ ] Determine if task needs main thread (use `runTaskTimer`) or is I/O (use `runTaskTimerAsynchronously`)
- [ ] Store the `BukkitTask` reference so you can cancel in `onDisable()`
- [ ] Cancel all tasks in `onDisable()` or use `getServer().getScheduler().cancelTasks(plugin)`

---

## Build, Validate, and Run

1. Build the plugin JAR:
   ```bash
   ./gradlew build
   # Output: build/libs/my-plugin-1.0.0-SNAPSHOT.jar
   ```
2. Run the bundled validator to catch config and layout errors:
   ```bash
   ./scripts/validate-plugin-layout.sh --root /path/to/plugin-project
   # Strict mode treats warnings as failures:
   ./scripts/validate-plugin-layout.sh --root /path/to/plugin-project --strict
   ```
   The validator requires Node and includes its own YAML parser for descriptor checks.
3. Fix any reported errors and re-run until clean.
4. Deploy: copy the built JAR to `server/plugins/` and restart the Paper server.
   If the real project already applies a Paper dev-server plugin such as `xyz.jpenilla.run-paper`,
   use that project's documented dev task instead of assuming `./gradlew runServer` exists.

The validator checks:
- active `plugin.yml` or `paper-plugin.yml` required keys (`name`, `version`, `main`, `api-version`) and repo-supported current `26.<release>` or legacy `1.21` / positive `1.21.<patch>` values, with warnings for versions newer than the documented examples
- cross-descriptor metadata consistency when both descriptors are present; `paper-plugin.yml` is selected as active
- Active main class path exists and extends `JavaPlugin`
- actual server `/reload` anti-patterns such as `Bukkit.reload()` or dispatching the server reload command

---

## References

- Paper API Javadoc: https://jd.papermc.io/paper/
- Paper plugin descriptor: https://docs.papermc.io/paper/dev/plugin-yml/
- Paper plugins: https://docs.papermc.io/paper/dev/getting-started/paper-plugins/
- Paper Brigadier registration: https://docs.papermc.io/paper/dev/command-api/basics/registration/
- Gradle Java compatibility: https://docs.gradle.org/current/userguide/compatibility.html
- Adventure (text API): https://docs.advntr.dev/
- MiniMessage format: https://docs.advntr.dev/minimessage/format.html
- Vault API: https://github.com/MilkBowl/VaultAPI
- Bukkit API Javadoc: https://javadoc.io/doc/org.bukkit/bukkit/
- run-task Gradle plugin: https://github.com/jpenilla/run-task

© Jahrome907 · MIT · Jahrome907/minecraft-agent-skills

Похожие скиллы

Все скиллы по теме «Геймдев и 3D: Unity, Unreal, Godot, Blender» →
minecraft-bukkit-pro rmyndharis Скилл minecraft-bukkit-pro для Claude Code помогает разрабатывать плагины Minecraft через Bukkit, Spigot и Paper. Включается для архитектуры, команд, событий и оптимизации сервера. CX Codex +1 131установок minecraft-mcp MakkCH Позволяющий ИИ-агенту управлять персонажем в Minecraft. Агент выполняет JavaScript-сценарии через JsMacros, делает снимки экрана и общается в игровом чате. CX Codex +1 ★ 26звёзд репо MCP Fabric (Minecraft) denfry MCP Fabric (Minecraft) — MCP-сервер для Claude Code, который связывает ИИ-клиент с Minecraft: Java Edition через мод mcpfabric и позволяет агенту осматривать игровой мир и управлять им. CX Codex +1 ★ 21звёзд репо mc-asset — Minecraft Pixel Asset Engine smile-minecraft MCP-сервер mc-asset — Minecraft Pixel Asset Engine для Claude Code создаёт текстуры и проверяет ресурс-паки Minecraft Java Edition. Запускается при генерации спрайтов по текстовым сеткам. CX Codex +1 ★ 5звёзд репо Minecraft Wiki l3-n0x MCP-сервер ищет страницы в официальной Minecraft Wiki и отдаёт агенту текст разделов: блоки, мобы, предметы, структуры. CX Codex +1 Minecraft MairwunNx MCP-сервер связывает ИИ-агента с Minecraft через WorldAPI: он читает данные мира и выполняет разрешённые действия. Подходит для проверки сервера и управления им из чата. CX Codex +1

Из того же набора13

Весь набор →
minecraft-resource-pack Скилл minecraft-resource-pack помогает собирать и отлаживать ресурс-паки Minecraft версий 1.21.x и 26.x. Генерирует модели блоков, звуковые карты, шрифты и конфиги pack.mcmeta без изменения серверного кода игры. CX Codex +1 385установок minecraft-datapack Скилл minecraft-datapack создаёт и отлаживает датапаки для Minecraft 1.21.x и 26.x. Помогает собрать структуру папок, функции, таблицы лута и настроить pack.mcmeta без модов. CX Codex +1 300установок minecraft-server-admin Скилл minecraft-server-admin для Claude Code ведёт Java-серверы Minecraft: Paper, Purpur, Folia, Velocity, Fabric и NeoForge. Разбирает падение TPS, отказ прокси и ошибки запуска версии. CX Codex +1 279установок minecraft-world-generation Скилл minecraft-world-generation для Claude Code помогает создавать и отлаживать генерацию мира Minecraft в датапаках и модах NeoForge или Fabric. Он подключается к задачам с биомами, измерениями, структурами и регистрацией worldgen-данных. CX Codex +1 269установок minecraft-multiloader Скилл minecraft-multiloader настраивает моды Minecraft на базе Architectury для версий 26.x и 1.21.x с общей кодовой базой под NeoForge и Fabric. Включается при одновременной поддержке обоих загрузчиков. CX Codex +1 247установок minecraft-commands-scripting Скилл minecraft-commands-scripting генерирует и отлаживает команды Minecraft Java 26.x и 1.21.x, цепочки execute, скорборды и RCON-скрипты. Работает со строками команд без сборки структуры датапаков. CX Codex +1 241установок minecraft-ci-release Скилл minecraft-ci-release собирает CI и релизы для модов Minecraft и плагинов Paper: workflow, артефакты, версии, теги и GitHub Release. CX Codex +1 238установок minecraft-imagegen Скилл minecraft-imagegen создаёт и редактирует растровые изображения для Minecraft: иконки паков, баннеры, текстурные концепты и макеты интерфейса. CX Codex +1 213установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой