# Setup Platform

> Configure (or reconfigure) the target Minecraft server stack AND the project identity for this plugin — platform (Paper/Spigot/Folia/Velocity/…), Minecraft version, Java version, build tool, API coordinates, plus plugin.yml metadata (name, package/group id, version, description, authors, contributors, website, prefix) — and record it all to .mcplugin/config.yml. Use this whenever the user wants to pick or change their platform / Minecraft version / build tool / plugin name / package / authors, before scaffolding, or when a build fails from a version/Java/coordinate mismatch. Run before /scaffold.

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

---


# Configure the target server stack

This skill writes one file: **`.mcplugin/config.yml`** — the single record of the plugin's
target stack **and identity** that every other skill reads. It does not generate project code
(that's `/scaffold`). Keep it fast: ask only what you can't safely infer.

Always ground your answers in the references — do **not** rely on memory for version/Java/
coordinate facts, which changed in 2026:
- `../../references/api/VERSION.md` — version→Java→api-version matrix, 2026 changes
- `../../references/platforms.md` — platform choice and trade-offs
- `../../references/build-systems.md` — repositories, coordinates, shading
- `../../references/project-config.md` — the full config schema + identity/metadata fields

(If those relative paths don't resolve — e.g. a global install — `Glob` for
`**/references/api/VERSION.md` and read from there.)

## Phase 1: Read context

- Read `.mcplugin/config.yml` if it exists — this may be a reconfigure. Show the current stack
  and confirm what's changing rather than starting from scratch.
- Read the three reference files above so your options and derived values are accurate.
- If the user passed args (e.g. `paper 1.21.4`), treat them as the platform/version answers and
  skip those questions.

## Phase 2: Ask the stack decisions

Use `AskUserQuestion`. Ask only what's still unknown after Phase 1 / args.

1. **Platform** — options: `Paper (recommended)`, `Spigot`, `Folia`, `Velocity (proxy)`,
   with a short trade-off for each from `platforms.md`. If the user picks Folia or a proxy,
   note that it changes how features are written and confirm they meant it.
2. **Minecraft version** — offer the current stable and the dominant classic line as concrete
   options, e.g. `26.1.x (newest, Java 25)`, `1.21.x (widest ecosystem, Java 21)`, plus
   "other (I'll type it)". If the user wants the *latest* and you have `WebFetch`, verify the
   current build at https://papermc.io/downloads/paper and state what you found; otherwise use
   the newest version named in `VERSION.md` and tell the user to confirm against that page.
3. **Build tool** — options: `Maven`, `Gradle (Kotlin DSL)`, `Gradle (Groovy)`. If they don't
   care, default to **Maven** (simplest for plugins) and say so.

## Phase 3: Derive the rest (don't ask)

From platform + MC version, derive using the references — never guess:
- **`version_scheme`**: `year` for `26.x`+ (2026 year-based), `classic` for `1.x`.
- **`java_version`**: from the matrix in `VERSION.md` (25 for 26.1.x, 21 for 1.21.x, 17 for
  1.18–1.20.4, …).
- **`api_version`**: the `plugin.yml` value (e.g. `26.1` or `1.21`).
- **`paper_api_version`** (or spigot/velocity coordinate): the exact version string for the
  chosen build tool and scheme, per `build-systems.md`. Remember the 26.x Paper format differs
  by build tool — Gradle wants `26.1.2.build.+`, Maven wants a range like `[26.1.2.build,)`.

If any derived value is uncertain because the version is newer than the references, say so
explicitly and point the user at the live source, rather than inventing a coordinate.

## Phase 3b: Project identity & plugin.yml metadata

Capture the project's identity and descriptor metadata now, so `/scaffold` can generate without
re-asking. Follow `../../references/project-config.md` for the exact fields and the
asked-vs-derived split. Pre-fill from any existing `.mcplugin/config.yml`: on a pure stack
reconfigure where identity is already set, just ask "keep the existing project details?" and move on.

Ask **each field as its own question** with `AskUserQuestion` (one field per question, a sensible
default as the first option — the user picks it or types their own via "Other"), grouped a few at a
time: plugin name · base package (group id) · version `[1.0.0]` · main class `[= plugin name]` ·
description · author(s) · contributors `[none]` · website `[none]` · console prefix `[none]`.
Then **derive** `artifact_id` (name lowercased), `package` (`group_id.artifact_id`, unless the user
overrides), and `main` (`package.main_class`). Leave optional fields blank if skipped — `/scaffold`
keeps them present but empty in `plugin.yml`.

## Phase 4: Write `.mcplugin/config.yml`

Create `.mcplugin/` if needed and write the full schema from `project-config.md` — stack **and**
identity — preserving any existing field you didn't change:

```yaml
# Stack + identity for this plugin — written by /setup-platform (or /start). Skills read this.
platform: paper
mc_version: "1.21.4"
build_tool: maven
version_scheme: classic                     # derived
api_version: "1.21"                         # derived
java_version: 21                            # derived
paper_api_version: "1.21.4-R0.1-SNAPSHOT"   # derived
plugin_name: DungeonCrawler
group_id: com.lucastudios
plugin_version: "1.0.0"
description: "Diablo-style dungeon crawler on a vanilla Minecraft Java Edition client"
authors: [Lucastudios]
contributors: [Vaguestan Development]        # blank if none (kept, not omitted)
website: "lucastudios.com"                   # blank if none (kept, not omitted)
prefix: "DungeonCrawler-MC"                  # blank if none (kept, not omitted)
main_class: Main
artifact_id: dungeoncrawler                 # derived
package: com.lucastudios.dungeoncrawler     # derived
main: com.lucastudios.dungeoncrawler.Main   # derived
```

Writing this file is the skill's purpose — do it without a separate "may I write?" prompt. Then
show the resolved stack + identity back in a short table.

## Phase 5: Hand off

State the required JDK plainly (e.g. "This target needs **Java 21** — make sure `java -version`
reports 21+"). Then:
- If no plugin project exists yet (no `pom.xml`/`build.gradle` and no `src/main/java`), suggest:
  "Run `/scaffold` to generate the plugin project for this stack."
- If a project already exists, suggest rebuilding with `/build` to catch mismatches.

Do not auto-run the next skill.