feat: add minecraft-plugin-development skillFeat/minecraft plugin development

[zixuanjiang332]

Pull Request Checklist

• I have read and followed the CONTRIBUTING.md guidelines.
• I have read and followed the Guidance for submissions involving paid services.
• My contribution adds a new instruction, prompt, agent, skill, or workflow file in the correct directory.
• The file follows the required naming convention.
• The content is clearly structured and follows the example format.
• I have tested my instructions, prompt, agent, skill, or workflow with GitHub Copilot.
• I have run npm start and verified that README.md is up to date.
• I am targeting the staged branch for this pull request.

---

Description

This PR adds a new skill: minecraft-plugin-development.
This skill is based on real Paper plugin development patterns rather than generic Minecraft advice, and is intended to improve Copilot usefulness for gameplay-heavy server plugins and it is designed for Paper, Spigot, and Bukkit plugin development, with a focus on stateful, gameplay-heavy Minecraft server plugins rather than generic Java coding guidance.

It covers practical plugin-development scenarios such as:

• plugin.yml setup and command wiring
• listener design and event handling
• scheduler and task lifecycle management
• player session and gameplay state modeling
• team, arena, and match flow logic
• config-driven gameplay values
• async persistence and Bukkit main-thread boundaries
• Paper-safe and version-aware API usage

In addition to the main SKILL.md, this contribution includes focused reference documents so the skill can use progressive disclosure instead of putting all guidance directly in the main file.

---

Why this skill is valuable

Minecraft plugin development has several recurring pitfalls that are easy to get wrong with generic coding guidance alone, especially in Paper plugins with custom game modes:

• keeping plugin.yml, executors, permissions, and startup registration in sync
• modeling player, team, arena, and match state cleanly
• handling scheduled tasks across match start, round end, player quit, and plugin shutdown
• separating async database/cache work from Bukkit API mutations on the main thread
• structuring a plugin as it grows from a small command/listener plugin into a multi-system gameplay project

This skill aims to give Copilot more grounded guidance for those real-world patterns.

---

Real-world patterns reflected in this contribution

This skill was informed by architecture and implementation patterns from two real Paper plugin codebases with different styles:

• a match-heavy gameplay plugin with:

  • game phases
  • player sessions
  • teams and map instances
  • match overlays
  • boss/resource systems
  • config-driven gameplay rules

• a class-based PvP plugin with:

  • service-oriented architecture
  • hero/class selection
  • progression and player data services
  • async leaderboard refreshes
  • rotating combat maps

These patterns are reflected in the added references for:

• project architecture
• bootstrap and registration
• sessions, state, and gameplay phases
• config, persistence, and async handling
• maps, hero/class systems, and modular feature growth

---

Type of Contribution

• New skill file.

---

Files added

• skills/minecraft-plugin-development/SKILL.md
• skills/minecraft-plugin-development/references/project-patterns.md
• skills/minecraft-plugin-development/references/bootstrap-registration.md
• skills/minecraft-plugin-development/references/state-sessions-and-phases.md
• skills/minecraft-plugin-development/references/config-data-and-async.md
• skills/minecraft-plugin-development/references/maps-heroes-and-feature-modules.md

This PR also updates:

• docs/README.skills.md

---

Validation

Ran successfully:

• npm run skill:validate
• npm start

---

Additional Notes

The goal of this skill is not to replace general Java or plugin best practices, but to provide Copilot with better guidance for the kinds of gameplay-oriented Paper plugin workflows that often involve:
this is my first time trying a pull request

• complex player and match state
• repeated registration/update mistakes
• scheduler cleanup problems
• async vs main-thread mistakes
• growing feature surfaces such as maps, heroes/classes, shops, scoreboards, and progression

[github-actions]

🔍 Skill Validator Results

⚠️ Warnings or advisories found

Scope	Checked
Skills	1
Agents	1
Total	2
Severity	Count
---	---:
❌ Errors	0
⚠️ Warnings	1
ℹ️ Advisories	0

Summary

Level	Finding
ℹ️	Found 1 skill(s)
ℹ️	[minecraft-plugin-development] 📊 minecraft-plugin-development: 1,853 BPE tokens [chars/4: 2,278] (detailed ✓), 22 sections, 0 code blocks
ℹ️	[minecraft-plugin-development] ⚠ No code blocks — agents perform better with concrete snippets and commands.
ℹ️	✅ All checks passed (1 skill(s))

Full validator output

```text Found 1 skill(s) [minecraft-plugin-development] 📊 minecraft-plugin-development: 1,853 BPE tokens [chars/4: 2,278] (detailed ✓), 22 sections, 0 code blocks [minecraft-plugin-development] ⚠ No code blocks — agents perform better with concrete snippets and commands. ✅ All checks passed (1 skill(s)) ```

[zixuanjiang332]

Thanks — I traced the validator noise to the branch base rather than the new skill itself.

The PR branch has now been rebuilt on top of staged and force-pushed so the diff only contains the new minecraft-plugin-development skill and its generated docs/README.skills.md update.

The previous validator run was comparing a main-based branch against staged, which pulled in unrelated repository differences. A fresh run should now validate only this contribution.