Skip to main content

AI Prompts and Skills

Essentials. Day-to-day work runs through a small set of /commands you invoke in Claude Code. They are thin composers over reusable fragments (.claude/fragments/, the primitives) and auto-firing skills (.claude/skills/, the atomic operations). The canonical source lives in the le-workspace root and is synced (tracked) into every repo, so any clone is self-sufficient — edit only the le-workspace canonical copy then run sync-tooling.sh; never hand-edit an AUTO-SYNCED file inside a child.

CommandUse it when
/dev-issue <id>work one GitLab issue end-to-end — the default entry point
/designshape a medium/large topic into an ordered issue set before any code
/deliverimplement a validated issue series autonomously (local commits, no push)
/finalize-seriespre-push gate: neutral review of the series across repos → push → To release
/releasetag & publish a multi-repo release
/reviewneutral code review of the current branch (reports only)
/fix-mr-commentsapply MR reviewer feedback
/epicbig topic: chain design → deliver → finalize-series → create-test-issue

Mental model: design → (dev-issue │ deliver) → finalize-series → release. A code review is always a mandatory neutral subagent; an autonomous fix-loop is capped at 5 rounds then stops and waits; per-stack build/version rules live in the _stack-dispatch fragment. The full picture is in the Workflow map below; the precise per-item reference is further down. Supported assistant today: Claude Code (to wire another, see Re-adding another AI provider).

💡 Prerequisite (Claude Code): Commands and skills under .claude/ are auto-discovered. The repository's CLAUDE.md is the entry guide for Claude Code agents and points to AGENTS.md — the canonical project rule source for all AI assistants.

Workflow map​

