# Start

> First-time entry point for building a Minecraft plugin with this toolkit. Detects where the project is, asks what the user wants to build, then configures the target stack (platform, Minecraft version, build tool → .mcplugin/config.yml) and routes them to scaffolding. Use this when someone is new to the toolkit, says 'help me make a Minecraft plugin', or isn't sure where to begin. Makes no assumptions — it asks first.

- Skill: `itamarb2010-jpg/start` (Agent Skill)
- Install (CLI): `npx skillmds@latest add itamarb2010-jpg/start`
- Raw SKILL.md: https://api.skillmd.com/api/skills/itamarb2010-jpg/start/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/start

---


# Guided start

The entry point for building a Minecraft plugin. It detects state, asks where you are,
**configures the target stack** (writes `.mcplugin/config.yml`), then **offers to scaffold the
project**. It won't silently run steps: at the config→scaffold boundary it asks first, and beyond
scaffolding it hands off (features, build, run are each their own command).

Ground every version/Java/coordinate fact in the references — don't rely on memory (Minecraft
changed materially in 2026). Read as needed (relative to this skill; `Glob` `**/references/...`
as a fallback):
- `../../references/api/VERSION.md` — version→Java→api-version matrix, 2026 changes
- `../../references/platforms.md` — platform trade-offs
- `../../references/build-systems.md` — coordinates per build tool

## Phase 1: Detect project state (silently)

Use this to tailor recommendations; don't dump it:
- **Stack configured?** Read `.mcplugin/config.yml` if it exists (this may be a returning user).
- **Project scaffolded?** `Glob` `pom.xml`, `build.gradle*`, `src/main/java/**/*.java`.
- **Descriptor present?** `Glob` `**/plugin.yml` / `**/paper-plugin.yml`.
- **Existing/foreign plugin?** Java/build files but no `.mcplugin/config.yml` = the user brought
  a project the toolkit hasn't been told about yet.

## Phase 2: Ask where the user is

Use `AskUserQuestion`:
- **Prompt**: "Welcome — let's build a Minecraft plugin. Where are you starting from?"
- **Options**:
  - `A) Brand new` — No project yet. Make a plugin from scratch.
  - `B) Have an idea` — Knows roughly what it should do; set it up and build it.
  - `C) Existing project` — Already has plugin code/build files.
  - `D) Just configure` — Only wants to set/change platform, MC version, or build tool.

Wait for the answer; validate against Phase 1 (e.g. picked A but code exists → point that out).
For **B**, ask them to describe the plugin in one sentence (what it does in-game) and reflect it
back before continuing.

## Phase 3: Configure the stack + project identity

End this phase with a written `.mcplugin/config.yml`. This is the same configuration
`/setup-platform` performs — done here so a new user answers everything in one flow.

- **If `.mcplugin/config.yml` already exists** (returning user): show the current stack and ask
  (`AskUserQuestion`) "Keep this stack, or change it?" Keep → skip to Phase 4. Change → ask the
  questions below.
- **Path C (existing project)**: infer platform, MC version, Java, build tool, and identity from
  `pom.xml`/`build.gradle*`/`plugin.yml`; summarize what you found and ask the user to **confirm
  or correct** it — don't ask from scratch.
- **Paths A / B / D** (and C when nothing to infer): ask with `AskUserQuestion`, only what's
  still unknown:
  1. **Platform** — `Paper (recommended)`, `Spigot`, `Folia`, `Velocity (proxy)`, with a short
     trade-off each from `platforms.md`. If they pick Folia or a proxy, note it changes how every
     feature is 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 they want the *latest* and you have `WebFetch`, verify the
     current build at https://papermc.io/downloads/paper and say what you found; else use the
     newest version in `VERSION.md` and tell them to confirm there.
  3. **Build tool** — `Maven`, `Gradle (Kotlin DSL)`, `Gradle (Groovy)`. No preference → default
     **Maven** and say so.

Then gather the **project identity & plugin.yml metadata** (per
`../../references/project-config.md`) by asking **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]`. For path C, pre-fill each default from the
existing `pom.xml`/`plugin.yml`.

**Derive the rest from the references — never guess:** stack values `version_scheme` (`year` for
26.x+, `classic` for 1.x), `java_version`, `api_version`, `paper_api_version` (exact coordinate for
the build tool + scheme — Gradle wants `26.1.2.build.+`, Maven a range like `[26.1.2.build,)`;
classic is `1.21.4-R0.1-SNAPSHOT`); and identity values `artifact_id` (name lowercased), `package`
(`group_id.artifact_id` unless overridden), `main` (`package.main_class`). If a value is uncertain
because the version is newer than the references, say so and point to the live source rather than
inventing it.

Create `.mcplugin/` and write the full schema from `project-config.md` (this write is the phase's
purpose — no separate "may I write?"); leave optional fields blank if the user skipped them:

```yaml
# Stack + identity for this plugin — written by /start (or /setup-platform). 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
```

Then show the resolved stack + identity in a short table and **state the required JDK plainly**
(e.g. "This target needs **Java 21** — make sure `java -version` reports 21+").

## Phase 4: Offer to continue into scaffolding

The stack is configured. Decide the next move *with the user* — don't silently barrel ahead, and
don't silently stop. Ask explicitly (`AskUserQuestion`):
- **Prompt**: "Stack saved ({platform} {mc_version}, {build_tool}). Scaffold the project now, or
  stop here?"
- **Options**:
  - `Scaffold now` — generate the project skeleton straight away.
  - `Stop here` — I'll run the next step myself.

**If `Scaffold now`:** run the scaffolding flow defined by the `/scaffold` skill rather than
improvising — read `../scaffold/SKILL.md` (`Glob` `**/skills/scaffold/SKILL.md` as fallback) and
follow it: gather any missing project identity (plugin name, base package), fill the templates,
and **show the build file + `plugin.yml` for approval before writing** (never skip that approval
just because you're chaining from `/start`). After scaffolding, show the remaining arc and stop.

**If `Stop here`:** reply with a single line — "Type `/scaffold` to begin." — and stop.

Either way, show the arc for reference and point to `/help` if they're unsure what a skill does:
1. `/scaffold` — generate the buildable project skeleton.
2. Implement — `/add-command`, `/add-listener`, `/add-config`, `/add-gui`, `/add-storage`.
3. `/build` → `/run-server` → `/plugin-review`.

**Do not** auto-run anything past scaffolding — features, build, and run each need the user's
specific intent, so hand off to them.

## Edge cases
- **Already fully set up** (config + project exist and they chose "keep"): skip ahead —
  "You're set up: {platform} {mc_version}, {build_tool}. Add a feature (`/add-command`, …),
  `/build`, or `/run-server`. Or tell me what the plugin should do."
- **User doesn't fit an option**: let them describe their situation and adapt.