# Add Command

> Add a command to a Minecraft plugin — the executor class, tab completion, plugin.yml registration, permissions, and wiring in onEnable. Use this whenever the user wants a new /command, slash command, subcommands, argument parsing, or tab completion in their Bukkit/Paper/Spigot plugin. Reads the target stack from .mcplugin/config.yml.

- Skill: `itamarb2010-jpg/add-command` (Agent Skill)
- Install (CLI): `npx skillmds@latest add itamarb2010-jpg/add-command`
- Raw SKILL.md: https://api.skillmd.com/api/skills/itamarb2010-jpg/add-command/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: itamarb2010-jpg (https://skillmd.com/u/itamarb2010-jpg)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/itamarb2010-jpg/add-command

---


# Add a command

Wire up a working command with tab completion and permissions, matching the project's stack and
conventions. Follow the collaborative rule: propose the design, show the code, then write after
the user approves.

## Phase 1: Load context

- Read `.mcplugin/config.yml` for `platform`, `mc_version`, `version_scheme`, `package`,
  `main_class`, `plugin_name`. If it's missing, tell the user to run `/setup-platform` (and
  `/scaffold`) first.
- Read the command reference and pitfalls (relative to this skill; `Glob` as fallback):
  - `../../references/api/commands.md` — command systems, tab completion, argument patterns
  - `../../references/pitfalls.md` — the "Commands" section
- Look at existing source to match style: `Glob` `src/main/java/**/*.java`, read the main class
  and any existing command classes.

## Phase 2: Clarify the command

Ask (AskUserQuestion or plain text) only what you can't infer from the argument/description:
- **Name + aliases** (e.g. `warp`, aliases `w`).
- **What it does** and its **arguments** (e.g. `/warp <name>`, `/warp set <name>`). Note which
  args need tab completion.
- **Who can run it** — a permission node (default `<pluginname>.<command>`) and default
  (`op`/`true`/`false`), and whether it's player-only or also console/command-block.

## Phase 3: Choose the command system

Decide from the stack (explain the pick briefly):
- **Classic `plugin.yml` + `CommandExecutor`/`TabCompleter`** — universal, works everywhere,
  simplest. Default choice.
- **Paper Brigadier (`Commands` / lifecycle API)** — only on Paper 1.20.6+ and when the user
  wants typed arguments, suggestions, or nested subcommands with real parsing. Use the details
  in `commands.md`; don't guess the API surface.

## Phase 4: Implement

Generate, in the project's package:
1. A command class implementing the executor (and tab completer) with:
   - `args.length` checks before indexing; helpful usage message on bad input.
   - `sender instanceof Player` check before casting when player-only; a clear message otherwise.
   - Permission checks via the declared node.
   - Tab completion returning context-appropriate, filtered suggestions (match the current token).
2. **Register it**: add the command block to `plugin.yml` (name, description, usage, permission,
   aliases) and the permission node; in the main class `onEnable`, set the executor —
   guarding the `getCommand("x")` result against null (it's null if the name isn't in
   `plugin.yml`).

Show the new/edited files (the command class, the `plugin.yml` diff, the `onEnable` diff) and
get approval before writing.

## Phase 5: Verify + hand off

- Re-check the pitfalls: command declared in `plugin.yml`, executor set, null-guarded, args
  validated, sender type handled, permission consistent between code and `plugin.yml`.
- Suggest next steps: "`/build` to compile, then `/run-server` to try `/​{command}` in game."

Do not fabricate APIs for a Minecraft version newer than `../../references/api/VERSION.md`
documents — if unsure the method exists in the target version, say so and verify.