# Minecraft Skin Studio

> Draft, clean, preview, register, or build a Minecraft Java skin workflow, including the bundled `apps/minecraft-skinbar` menu bar app. Use when Codex needs to turn a skin idea into launcher-ready files, wire the local Minecraft Launcher skin library, render previews, or refine the repo-native macOS skin workflow.

- Skill: `arnie016/minecraft-skin-studio` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add arnie016/minecraft-skin-studio`
- Raw SKILL.md: https://api.skillmd.com/api/skills/arnie016/minecraft-skin-studio/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: Arnie016 (https://skillmd.com/u/arnie016)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/arnie016/minecraft-skin-studio

---


# Minecraft Skin Studio

Use this skill when the user wants a Minecraft Java skin workflow, not a server workflow. If the current repo contains `apps/minecraft-skinbar`, use that workspace by default when the request involves a menu bar app, app UI, or local macOS workflow changes.

## Quick Start

1. Treat the launcher-ready deliverable as a `64x64` skin PNG plus a preview image.
2. If the request touches the bundled app, run `bash scripts/run_minecraft_skinbar.sh doctor` first.
3. Run `bash scripts/run_minecraft_skinbar.sh inspect` before editing the app.
4. Use `bash scripts/run_minecraft_skinbar.sh generate` after changing `apps/minecraft-skinbar/project.yml`.
5. Use `bash scripts/run_minecraft_skinbar.sh typecheck` for a fast shell and Python syntax pass before the helper smoke test.
6. Use `bash scripts/run_minecraft_skinbar.sh test` after changing the Python helper, preview rendering, or launcher registration contract.
7. Use `bash scripts/run_minecraft_skinbar.sh build` after app UI, model, CLI wiring, or keychain changes.
8. Use `bash scripts/run_minecraft_skinbar.sh run` when you need the local menu bar app relaunched.
9. Prefer registering skins through the launcher's local custom-skins file instead of brittle UI clicking.
10. If the user has a prompt only, generate a draft skin sheet first, then clean it into a usable `64x64` skin.
11. Be honest that prompt-to-perfect skin generation is still draft-quality and may need a second pass.
12. If the user already has a PNG, skip generation and register it directly.

## Workflow

### Choose The Lane

- Use `minecraft-skinbar-workspace` when the user wants to build, troubleshoot, or refine the bundled macOS app in `apps/minecraft-skinbar`.
- Use `go` for the full flow: prompt draft, clean skin, preview, and launcher registration.
- Use `generate` when the user only wants files and iteration.
- Use `register` when they already have a valid skin PNG.
- Use `render-preview` when they want a quick visual check without touching the launcher.

### Work The Bundled App First

- Read `references/project-map.md` before editing the app workspace.
- Prefer the local runner before typing `xcodegen` or `xcodebuild` manually.
- Keep `Minecraft Skin Bar` compact and menu-bar-first.
- Preserve the current split:
  - `SkinBarModel` owns local state, launcher-facing actions, and keychain-backed API key handling
  - `SkinStudioCLI` shells out to `minecraft_skin_studio.py` through `uv`
  - `MenuBarView` stays focused on prompt, import, preview, and launcher handoff
- Keep OpenAI API keys in Keychain or environment variables only. Do not add plaintext config storage.
- Keep skin output local in `~/Pictures/Minecraft Skins` unless the user explicitly asks for another path.
- The current app project has no Xcode unit-test target, so use `typecheck` for the fastest helper sanity pass, `test` for the helper smoke path, and `build` as the strongest native validation.

### Skin Rules

- Java launcher skins should be treated as `64x64` PNG files.
- Keep the launcher-facing flow simple:
  - skin PNG
  - preview PNG
  - custom skin entry in `launcher_custom_skins.json`
- If the user asks for direct launcher automation, prefer the local JSON registration path first.
- Do not pretend generic image generation is guaranteed to produce a perfect UV layout on the first try.

### Required Deliverables

- A launcher-ready skin PNG path.
- A preview image path.
- A clear note on whether the skin was registered into the local launcher library.
- If generation was used, a short quality note about whether the result looks usable or needs another pass.

### Editing Guidance

- Keep prompts visual and specific: outfit, palette, theme, face detail, accessories.
- Use `wide` unless the user explicitly wants `slim`.
- Prefer simple names for launcher entries.
- Do not overwrite an existing launcher skin entry unless the user clearly wants a replace/update behavior.
- If you edit the bundled app, preserve the local-first workflow:
  - generate or import
  - preview locally
  - register into the launcher JSON
  - open the launcher or reveal the saved files
- Do not pretend the app can silently inject skins into Mojang services or change the active skin without the launcher's own local flow.

## Resources

- `scripts/minecraft_skin_studio.py`: generate, clean, preview, and register skins.
- `scripts/run_minecraft_skinbar.sh`: local doctor, inspect, generate, typecheck, test, open, build, and run helper for `apps/minecraft-skinbar`.
- `references/launcher-flow.md`: launcher storage path, workflow boundaries, and practical limits.
- `references/project-map.md`: bundled app target map, main files, and validation notes.
- `../../apps/minecraft-skinbar/`: the bundled macOS menu bar app workspace.
- `agents/openai.yaml`: UI metadata and default invocation prompt.