paper-plugins-skill

Paper Plugins Skill

A Codex skill for building, updating, reviewing, and debugging modern Minecraft Paper server plugins.

This skill gives Codex focused guidance for Paper/PaperMC plugin work in Java or Kotlin, including Gradle setup, plugin descriptors, Brigadier commands, Adventure text, Paper-specific APIs, persistence, runtime scheduling, Folia considerations, and release review checks.

What This Skill Covers

• Creating or updating Paper plugin project structure
• Choosing between plugin.yml and paper-plugin.yml
• Configuring Gradle with the Paper API
• Registering commands with Paper's Brigadier lifecycle APIs
• Using Adventure components and MiniMessage for player-facing text
• Working with dialogs, display entities, particles, boss bars, and other UI effects
• Managing Persistent Data Container keys, configuration files, serialization, and databases
• Implementing custom items, data components, registries, tags, and recipes
• Handling schedulers, async work, events, plugin messaging, and Folia compatibility
• Reviewing Paper plugins before release

Repository Structure

paper-plugins-skill/
+-- SKILL.md
+-- agents/
|   +-- openai.yaml
+-- references/
    +-- commands.md
    +-- data-storage.md
    +-- items-registries-recipes.md
    +-- project-setup.md
    +-- review-checklist.md
    +-- runtime-integrations.md
    +-- text-ui-and-effects.md

Files

• SKILL.md defines the skill metadata, trigger description, workflow, default assumptions, guardrails, and official documentation sources.
• agents/openai.yaml provides UI-facing metadata for skill lists and prompts.
• references/*.md contains topic-specific guidance that Codex should load only when relevant to the task.

Installation

Install the skill directly from the GitHub repository:

npx skills add https://github.com/shaokeyibb/paper-plugins-skill

Restart Codex or refresh the environment if your client does not automatically discover new skills.

Usage

Ask Codex to use the skill explicitly:

Use $paper-plugins-skill to create a Paper plugin with a /spawn command.

Or ask for a task that naturally matches the skill:

Review this Paper plugin for scheduler and command registration issues.

Update this Spigot-style plugin to use modern Paper APIs where appropriate.

Add persistent custom item metadata to this Paper plugin.

Design Principles

• Preserve the target Paper and Minecraft version already pinned by the project unless the user requests an upgrade.
• Prefer Paper APIs over legacy Bukkit or Spigot patterns when Paper provides a stable replacement.
• Keep version-sensitive APIs localized behind small modules or adapters.
• Treat paper-plugin.yml, data components, dialog APIs, bootstrap logic, and registry mutation as deliberate Paper-only choices.
• Keep blocking I/O off the server tick thread and return to the correct scheduler before touching live game state.
• Validate changes with the target repository's build command, usually ./gradlew build or .\gradlew.bat build.

Development

When updating the skill:

1. Keep SKILL.md concise and focused on workflow, guardrails, and reference selection.
2. Put detailed topic guidance in references/.
3. Avoid duplicating the same rule in multiple files unless it is essential context for that topic.
4. Keep examples version-aware and avoid dynamic dependency versions in committed snippets.
5. Ensure agents/openai.yaml still accurately describes the skill after major changes.

External References

The skill points Codex toward official Paper resources when local project context is not enough:

• Paper developer docs: https://docs.papermc.io/paper/dev/
• Paper project setup: https://docs.papermc.io/paper/dev/project-setup/
• Paper plugins: https://docs.papermc.io/paper/dev/getting-started/paper-plugins/
• Plugin descriptor docs: https://docs.papermc.io/paper/dev/plugin-yml/
• Paper Javadocs: https://jd.papermc.io/paper/

License

This project is licensed under the MIT License. See LICENSE for details.