papermc-skill 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-09-05
+
+### Added
+- **Interactive NPX CLI Tool (`papermc-skill`)**:
+  - `npx papermc-skill create [name]`: Interactive project scaffolding for modern Paper & Folia plugins with customizable package name, author, and Minecraft target version.
+  - `npx papermc-skill install-skill [--global]`: Automated installation of the `paper-plugin-dev` AI agent skill for workspace (`.agents/skills/`) or global (`~/.gemini/config/skills/`).
+  - `npx papermc-skill docs [topic]`: Instant in-terminal viewer for architectural guides.
+- **Modern Starter Template (`templates/paper-modern-template`)**:
+  - Gradle Kotlin DSL build setup (`build.gradle.kts`) with Java 21 toolchain and Foojay resolver convention.
+  - Paper 1.21.4 API dependency and instant testing tasks (`./gradlew runServer`, `./gradlew runFoliaServer`).
+  - Bundled official Gradle Wrapper (`gradlew`, `gradlew.bat`).
+  - Native Brigadier command registration via `LifecycleEvents.COMMANDS`.
+  - Kyori Adventure & MiniMessage integration without deprecated formatting codes.
+  - PersistentDataContainer (PDC) usage for player join tracking.
+  - Transparent Folia multi-threaded scheduler adapter (`SchedulerAdapter.java`).
+- **Comprehensive Architectural & Technical Guides (`docs/`)**:
+  - `01-modern-paper-architecture.md`: Paperweight userdev, `paper-plugin.yml`, and `PluginBootstrap`.
+  - `02-adventure-and-minimessage.md`: Kyori Adventure Component, gradient tags, Title, Sound, and BossBar.
+  - `03-persistent-data-container.md`: PDC on Item, Entity, and Chunk with custom `PersistentDataType`.
+  - `04-commands-and-brigadier.md`: Paper native Brigadier commands and Incendo Cloud framework.
+  - `05-concurrency-and-folia.md`: Threaded Regions, Folia Schedulers, and thread safety.
+  - `06-events-and-listeners.md`: Paper-exclusive events, event priority, and custom events.
+  - `07-best-practices-and-perf.md`: Memory leak prevention, async chunk loading, and anti-patterns.
+  - `08-gui-and-menus.md`: Safe custom `InventoryHolder` menus with PDC click action buttons.
+  - `09-custom-items-and-combat.md`: Raycasting spells, particles, vanilla cooldowns, and combat mechanics.
+  - `10-database-and-storage.md`: Asynchronous database handling with SQLite and MySQL HikariCP pool.
+- **AI Agent Skill Specification (`skills/paper-plugin-dev/SKILL.md`)**:
+  - Step-by-step workflow, dependency matrix, and ready-to-use code recipes for coding assistants.
+- **Nine Cloned Open-Source Reference Plugins (`references/`)**:
+  - `squaremap`, `chunky`, `luckperms`, `miniplaceholders`, `vault-api`, `run-paper`, `decentholograms`, `bstats`, and `paperweight-test-plugin`.
+- **Open-Source Governance & Security Suite**:
+  - MIT License (`LICENSE`), Code of Conduct (`CODE_OF_CONDUCT.md`), Contributing Guide (`CONTRIBUTING.md`), and Security Policy (`SECURITY.md`).
+  - GitHub Issue and Pull Request templates (`.github/ISSUE_TEMPLATE/`).
+  - Automated CI and NPM Publish workflows with provenance (`.github/workflows/`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paper Minecraft Plugin Skill Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,169 @@
+<div align="center">
+
+# 🎮 Paper Minecraft Plugin Skill & Knowledge Base
+
+[![PaperMC](https://img.shields.io/badge/PaperMC-1.20.6%20%7C%201.21+-0098FF?style=for-the-badge&logo=minecraft&logoColor=white)](https://papermc.io)
+[![Java](https://img.shields.io/badge/Java-21%2B%20LTS-ED8B00?style=for-the-badge&logo=openjdk&logoColor=white)](https://adoptium.net)
+[![Folia](https://img.shields.io/badge/Folia-Multi--Threaded%20Ready-5865F2?style=for-the-badge)](https://github.com/PaperMC/Folia)
+[![License: MIT](https://img.shields.io/badge/License-MIT-44CC11?style=for-the-badge)](LICENSE)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=for-the-badge)](CONTRIBUTING.md)
+
+**A comprehensive, production-grade knowledge base, architectural reference collection, starter template, and AI engineering skill for modern Minecraft Java Server plugin development on [PaperMC](https://papermc.io) and [Folia](https://github.com/PaperMC/Folia).**
+
+[Features](#-features) • [Quickstart](#-quickstart) • [Architecture Guide](#-documentation-suite) • [Reference Plugins](#-cloned-reference-plugins) • [AI Skill](#-ai-agent-integration) • [Contributing](#-contributing)
+
+---
+
+</div>
+
+## 🌟 Overview
+
+The Minecraft server development ecosystem has undergone massive architectural shifts with Minecraft 1.20.5+ and 1.21+. Legacy Bukkit/Spigot habits—such as section sign color formatting (`§`), `plugin.yml` command registration, third-party NBT hacks, and blocking main-thread schedulers—lead to performance degradation, memory leaks, and fatal crashes on modern servers.
+
+This repository serves as an **authoritative, single-source knowledge base** and **developer skill** designed to empower both human software engineers and AI pair-programming assistants to build performant, thread-safe, and idiomatic Paper plugins.
+
+---
+
+## ⚡ Key Architecture Highlights
+
+| Modern Paper Standard | Legacy Spigot / Bukkit | Why Modern Matters |
+| :--- | :--- | :--- |
+| **Kyori Adventure & MiniMessage** | `ChatColor` & `§` color codes | Type-safe, component-based, 24-bit TrueColor/Hex gradients, interactive click/hover events, and zero string-injection risks. |
+| **PersistentDataContainer (PDC)** | External NBT libraries / Lore parsing | Official native NBT storage on Items, Entities, Chunks, and Worlds. Serializes Java records seamlessly. |
+| **Paper Native Brigadier** | `plugin.yml` & `setExecutor(...)` | Client-side syntax validation, auto tab-completion, and command routing directly inside Mojang's Brigadier engine. |
+| **Regionized Threading (Folia)** | Single Main Thread `BukkitScheduler` | Scales across CPU cores via Threaded Regions. Uses `RegionScheduler`, `EntityScheduler`, and `AsyncScheduler`. |
+| **Mojang Mappings (Paperweight)** | Spigot remapped / Obfuscated NMS | Zero-remapping runtime on Paper 1.20.5+; direct, clean access to Mojang server internals with `paperweight-userdev`. |
+
+---
+
+## 📚 Documentation Suite
+
+Our documentation suite includes 10 comprehensive, in-depth architectural guides:
+
+1. **[01. Modern Paper Architecture](https://github.com/ardianryan/papermc-skill/blob/main/docs/01-modern-paper-architecture.md)**  
+   *Deep dive into `paper-plugin.yml`, `PluginBootstrap` vs `JavaPlugin`, Gradle `paperweight-userdev`, and runtime Mojang mappings.*
+2. **[02. Adventure API & MiniMessage](https://github.com/ardianryan/papermc-skill/blob/main/docs/02-adventure-and-minimessage.md)**  
+   *Hex colors, gradient tags, dynamic `TagResolver` placeholders, `ComponentLogger`, Titles, BossBars, and Sound playback.*
+3. **[03. PersistentDataContainer (PDC)](https://github.com/ardianryan/papermc-skill/blob/main/docs/03-persistent-data-container.md)**  
+   *Storing custom data on ItemStacks, Entities, and Chunks; implementing custom `PersistentDataType<T, Z>` for POJO/record serialization.*
+4. **[04. Modern Command Systems: Brigadier & Cloud](https://github.com/ardianryan/papermc-skill/blob/main/docs/04-commands-and-brigadier.md)**  
+   *Paper's native Brigadier command registration via `LifecycleEvents.COMMANDS`, argument parsing, suggestions, and Incendo Cloud.*
+5. **[05. Concurrency, Threading & Folia Compatibility](https://github.com/ardianryan/papermc-skill/blob/main/docs/05-concurrency-and-folia.md)**  
+   *Threaded regions, region schedulers, entity schedulers, async schedulers, and universal cross-platform scheduling abstractions.*
+6. **[06. Event System & Listeners](https://github.com/ardianryan/papermc-skill/blob/main/docs/06-events-and-listeners.md)**  
+   *Paper-exclusive events (`AsyncChatEvent`, `PrePlayerAttackEntityEvent`), event priority lifecycle, and custom event authoring.*
+7. **[07. Best Practices & Performance Optimization](https://github.com/ardianryan/papermc-skill/blob/main/docs/07-best-practices-and-perf.md)**  
+   *Preventing GC memory leaks (UUID vs entity references), asynchronous chunk loading (`world.getChunkAtAsync`), and anti-patterns.*
+8. **[08. Modern GUI & Inventory Menus](https://github.com/ardianryan/papermc-skill/blob/main/docs/08-gui-and-menus.md)**  
+   *Custom `InventoryHolder` verification, PDC-tagged interactive buttons, and bulletproof duplication-exploit prevention.*
+9. **[09. Custom Items, Abilities & Combat](https://github.com/ardianryan/papermc-skill/blob/main/docs/09-custom-items-and-combat.md)**  
+   *Raycasting hitscan spells (`rayTraceEntities`), particle beam effects, vanilla visual cooldowns, and Adventure sound effects.*
+10. **[10. Asynchronous Database Storage](https://github.com/ardianryan/papermc-skill/blob/main/docs/10-database-and-storage.md)**  
+    *SQLite and MySQL/PostgreSQL connection pooling via HikariCP, thread-safe asynchronous DAO pattern with `CompletableFuture`.*
+
+---
+
+## 🔍 Cloned Reference Plugins
+
+Nine industry-standard open-source repositories have been cloned into [`references/`](references/) as real-world architectural blueprints:
+
+| Repository | Source Origin | Core Concepts Demonstrated |
+| :--- | :--- | :--- |
+| **[`squaremap`](references/squaremap)** | `jpenilla/squaremap` | Developed by a PaperMC core developer. World rendering, `paperweight-userdev`, Incendo Cloud commands, and Folia multi-threading. |
+| **[`chunky`](references/chunky)** | `pop4959/Chunky` | High-throughput async chunk loading (`world.getChunkAtAsync`), mathematical optimizations, and multi-platform platform adapters. |
+| **[`luckperms`](references/luckperms)** | `LuckPerms/LuckPerms` | Enterprise-grade Java architecture: HikariCP connection pooling, custom internal event bus, caching hierarchy, and async I/O. |
+| **[`miniplaceholders`](references/miniplaceholders)** | `MiniPlaceholders/MiniPlaceholders` | Advanced Kyori Adventure API usage, custom MiniMessage tag resolvers, and modern `paper-plugin.yml` bootstrapping. |
+| **[`vault-api`](references/vault-api)** | `MilkBowl/VaultAPI` | The standard ecosystem bridge API for economy and permissions in Minecraft Java. |
+| **[`run-paper`](references/run-paper)** | `jpenilla/run-paper` | The Gradle plugin source code for running instant local Paper and Folia test environments. |
+| **[`decentholograms`](references/decentholograms)** | `DecentSoftware-eu/DecentHolograms` | Display entity manipulation, protocol packet handling, and dynamic per-player text rendering. |
+| **[`bstats`](references/bstats)** | `Bastian/bStats-Metrics` | Industry-standard telemetry and metrics integration for Minecraft server plugins. |
+| **[`paperweight-test-plugin`](references/paperweight-test-plugin)** | `PaperMC/paperweight-test-plugin` | Official PaperMC test project for `paperweight-userdev` Gradle configurations. |
+
+---
+
+## 🚀 Quickstart
+
+### Method 1: Instant Scaffolding via NPX (Recommended)
+
+You can scaffold a new Paper plugin or install the AI skill instantly anywhere using `npx`:
+
+```bash
+# 1. Interactively create a new modern Paper & Folia plugin
+npx papermc-skill create MyAwesomePlugin
+
+# 2. Or install the AI skill into your workspace (.agents/skills) or globally
+npx papermc-skill install-skill --global
+
+# 3. Read architectural guides right in your terminal
+npx papermc-skill docs
+```
+
+### Method 2: Manual Clone & Local Server Test
+
+A production-ready Gradle starter template is available in [`templates/paper-modern-template/`](templates/paper-modern-template).
+
+#### Prerequisites
+- **Java 21 SDK** installed ([Adoptium Temurin 21](https://adoptium.net/)):
+  - macOS: `brew install openjdk@21`
+  - Linux: `sudo apt install openjdk-21-jdk`
+- Gradle is bundled inside the template via `./gradlew` (no manual Gradle install required).
+
+#### Running a Local Test Server in 60 Seconds
+```bash
+# 1. Navigate to the template project
+cd templates/paper-modern-template
+
+# 2. Launch an automated Paper test server
+./gradlew runServer
+
+# 3. Or launch a multi-threaded Folia test server
+./gradlew runFoliaServer
+```
+The task will automatically download the Paper/Folia runtime, accept the Mojang EULA, compile your code, and launch the server with your plugin enabled.
+
+---
+
+## 🤖 AI Agent Integration
+
+This repository includes a standardized AI Assistant Skill in [`skills/paper-plugin-dev/SKILL.md`](skills/paper-plugin-dev/SKILL.md).
+
+When working with AI coding assistants (such as Antigravity, GitHub Copilot, or Cursor):
+- Point your assistant to `skills/paper-plugin-dev/SKILL.md`.
+- The assistant will automatically adopt modern Paper 1.21+ standards, avoid deprecated Spigot methods, enforce Folia thread-safety, and use Adventure/PDC patterns out of the box.
+
+---
+
+## 📁 Repository Structure
+
+```text
+minecraft-plugin-skill/
+├── .github/                            # Issue & Pull Request templates
+│   ├── ISSUE_TEMPLATE/
+│   │   ├── bug_report.yml
+│   │   └── feature_request.yml
+│   └── pull_request_template.md
+├── docs/                               # 10 In-depth architectural guides
+├── references/                         # 9 Cloned open-source reference plugins
+├── skills/
+│   └── paper-plugin-dev/               # AI Assistant Skill definition (SKILL.md)
+├── templates/
+│   └── paper-modern-template/          # Standalone, runnable starter plugin project
+├── CODE_OF_CONDUCT.md                  # Contributor Covenant v2.1
+├── CONTRIBUTING.md                     # Comprehensive contribution guide
+├── LICENSE                             # MIT License
+├── README.md                           # Repository documentation
+└── SECURITY.md                         # Security policy & reporting guidelines
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md) before submitting pull requests or opening issues.
+
+---
+
+## 📄 License & Trademarks
+
+- This project is licensed under the **[MIT License](LICENSE)**.
+- *Minecraft* is a registered trademark of Mojang Synergies AB. This project is not affiliated with or endorsed by Mojang Synergies AB, Microsoft Corporation, or PaperMC.

package/bin/cli.js

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const ROOT_DIR = path.resolve(__dirname, '..');
+
+// ANSI Color Helpers (Pure zero-dependency, safe for all terminals)
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  gray: '\x1b[90m'
+};
+
+function printBanner() {
+  console.log(`
+${c.cyan}${c.bold}  ____                            __  __  ____ 
+ |  _ \\ __ _ _ __   ___ _ __     |  \\/  |/ ___|  ____  _     _ _ _ 
+ | |_) / _\` | '_ \\ / _ \\ '__|____| |\\/| | |     / ___|| | __(_) | |
+ |  __/ (_| | |_) |  __/ | |_____| |  | | |___  \\___ \\| |/ / | | |
+ |_|   \\__,_| .__/ \\___|_|       |_|  |_|\\____| |____/|_|\\_\\_|_|_|
+            |_| ${c.reset}${c.dim}Modern Paper & Folia Plugin Toolchain${c.reset}
+`);
+}
+
+function prompt(question, defaultValue) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  return new Promise((resolve) => {
+    const q = defaultValue
+      ? `${c.cyan}?${c.reset} ${c.bold}${question}${c.reset} ${c.dim}(${defaultValue})${c.reset}: `
+      : `${c.cyan}?${c.reset} ${c.bold}${question}${c.reset}: `;
+
+    rl.question(q, (answer) => {
+      rl.close();
+      resolve(answer.trim() || defaultValue);
+    });
+  });
+}
+
+// Strict Input Sanitization (Prevents path traversal, code injection & illegal characters)
+function sanitizePluginName(name) {
+  const sanitized = String(name || '').trim().replace(/[^a-zA-Z0-9_-]/g, '');
+  if (!sanitized) {
+    throw new Error('Plugin name must contain at least one alphanumeric character.');
+  }
+  return sanitized;
+}
+
+function sanitizePackageName(pkg) {
+  const sanitized = String(pkg || '').trim().toLowerCase().replace(/[^a-z0-9_.]/g, '');
+  if (!sanitized || sanitized.startsWith('.') || sanitized.endsWith('.') || sanitized.includes('..')) {
+    throw new Error('Invalid package name format. Example: com.example.myplugin');
+  }
+  return sanitized;
+}
+
+function sanitizeSafeDir(baseDir, targetName) {
+  const safeName = path.basename(targetName).replace(/[^a-zA-Z0-9_-]/g, '');
+  const resolved = path.resolve(baseDir, safeName);
+  if (!resolved.startsWith(path.resolve(baseDir))) {
+    throw new Error('Security Error: Path traversal attempt detected.');
+  }
+  return resolved;
+}
+
+function copyDirRecursive(src, dest, replacements = {}) {
+  fs.mkdirSync(dest, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath, replacements);
+    } else {
+      const content = fs.readFileSync(srcPath);
+
+      // Text replacement only on safe, recognized source file types
+      if (
+        entry.name.endsWith('.gradle.kts') ||
+        entry.name.endsWith('.yml') ||
+        entry.name.endsWith('.yaml') ||
+        entry.name.endsWith('.java') ||
+        entry.name.endsWith('.md')
+      ) {
+        let text = content.toString('utf-8');
+        for (const [key, value] of Object.entries(replacements)) {
+          text = text.replaceAll(key, value);
+        }
+        fs.writeFileSync(destPath, text, 'utf-8');
+      } else {
+        fs.copyFileSync(srcPath, destPath);
+      }
+
+      // Preserve executable permissions for gradlew wrapper
+      if (entry.name === 'gradlew') {
+        try {
+          fs.chmodSync(destPath, 0o755);
+        } catch (_) {}
+      }
+    }
+  }
+}
+
+async function handleCreate(targetDirArg) {
+  printBanner();
+  console.log(`${c.bold}Scaffolding a new Modern Paper Plugin...${c.reset}\n`);
+
+  const rawPluginName = await prompt('Plugin Name', targetDirArg || 'MyPaperPlugin');
+  const pluginName = sanitizePluginName(rawPluginName);
+  const targetDir = sanitizeSafeDir(process.cwd(), targetDirArg || pluginName.toLowerCase());
+
+  if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0) {
+    console.error(`\n${c.red}Error:${c.reset} Target directory '${targetDir}' already exists and is not empty.\n`);
+    process.exit(1);
+  }
+
+  const rawPackage = await prompt('Package Group (e.g. com.example.plugin)', `com.example.${pluginName.toLowerCase().replace(/[^a-z0-9]/g, '')}`);
+  const packageName = sanitizePackageName(rawPackage);
+
+  const rawAuthor = await prompt('Author Name', 'Developer');
+  const authorName = String(rawAuthor || 'Developer').replace(/[^a-zA-Z0-9_\s-]/g, '').trim() || 'Developer';
+
+  const mcVersion = await prompt('Paper Minecraft Version', '1.21.4');
+  const cleanMcVersion = String(mcVersion || '1.21.4').replace(/[^0-9.]/g, '') || '1.21.4';
+
+  console.log(`\n${c.yellow}Creating project at:${c.reset} ${c.dim}${targetDir}${c.reset}`);
+
+  const templateDir = path.join(ROOT_DIR, 'templates', 'paper-modern-template');
+  if (!fs.existsSync(templateDir)) {
+    console.error(`${c.red}Error:${c.reset} Starter template directory not found at ${templateDir}`);
+    process.exit(1);
+  }
+
+  // 1. Copy base template with sanitized replacements
+  copyDirRecursive(templateDir, targetDir, {
+    'ModernPaperTemplate': pluginName,
+    'paper-modern-template': pluginName.toLowerCase().replace(/[^a-z0-9_-]/gi, '-'),
+    'com.example.paperplugin': packageName,
+    '1.21.4': cleanMcVersion,
+    'Developer': authorName
+  });
+
+  // 2. Refactor Java package directory structure if package changed from com.example.paperplugin
+  const defaultPackagePath = path.join(targetDir, 'src', 'main', 'java', 'com', 'example', 'paperplugin');
+  const targetPackagePath = path.join(targetDir, 'src', 'main', 'java', ...packageName.split('.'));
+
+  if (defaultPackagePath !== targetPackagePath && fs.existsSync(defaultPackagePath)) {
+    fs.mkdirSync(targetPackagePath, { recursive: true });
+    const files = fs.readdirSync(defaultPackagePath);
+    for (const file of files) {
+      fs.renameSync(path.join(defaultPackagePath, file), path.join(targetPackagePath, file));
+    }
+    // Cleanup empty old dirs safely
+    try {
+      fs.rmSync(path.join(targetDir, 'src', 'main', 'java', 'com', 'example'), { recursive: true, force: true });
+    } catch (_) {}
+  }
+
+  console.log(`\n${c.green}${c.bold}✔ Project created successfully!${c.reset}\n`);
+  console.log(`${c.bold}To start developing and run your test server:${c.reset}`);
+  console.log(`  ${c.cyan}cd${c.reset} ${path.relative(process.cwd(), targetDir) || '.'}`);
+  console.log(`  ${c.cyan}./gradlew runServer${c.reset}      ${c.gray}# Launches Paper test server${c.reset}`);
+  console.log(`  ${c.cyan}./gradlew runFoliaServer${c.reset} # Launches Folia multi-threaded test server${c.reset}\n`);
+}
+
+async function handleInstallSkill(options) {
+  printBanner();
+  console.log(`${c.bold}Installing 'paper-plugin-dev' Agent Skill...${c.reset}\n`);
+
+  const isGlobal = options.includes('--global') || options.includes('-g');
+  const homeDir = process.env.HOME || process.env.USERPROFILE;
+  
+  let targetSkillDir;
+  if (isGlobal) {
+    targetSkillDir = path.join(homeDir, '.gemini', 'config', 'skills', 'paper-plugin-dev');
+  } else {
+    // Current workspace customization root
+    targetSkillDir = path.resolve(process.cwd(), '.agents', 'skills', 'paper-plugin-dev');
+  }
+
+  const srcSkillDir = path.join(ROOT_DIR, 'skills', 'paper-plugin-dev');
+  if (!fs.existsSync(srcSkillDir)) {
+    console.error(`${c.red}Error:${c.reset} Source skill directory not found at ${srcSkillDir}`);
+    process.exit(1);
+  }
+
+  copyDirRecursive(srcSkillDir, targetSkillDir);
+
+  console.log(`${c.green}${c.bold}✔ Skill successfully installed!${c.reset}`);
+  console.log(`  Target: ${c.dim}${targetSkillDir}${c.reset}\n`);
+  console.log(`Your AI coding agent can now automatically discover and load the ${c.bold}paper-plugin-dev${c.reset} skill.`);
+}
+
+function handleDocs(topic) {
+  const docsDir = path.join(ROOT_DIR, 'docs');
+  if (!fs.existsSync(docsDir)) {
+    console.error(`${c.red}Error:${c.reset} Docs directory not found.`);
+    process.exit(1);
+  }
+
+  const files = fs.readdirSync(docsDir).filter(f => f.endsWith('.md')).sort();
+
+  if (!topic) {
+    printBanner();
+    console.log(`${c.bold}Available Architectural & Technical Guides:${c.reset}\n`);
+    files.forEach((file, index) => {
+      console.log(`  ${c.cyan}${String(index + 1).padStart(2, '0')}.${c.reset} ${c.bold}${file}${c.reset}`);
+    });
+    console.log(`\nTo view a specific guide, run: ${c.cyan}npx papermc-skill docs <number|keyword>${c.reset}\n`);
+    return;
+  }
+
+  const cleanTopic = String(topic).replace(/[^a-zA-Z0-9_-]/g, '');
+  const matched = files.find(f => f.toLowerCase().includes(cleanTopic.toLowerCase()) || f.startsWith(cleanTopic.padStart(2, '0')));
+  if (!matched) {
+    console.error(`${c.red}No guide found matching '${topic}'. Run 'npx papermc-skill docs' for a list.${c.reset}`);
+    return;
+  }
+
+  const content = fs.readFileSync(path.join(docsDir, matched), 'utf-8');
+  console.log(`\n${c.green}${c.bold}--- ${matched} ---${c.reset}\n`);
+  console.log(content);
+}
+
+function printHelp() {
+  printBanner();
+  console.log(`${c.bold}Usage:${c.reset}
+  npx papermc-skill <command> [options]
+
+${c.bold}Commands:${c.reset}
+  ${c.cyan}create [name]${c.reset} / ${c.cyan}init [name]${c.reset}   Scaffold a modern Paper & Folia plugin project
+  ${c.cyan}install-skill [--global]${c.reset}     Install the AI skill into workspace (.agents) or global (~/.gemini)
+  ${c.cyan}docs [number|keyword]${c.reset}        Browse or print documentation guides
+  ${c.cyan}help${c.reset} / ${c.cyan}--help${c.reset}                Display this help screen
+  ${c.cyan}--version${c.reset}                    Show version information
+
+${c.bold}Examples:${c.reset}
+  ${c.dim}# Create a new Paper plugin in current directory${c.reset}
+  npx papermc-skill create MyAwesomePlugin
+
+  ${c.dim}# Install AI skill globally for your coding agent${c.reset}
+  npx papermc-skill install-skill --global
+
+  ${c.dim}# View the Adventure API and MiniMessage guide${c.reset}
+  npx papermc-skill docs adventure
+`);
+}
+
+// CLI Router
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0] || 'create';
+
+  switch (command) {
+    case 'create':
+    case 'init':
+    case 'new':
+      await handleCreate(args[1]);
+      break;
+    case 'install-skill':
+    case 'install':
+    case 'skill':
+      await handleInstallSkill(args.slice(1));
+      break;
+    case 'docs':
+    case 'doc':
+    case 'guide':
+      handleDocs(args[1]);
+      break;
+    case '--version':
+    case '-v': {
+      const pkg = JSON.parse(fs.readFileSync(path.join(ROOT_DIR, 'package.json'), 'utf-8'));
+      console.log(`papermc-skill v${pkg.version}`);
+      break;
+    }
+    case 'help':
+    case '--help':
+    case '-h':
+    default:
+      if (command.startsWith('-')) {
+        printHelp();
+      } else {
+        await handleCreate(command);
+      }
+      break;
+  }
+}
+
+main().catch((err) => {
+  console.error(`\n${c.red}Error:${c.reset}`, err.message);
+  process.exit(1);
+});