Current architecture (implemented in #733)​

This is the implemented command/skill architecture, validated against an AI-engineering critique and a behaviour-coverage audit of the prior prompts:

  • One read-only primitive panel-report(context, roles, output-schema) over a shared role-panel pass (fan-out role subagents → synthesize). ANALYZE and REVIEW are named presets of it, not separate primitives. ANALYZE: author context, scope topic→issue-set or issue→impl-plan, human-gated. REVIEW(scope: branch|commit|series): neutral non-author context, outputs findings; the series scope is incremental (integration + conformity, not a re-review of per-commit diffs already cleared).
  • APPLY-CHANGE (code → build) is split out of IMPLEMENT-ONE (version → APPLY-CHANGE → CHANGELOG → naming → commit). Fix loops call APPLY-CHANGE only — never the full IMPLEMENT-ONE (which would re-bump the version and duplicate the CHANGELOG entry).
  • completion-policy is a shared primitive (one fragment): the local / beta-move-now / beta-wait × series / solo rules deciding commit/push/To-release timing — used by dev-issue, deliver and finalize-series (epic via deliver/finalize). On a branch/MR, To-release and the beta deploy tie to the merge to main, not the branch push.
  • Bounded feedback loops: REVIEW → Must Fix → APPLY-CHANGE (flush) → REVIEW, capped at 5 — on the cap, no progress, or a new Must-Fix the loop stops and waits for the human. In standalone /dev-issue the review autonomy is an up-front option (report-only vs autonomous fix-loop); deliver/epic/finalize-series run it autonomously by contract. Review neutrality is mechanical: the reviewer is a mandatory separate subagent that did not author the work (the fragment text, the diff, and the _stack-dispatch table are passed into its prompt) — never an inline self-review.
  • Three layers: Judgment (the primitives) / Atomic operations (skills — some deterministic, some judgment, tagged) / Enforcement, which is two kinds: true git hooks (commit-msg; the le-workspace pre-commit cross-repo guard) and local/CI guards that are not hooks (the prepare-docs docs-build exclude; sync auto-prune + --check orphan scan; the orphan-staging / flush self-checks). The validate-branch-and-commit-naming skill mirrors commit-msg as an explanatory pre-check (it is a skill, not a hook). Human validation gates are control-flow in the commands, not enforcement.
  • Implementable form — build-time inlining (the key decision): each primitive is a canonical prompt fragment under .claude/fragments/, edited once. The Claude Code runtime does not transclude linked files, so to keep correctness from depending on the agent voluntarily opening 2–3 levels of links, sync-tooling.sh inlines each command's full transitive fragment closure into the command at sync time. The shipped command (in every child's .claude/commands/) is therefore self-contained — one file, no runtime dereference. Fragments are a build input, not a shipped file type (an older sync's fragment-as-file is pruned). prepare-docs.mjs needs no change — the whole .claude/ dir is excluded from the docs build.
  • Renames: /design-loop → /design, /ship-review → /finalize-series, /create-release → /release. condense-changelog lives only in /release (the per-commit fragments stay until the tag freezes the version).

Architecture — three layers:

Pipeline — commands compose the primitives (with feedback loops):

Behaviours to carry into the prompt fragments (must not lose in the rewrite). The diagram is a map, not the full spec — these stay in the command/fragment prose: ANALYZE depth calibration (trivial / single-feature / umbrella) + the LE-specific UX analysis (Item.java item tables, the manual Mineskin/NovaSkin HEAD-texture step) + the step-breakdown dependency graph; the full REVIEW checklist (architecture · exceptions · logging · events · database · CHANGELOG audit · version-bump-segment-matches-Conventional-type · orphan .translation-staging.json); the [NEEDS CLARIFICATION: …] inline-assumption convention; the multi-repo discipline (dependency order — producer of a shared contract before its consumer — and keeping that contract coherent via the relevant domain skill, not a version pin); the Stack-dispatch table as the substrate of IMPLEMENT-ONE / REVIEW (translations LE-only, Python no -SNAPSHOT/no per-version tag, Go web build, wiki no build); and the /release joint sub-steps (poll publish-to-artifactory before the LEPSU pom-pin + tag, stop on pipeline failure, the DEPLOY_DOCS trigger condition).

MCP servers​

Beyond commands and skills, the AI assistants rely on two MCP servers, declared in .mcp.json and enabled per project:

  • gitlab — read/write access to GitLab issues and merge requests; backs every issue/MR skill below. Token via the GITLAB_PERSONAL_ACCESS_TOKEN env var (see Setup Development Environment).
  • context7 — fetches up-to-date library/API documentation (Bukkit/Spigot/Paper here, and the libraries of the companion le-agent / le-mcp / le-play-server-utils repos). Query it to confirm current API signatures instead of relying on the model's training memory. Remote HTTP server, no token required.

How to invoke a command​

In Claude Code, type /<command-name> [<parameters>] in the chat input. Example: /dev-issue 123 to start working on issue #123. Claude Code reads the canonical .claude/commands/<name>.md file directly.

How skills trigger​

Skills don't need explicit invocation — the assistant reads each skill's frontmatter description field and fires the matching skill when your request aligns with it. You can also reference a skill by name in your request to force its use (e.g. "use bump-version").

Parallel agents and git worktrees​

When you want several AI agents to work in parallel on different issues, run each in its own git worktree so they don't fight over the same working tree. This is the only reason to reach for a worktree — for ordinary sequential work, staying on main or a normal branch is simpler.

  • When to use: parallel or background agents on different branches. Not for the common one-issue-at-a-time flow.
  • How: in an interactive Claude Code session, prefer the native EnterWorktree / ExitWorktree tools, or pass isolation: "worktree" to the Agent / Workflow tools for truly concurrent background agents. The explicit git form is: 
    git switch main ; git pull
    git worktree add .claude/worktrees/<type>-<issue>-<kebab> -b <type>/<issue>-<short-kebab-desc>
    # … work inside that directory …
    git worktree remove .claude/worktrees/<type>-<issue>-<kebab>
    .claude/worktrees/ is already gitignored, and the branch name is identical to a normal branch — naming rules apply unchanged.
  • From the workspace root: in the multi-repo le-workspace layout, route first (the route-issue skill) to find the child the work belongs in, then create the worktree inside that child — a worktree is per-clone, so it lives under the resolved child's .claude/worktrees/, not the workspace root.
  • Config & hooks carry over: a worktree shares its clone's git config (it reads the same .git/config), so core.hooksPath and hooks.requireIssueRef apply and the commit-hygiene hooks run there automatically — nothing to re-enable. The only thing that does not follow is the gitignored .claude/settings.local.json (it isn't tracked); that is expected and usually fine.
  • Caveat: no in-game local testing from a worktree — the run/ Paper servers and the .run/*.xml IntelliJ configs live in the main clone. Build and compile work fine from a worktree; for in-game testing use the main clone or the beta-test server.

No extra library or MCP is needed — git worktrees are built into git and supported natively by Claude Code.

Commands Reference​

Commands are thin composers over the fragments (the reusable primitives) plus the skills. The per-command summaries below name which fragment each step delegates to.

Dev Issue​

File: .claude/commands/dev-issue.md

Use when: Starting work on a single GitLab issue (bug fix or feature), end-to-end.

What it does:

  1. Route (route-issue) to the right repo, then fetch (fetch-gitlab-issue).
  2. Up-front questions (once): the test mode (local vs beta) + completion timing (if beta); the review autonomy (report-only vs autonomous fix-loop); the mandatory main vs branch vs worktree choice (with an uncommitted-changes guard); the Conventional commit type.
  3. Analyze — the ANALYZE preset of _panel-report (dev profile, sections 4.1–4.6 with the depth calibration), then a plan-validation gate: no code is written without an explicit go ([NEEDS CLARIFICATION: …] for unconfirmed assumptions).
  4. Record & implement — flips Status: In Progress + records the plan as a comment (one combined OK), then IMPLEMENT-ONE (version bump if published, code + build, flush translations, CHANGELOG, wiki, naming, local commit). A fast path trims the analysis for trivial fixes but keeps version / translations / naming / commit.
  5. Review — the REVIEW preset (scope = branch) in a fresh neutral subagent; report-only or bounded auto-fix per the up-front choice.
  6. Complete — _completion-policy: local test wait / beta / series timing → push + Status: To release (the issue is closed later, at release time, by Release).

⚠️ Requires the issue id as input. It will stop and ask for it if not provided.

Review​

File: .claude/commands/review.md

Use when: Reviewing code changes on the current branch before creating or merging a Merge Request.

What it does:

  1. Fetches issue details via fetch-gitlab-issue.
  2. Identifies all changed files compared to main.
  3. Checks branch and commit naming via validate-branch-and-commit-naming (Conventional format + no GitLab auto-close keywords).
  4. Verifies the version increment via check-version-published and that the bump segment matches the Conventional type chosen for the branch.
  5. Validates the CHANGELOG.md entry format and content.
  6. Reviews the code against the full project checklist: architecture layers, exceptions, player messages, logging, events, database, documentation, quality. If you also authored the changes, it runs the critique in a fresh subagent that did not write them (no self-approval bias).
  7. Verifies no orphan .translation-staging.json remains at the project root.
  8. Runs the build.
  9. Produces a structured review report (✅ Good, ⚠️ Suggestions, ❌ Must Fix, ❓ Questions).

⚠️ Requires the issue id as input.

Fix MR Comments​

File: .claude/commands/fix-mr-comments.md

Use when: Applying changes requested by reviewers after a Merge Request review on GitLab.

What it does — this is REVIEW(human findings) → APPLY-CHANGE, looped:

  1. Invokes fetch-mr-comments to retrieve all MR comments from GitLab (via the GitLab MCP server) and produce .github/tmp/mr-comments.md.
  2. For each unresolved comment: analyzes the request, proposes a plan, applies the fix via _apply-change (code + build), running analyze-server-log → diagnose-log-level first for runtime-behaviour comments, and updating CHANGELOG/wiki if a comment warrants it.
  3. Flushes staged translations, then produces a summary (+ naming validation for new commits).

⚠️ Requires the GitLab MCP server (token via the GITLAB_PERSONAL_ACCESS_TOKEN env var). See Setup Development Environment — GitLab personal access token.

Release​

File: .claude/commands/release.md (was create-release)

Use when: Publishing a release across the workspace (LasersEnigma, LE Play Server Utils, le-room-organizer, le-agent, le-mcp, wiki).

What it does:

  1. Inventories the six workspace clones — presence (an absent clone is reported, never silently skipped), uncommitted changes, unpushed commits, version vs existing tags, CHANGELOG top section — and presents one recap table.
  2. Decides the release set: LE tag, LEPSU tag, le-room-organizer tag, le-agent / le-mcp pushes (main auto-deploys), wiki push — including the docs special case (trigger a DEPLOY_DOCS=true pipeline on lasersenigma when wiki commits would otherwise not be republished).
  3. Asks whether breaking changes require updates to LEPSU (in-workspace) or Skytale Map Editor (manual — SME and particleanimlib stay out of the automated scope).
  4. Condenses the CHANGELOG of every repo in the release set (condense-changelog lives here only), presents the recap, waits for explicit user validation, then executes the tags/pushes itself in the proven joint order (LE tag → poll publish-to-artifactory → LEPSU update LE pin → LEPSU tag → …), stopping on any pipeline failure, monitoring by polling the GitLab MCP in the foreground (no raw REST calls).
  5. Post-release, performed by the agent: closes the released issues via the GitLab MCP (list validated by the user first, Status: label removed on close — see Issue management) and checks the deployed servers with the read-only check-server-status skill. Reminds the remaining manual steps (Discord changelog, SpigotMC update).

⚠️ Never tags or pushes before the explicit user validation of the release recap; once validated, it executes the actions itself instead of handing the commands back.

⚠️ Only project maintainers can create tags. See Development Process — Tag Creation.

Design​

File: .claude/commands/design.md (was design-loop)

Use when: Shaping a medium or large topic before implementation. Skip for trivial one-file changes (use Dev Issue directly).

What it does — composes the ANALYZE preset (design profile):

  1. Understands the ground truth first — reads the relevant code, wiki page(s) and related issues, fanning out read-only Explore subagents for a broad sweep.
  2. Analyses the topic through three distinct lenses — functional analyst, technical architect, lead dev (three bounded parallel subagents for a large topic, inline for a medium one).
  3. Synthesises them into one focused response — open questions, problems/risks, a recommended direction (pick one), and the few real alternatives — not three raw dumps; unconfirmed assumptions surfaced as [NEEDS CLARIFICATION: …].
  4. Loops until no open point remains.
  5. Gates on explicit validation (and only that — no bundled new scope).
  6. Decomposes the work into an ordered issue set via create-issue, then hands off to Deliver / Epic.

Deliver​

File: .claude/commands/deliver.md

Use when: Implementing a validated issue series autonomously (typically after Design).

What it does:

  1. Asks the main-vs-branch-vs-worktree question + test mode once for the whole series.
  2. For each issue in dependency order, runs IMPLEMENT-ONE without the human gates (design already validated): Status → In Progress, version check/bump, code+build, stage/flush translations, one CHANGELOG entry per issue, wiki, naming, local commit (no push).
  3. Runs the REVIEW preset (scope = commit) in a bounded auto-fix loop (_apply-change → re-REVIEW) before the next commit.
  4. Stops only on a genuine blocker (ambiguous decision, spec contradiction, unfixable build, destructive/outward action).
  5. Hands off to Finalize Series for the global review + push.

Finalize Series​

File: .claude/commands/finalize-series.md (was ship-review)

Use when: Before pushing a series of local commits across one or more repos (wiki included).

What it does — composes the REVIEW preset (scope = series):

  1. Inventories the unpushed commits across every clone this work touched — only those; unpushed commits in a clone you didn't change belong to a concurrent agent and are left alone.
  2. Runs a global REVIEW(series, incremental) of the unpushed series across repos (fresh neutral subagents per repo or dimension), wiki doc accuracy included — integration + cross-issue concerns, not a re-review of per-commit diffs already cleared in deliver.
  3. For a big multi-issue topic, runs a functional-conformity check mapping each requirement → CONFORMS / PARTIAL / MISSING / DEVIATES.
  4. Reports blockers / non-blocking, fixes low-impact findings (bounded _apply-change), then on explicit validation pushes each clone separately. (No condense-changelog here — that runs at Release only.)
  5. Moves each issue's Status: In Progress → Status: To release (beta-wait aware) via edit-issue — never closes (that is Release at tag time).

Epic​

File: .claude/commands/epic.md

Use when: A big multi-issue topic, to chain the whole pipeline. Not for small topics — use Dev Issue.

What it does: a thin orchestrator chaining, with the human gates between phases:

  1. Design — three-lens design → explicit-validation gate → issue set. (Skipped if an existing ordered issue-id list is given — epic-from-issue-ids.)
  2. Deliver — autonomous implementation, per-commit review, local commits.
  3. Finalize Series — global review + conformity → validated push → issues to To release.
  4. create-test-issue — the final manual in-game test checklist.

Releasing (tags) stays separate — run Release when ready. Scales down: skip phases that don't fit. The expensive phases use a few bounded subagents, not the heavy Workflow fan-out (reserved for an explicit "ultracode" request).

Fragments Reference​

Reusable prompt primitives under .claude/fragments/, edited once canonically and inlined into the referencing commands at sync time (a build input — not invoked directly and not shipped as standalone files into children; the shipped commands are self-contained). The canonical fragments live in le-workspace.

_role-panel​

One multi-role subagent pass: fan-out the given roles → synthesize into one structured result. The shared mechanism under _panel-report. Read-only; looping/mutation belong to the caller.

_panel-report​

The read-only panel-report(context, roles, output-schema) built on _role-panel. Two presets: ANALYZE (author context, human-gated — profile design: three kept-separate lenses → Open questions / Problems / Suggestions-pick-one / Alternatives → validation gate; profile dev: sections 4.1–4.6 incl. UX Item.java/HEAD textures and the 4.6 dependency graph; the [NEEDS CLARIFICATION: …] convention; depth calibration) and REVIEW (neutral non-author context — scope branch/commit/ series, series incremental; the full checklist — architecture, code conventions, exceptions, logging, events, database, documentation + sibling-push, security, quality, naming/version/CHANGELOG audits, orphan staging — plus the ✅ Good / ⚠️ Suggestions / ❌ Must Fix / ❓ Questions template). REVIEW neutrality is mandatory (a separate non-author subagent, fragment text + diff passed in); the autonomous fix-loop is capped at 5 then stops and waits for the human.

_stack-dispatch​

The per-stack mapping (LE / LEPSU / Python / Go / wiki) for build, version file + bump, CHANGELOG and translations, plus the multi-repo rules (pointing at the workspace AGENTS.md Multi-repo issue section). Read by _implement-one, _apply-change, _panel-report and the commands — kept as its own fragment so it isn't trapped inside a command (no layer inversion, no anchor-breaks-on-rename).

_apply-change​

The smallest mutation unit: code → build (translations staged for LE). The unit a review fix-loop re-runs — deliberately no version bump / CHANGELOG / commit (those would duplicate per fix).

_implement-one​

Implement one issue to a local commit: Status→In Progress → version (bump if published) → _apply-change → flush translations → CHANGELOG → wiki (+_sidebar.md) → naming → commit. Stack-dispatch aware; never pushes (the caller's _completion-policy does).

_completion-policy​

Decides commit/push/status timing from the test mode (local / beta-move-now / beta-wait) and series vs solo: series → commit local, no push (batched at finalize-series); solo local → wait for the manual test (on failure → analyze-server-log → diagnose-log-level) then push + To release; etc. On a branch/MR, To-release and the beta deploy tie to the merge to main.

Skills Reference​

22 atomic skills under .claude/skills/. Each fires automatically when the assistant's task matches its description. Several prompts above invoke these skills internally; you can also use any of them standalone.

Shared vs repo-local. Most skills are shared (canonical in le-workspace, synced into every repo) — including add-changelog-entry and condense-changelog, which are stack-agnostic. The version skills check-version-published / bump-version are repo-local (the version source differs per stack: gradle.properties here, pom.xml in LEPSU, VERSION in le-room-organizer; the Python repos have no per-version tag). Two domain skills are repo-local too: lepsu-add-flyway-migration (LEPSU) and gro-csv-roundtrip-check (le-room-organizer). The count above is the LE set.

fetch-gitlab-issue​

Pulls a GitLab issue (title, description, labels and discussion comments) via the GitLab MCP server (get_issue + list_issue_discussions). Returns a fix/feature verdict from the Type: label or inferred from the issue body/comments. Warns when the issue contains Scope: labels outside Scope: Lasers-Enigma plugin. Comments are now retrieved directly — no need to ask the user to paste them.

Used by: dev-issue, review, edit-issue (to build a before/after diff).

route-issue​

Maps a GitLab issue to the workspace repo(s) the work belongs in. All issues live on lasersenigma/lasersenigma, but many concern another repo, span several, or are non-dev — this reads the issue's Scope: labels + body against a Scope→repo table and returns the affected clone(s) + the cwd to launch in, flagging non-dev (game/level design, Discord, website, video, recruitment) and external (SME, NESB) work that has no workspace clone. Read-only.

Used by: dev-issue (step 0), deliver, triage.

create-issue​

Creates a new GitLab issue on lasersenigma/lasersenigma from a conversation. The skill collects title / description / labels, shows the composed issue to the user and waits for explicit validation, then calls the GitLab MCP create_issue tool. The returned issue carries its IID and web_url directly (no intermediate file). Suggests labels from the standard project taxonomy (Type:, Scope:, Priority:) and warns when no Type: label is set — the fix/feature verdict drives downstream dev-issue / bump-version / add-changelog-entry decisions.

⚠️ Requires the GitLab MCP server with a token of scope api (read+write — read_api is not enough to create). See Setup Development Environment — GitLab personal access token.

⚠️ Creating an issue is irreversible — the skill never creates without explicit user validation of the composed content.

create-test-issue​

Creates a GitLab issue whose body is a short manual in-game test checklist (markdown checkboxes) for a just-shipped topic, on lasersenigma/lasersenigma via the MCP create_issue tool. One checkbox = one action + its expected result; observable behaviour only; grouped by issue/feature. Filed at the end of a medium/large topic (the final step of Epic) so the user can validate each test on the beta server. Pairs with create-issue for the mechanics and the explicit-validation step.

⚠️ Requires the GitLab MCP server with a token of scope api.

edit-issue​

Edits an existing GitLab issue (title, description, labels, state close/reopen) from a conversation. Reads the current state via the MCP get_issue tool, shows a clear before/after diff and waits for explicit validation, then calls the MCP update_issue tool. Labels are a full replacement (the API takes the complete label set, not add/remove) — the skill starts from the current labels and sends the merged result, respecting cardinality. Description edits are full replacements too — the skill rebuilds the full description when the user asks for a partial change.

⚠️ Requires the GitLab MCP server with a token of scope api.

⚠️ Use this skill (with state_event: close) to close an issue programmatically. Never use a GitLab auto-close keyword (Close #N, Fixes #N, …) in a commit message — forbidden by project convention (see validate-branch-and-commit-naming).

comment-issue​

Posts a comment (note) on an existing GitLab issue via the MCP create_issue_note tool, after showing the composed comment and waiting for explicit validation. This is the project's sanctioned way to add an automated comment — e.g. the validated plan recorded by dev-issue. For label / title / description / state changes, use edit-issue instead.

Used by: dev-issue.

⚠️ Requires the GitLab MCP server with a token of scope api (posting a note is a write).

triage​

Triages the open issues of the project against the Issue management cardinality rules (exactly one Type: / Status: / Prio:, at least one Scope:). Lists issues via the MCP list_issues tool (scope="all"), flags missing/duplicate labels and parasite labels outside the canonical list, reports them, then proposes and applies re-labels via edit-issue — per-issue explicit validation, never a batch write. Cannot detect non-Issue work items (Task/Epic) — points to the relevant Detection view instead.

Also runs a git-log cross-check for Status-label drift: it parses the (#NNN) references from the commit subjects on main and flags (a) issues referenced by a commit on main but still Status: In Progress → proposes Status: To release; (b) issues referenced only by commits contained in a published tag but still open → proposes close + Status-label removal. Best-effort: commits missing their issue reference escape the check.

⚠️ Scope read_api is enough to report; scope api is required to apply fixes.

fetch-mr-comments​

Fetches the review discussion of the open Merge Request associated with the current branch via the GitLab MCP server (list_merge_requests to find the open MR, mr_discussions to read its notes), then writes the report to .github/tmp/mr-comments.md (MR metadata + per-comment author / file / line / resolved status). Keeps unresolved comments by default; can include resolved ones on request. Refuses to proceed on SHA mismatch (local HEAD ≠ MR head) so the comments stay aligned with the diff. Read-only on GitLab side.

⚠️ Requires the GitLab MCP server. Scope read_api is enough for this skill (scope api is also fine and is required by create-issue / edit-issue).

Used by: fix-mr-comments.

check-version-published​

Compares gradle.properties (sans -SNAPSHOT) to git tags. Reports whether the current version is already published — in which case a bump is required and a new CHANGELOG.md section must be opened — or still in-progress, in which case CHANGELOG entries go inside the existing section.

Used by: dev-issue, review, bump-version.

bump-version​

Increments X/Y/Z in gradle.properties based on the Conventional type chosen for the branch: feat → Y, fix/refactor/perf/chore/docs/ci/build/test → Z, <type>! (breaking) → X. Always keeps -SNAPSHOT.

Used by: dev-issue.

add-changelog-entry​

Adds a single user-facing line to CHANGELOG.md in the right subsection (## Features for feat, ## Fixes for fix, ## Technical changes for perf/refactor with observable effect). Refuses to edit any published version's entries (frozen). Format: - [#<id>](url): <description>.

Used by: dev-issue.

condense-changelog​

Condenses the in-progress (untagged) CHANGELOG section so a shipped version reads as one story instead of a per-commit log: merges fragments of the same issue, factors two issues describing the same feature into a single bullet (citing both links), collapses an internal/tooling block into one "No in-game effect" line, and rewrites for concision — never touching a frozen (tagged) section. Same user-facing tone and section rules as add-changelog-entry. Especially relevant before a tag.

Used by: release (condensing now lives at release only — see the workflow map).

add-translation-code​

Adds a brand-new translation code into every <domain>.<lang>.json file (25 languages). No forceUpdatePluginVersion — fresh keys are written on first plugin load. Edit tool only — never Write / sed / script (would corrupt UTF-8 BOM in non-Latin scripts). Best for 1–2 ad-hoc codes with no other translation work in flight; for ≥ 3 codes mid-feature, prefer stage-translation.

modify-translation-value​

Changes the value of a translation code already shipped in a prior release, bundling the new wording and the mandatory forceUpdatePluginVersion marker in the same Edit per language file. Without it, admins already running the plugin keep their stored value and your edit has no effect on live servers. Best for 1–2 ad-hoc rewordings; for ≥ 3 modifications mid-feature, prefer stage-translation.

stage-translation​

Buffers a translation (add or modify) into .translation-staging.json at the project root (gitignored) mid-feature, with a mandatory context field explaining when the code fires and what each {N} semantically represents — so non-English translations don't drift into wrong literals. The actual write to the 25 language files happens later via flush-translation-staging.

⚠️ Orphan check at session start: if .translation-staging.json exists from a previous session, this skill stops and asks whether to flush it or discard it. A stale staging file from a previous session must never be silently merged with new work.

flush-translation-staging​

Reads .translation-staging.json, writes every buffered entry into all 25 language files of each affected domain in one batched pass — one Edit per file containing every staged entry for that file (e.g. 8 staged codes × 25 languages = 25 Edits, not 200). Applies forceUpdatePluginVersion automatically for modify entries. Deletes the staging file on success. Run at end-of-task, before build/commit.

Used by: dev-issue.

validate-branch-and-commit-naming​

Verifies the branch name matches <type>/<id>-<kebab-desc> and the commit subject matches <type>(<scope>)?!?: <description> (#<id>), both Conventional Commits format. Also blocks any commit message containing a GitLab auto-close keyword (Close/Closes/Fix/Fixes/Resolve/Resolves/Implement/Implements + variants followed by #X) — issues close manually at release time, never on merge.

Used by: dev-issue, review.

analyze-server-log​

Read-only investigation of a Paper server log. Auto-picks the right log file (run/*/logs/latest.log — when several servers exist, the most recently modified one wins) and surfaces the relative path so you can redirect cheaply; a caller (you, or check-server-status with a downloaded remote log) can also hand it an explicit log file path, which skips the discovery. Sizes the file first (wc -l + ripgrep counts), checks the startup verdict (Done (…)! marker and plugin enable), then runs a broad ERROR/WARN/Exception scan with line numbers and windowed Read calls to capture multi-line stack traces without loading the whole file. When you give a structural hint ("at startup", "the last 5 seconds before stop", "around 21:08", "just before the server stopped"), the skill translates it into a [start, end] line window and restricts the scan to it. Does not infer grep patterns from feature names (portal, race, cube…) — that requires reading the plugin source code, which is the caller's responsibility; the skill will ask for an explicit grep string (logger name, FQN, or log-line fragment) instead. Produces a tight structured report ending with a numbered Suggested actions list with concrete fix proposals (class, method, file:line, config key) — never applies any of them. If the investigation concludes that missing FINE/FINEST traces are blocking diagnosis, the report ends with a delegation hint to invoke diagnose-log-level. Use whenever you want to debug a recent run without browsing thousands of log lines by hand.

