paper-plugin-dev

May 26, 2026 · View on GitHub

A Claude Code plugin that turns Claude into a senior Minecraft Paper plugin developer.

Adds a comprehensive skill and 8 specialized subagents covering every stage of Paper plugin development — from project architecture to Modrinth publishing. Enforces modern practices throughout: Adventure API, Display entities, config-driven design, lang files, and LuckPerms permission trees.

Features

Skill: `paper-plugin-core`

Automatically loaded when Claude detects a Paper plugin project. Covers:

Modern stack — Gradle Kotlin DSL, paper-plugin.yml, paperweight userdev
Adventure API + MiniMessage — legacy ChatColor and § codes are always flagged and replaced
Display entities — TextDisplay, BlockDisplay, ItemDisplay for all visual needs; ArmorStand hacks are never suggested
Commands — cloud-command-framework with Brigadier, one permission node per subcommand, LuckPerms-compatible tree design
Data — PDC, SQLite + HikariCP, YAML configs with type-safe wrappers and startup validation
Config-driven items — every item property (material, name, lore, item-model, custom model data, flags, attributes, enchantments) pulled from items.yml
Config-driven GUIs — menu titles, sizes, slot positions, and item definitions all live in menus.yml; shift-click and drag exploits handled automatically
Lang files — every player-facing string in lang/en_US.yml (MiniMessage format); nothing hard-coded
Player abuse prevention — inventory exploit patterns, cooldowns, null-safe deferred tasks, duplicate-join guards, permission escalation checks
Scheduling — BukkitScheduler and Folia-compatible regional schedulers
Plugin integrations — MythicMobs API, ModelEngine API, PlaceholderAPI, WorldGuard, Vault, LuckPerms
Testing — MockBukkit patterns for unit testing event handlers and commands
Publishing — shadow JAR config with relocation, GitHub Actions CI, Modrinth/Hangar, bStats, update checker

Subagents (8 specialists)

Agent	Activates when you…
`paper-architect`	Start a new plugin or plan a major refactor
`paper-debugger`	Share a crash log, stack trace, or unexpected behavior
`paper-reviewer`	Ask for a code review or pre-publish audit
`paper-data`	Design storage, PDC patterns, or player data lifecycle
`paper-commands`	Build a command tree or tab completion
`paper-events`	Work with events, priorities, or custom event types
`paper-performance`	Diagnose TPS drops, profile with Spark, or add Folia support
`paper-publisher`	Prepare a release, set up CI, or submit to Modrinth/Hangar

Installation

Requires Claude Code.

1. Add the marketplace

/plugin marketplace add Miscodings/paper-plugin

2. Install the plugin

/plugin install paper-plugin-dev@paper-plugin-dev

3. Reload

/reload-plugins

That's it. Open any Paper plugin project and everything activates automatically.

Usage

Claude picks up the skill and routes to the right subagent automatically. You can also invoke them directly:

Review my PlayerListener class for any API issues

I'm getting a NullPointerException in my scheduler callback — here's the stack trace

Design the architecture for a kit-based PvP arena plugin

Set up GitHub Actions to publish to Modrinth on every version tag

What gets enforced

Every plugin this helps build follows these non-negotiable rules:

No legacy chat formatting — MiniMessage everywhere, including item names, lore, titles, and action bars
No ArmorStands for visual/display purposes — TextDisplay, BlockDisplay, ItemDisplay only
No hard-coded player-facing strings — everything goes through a lang file
No hard-coded item definitions — material, model, attributes, flags all live in config
No hard-coded GUI slot positions or menu titles
No shared permission nodes across unrelated commands
No Bukkit API calls from async threads
No SQL string concatenation — prepared statements only
No Player references stored in collections — UUIDs only

Target Environment

Requirement	Version
Paper	1.21.x (latest stable)
Java	21+
Kotlin	2.x
Gradle	8.x
Claude Code	Latest

Contributing

PRs welcome. If you're adding a new subagent or extending the skill, follow the existing frontmatter format and keep content opinionated — the goal is enforcing modern patterns, not documenting every possible approach.

License

MIT — see LICENSE.