analyze-python-log​

Read-only investigation of a Python service loguru log (le-agent / le-mcp) — the loguru-format counterpart to analyze-server-log (which is Paper-only and would misread these). Parses text or JSON logs/latest.log, gives a startup verdict, and surfaces the service-specific failure modes — le-agent: Gemini quota, MCP timeout, auth-blacklist; le-mcp: stdout-corruption-under-stdio, wiki-refresh failure, ToolError. Read-only; ends with concrete suggested actions.

Used by: check-server-status (routes le-mcp/le-agent logs here).

diagnose-log-level​

LE-local skill (lives in lasersenigma/.claude/skills/, not in the shared manifest) — references to it in synced commands/fragments sit behind LE-only "runtime issue on a local Paper server" paths. Find out why FINE/FINEST traces from eu.lasersenigma are missing from a server log, then fix the cause interactively. Picks the same server analyze-server-log would (most recently modified run/*/logs/latest.log) unless you name one explicitly. Walks three probable causes in decreasing order of likelihood — (1) debug_level: in plugins/LasersEnigma/config.yml not set to FINEST, (2) <Logger name="eu.lasersenigma" level="..."> in log4j2.xml not set to TRACE (log4j filters out FINEST/FINER before the appender), (3) -Dlog4j.configurationFile=log4j2.xml missing from the IntelliJ run config in .run/<server>.run.xml. For each confirmed cause, it surfaces the proposed fix and asks for explicit confirmation before any edit — one question per cause, so you can accept one and refuse another. Prefers re-running ./gradlew configureLog4j over hand-editing the generated log4j2.xml (which would be overwritten on the next setup). Warns when the fix targets .run/*.run.xml since that file is committed and the change propagates to other contributors. If all three sources are correct, the skill stops and tells you the trace is genuinely not emitted by the plugin code — investigation moves to the source, not the config.

⚠️ Not for debugging exceptions with a full stack trace — finest traces add nothing. Stay in analyze-server-log in that case.

check-server-status​

Strictly read-only check of the deployed servers — play, beta, le-mcp, le-agent — through the Pterodactyl client API. Fetches the Pterodactyl credentials from the GitLab CI/CD variables of the project matching the target (the servers live on different panels: lasersenigma holds PLAY_MC_SERVER_PTERO_* / BETA_MC_SERVER_PTERO_*; le-mcp and le-agent hold their own SERVER_PTERO_*) via the GitLab MCP get_project_variable tool, queries the server state (running/offline, resources, uptime), downloads the log via the Pterodactyl files API into a temp file (never SFTP, never the websocket console), and delegates the parsing to the matching analyzer — the Paper servers (play/beta) go to analyze-server-log, the Python services (le-mcp/le-agent) to analyze-python-log, whose loguru format the Paper analyzer would misread — shared logic, no duplication. Never performs any Pterodactyl write action (no start/stop/restart/send-command), even when the server is down — an explicit user counter-order plus explicit validation is required for any exception.

Used by: release (post-release verification).

⚠️ Requires the GitLab MCP server with the variables toolset enabled (GITLAB_TOOLSETS — committed in .mcp.json; see Setup Development Environment).

run-maintenance-pipeline​

Launches a lasersenigma maintenance/ops pipeline on main by setting a single CI variable, via the GitLab MCP create_pipeline tool. Maps the user's intent to the right variable: publish / republish the docs site → DEPLOY_DOCS=true (runs build-and-deploy-docs); refresh the beta server / regenerate the server pack → GENERATE_SERVER_PACK=true (runs generate-server-pack, which stops, wipes and redeploys the beta mirror, ~2h). Verifies the expected job was actually created (not skipped) and watches it to completion. COMPRESS_WIKI is not covered — its job is still web-only and cannot be API-triggered. See CI/CD for the underlying jobs.

⚠️ Both are outward-facing deployments and GENERATE_SERVER_PACK is destructive on the beta server — the skill always confirms with the user before triggering.

⚠️ Requires the GitLab MCP server with a token of scope api (creating a pipeline is a write).

Re-adding another AI provider​

The commands and skills are plain markdown — provider-agnostic by design. Claude Code is the only assistant wired up today (it auto-discovers everything under .claude/), but another provider can be layered on without touching the canonical tooling:

  • Rules — point the provider at the repo's AGENTS.md (the canonical rule source). Most tools accept a thin entry file that redirects to it (e.g. a one-line pointer like CLAUDE.md's @AGENTS.md).
  • Workflows — if the provider doesn't read .claude/commands/ natively, add thin redirect prompts in its own convention, each opening the matching .claude/commands/<name>.md (the canonical workflow). Keep those redirects in the provider's directory, not in .claude/.
  • MCP servers — replicate .mcp.json (the gitlab + context7 servers, including GITLAB_TOOLSETS) into the provider's MCP config format.

A previous GitHub Copilot integration (.github/copilot-instructions.md + .github/prompts/*.prompt.md + .vscode/mcp.json) was removed once it fell out of use; the pattern above is what it took, should it be reinstated.