minecraft-modding
Create, modify, debug, or migrate Minecraft mods for current NeoForge or Fabric 26.x, legacy 1.21.x, and Forge 1.20.1. Use for loader-based gameplay code and assets; use minecraft-multiloader when one codebase must target both modern loaders.
Jahrome907 · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add Jahrome907/minecraft-agent-skills --skill minecraft-moddingAbout this skill
name: minecraft-modding description: "Create, modify, debug, or migrate Minecraft mods for current NeoForge or Fabric 26.x, legacy 1.21.x, and Forge 1.20.1. Use for loader-based gameplay code and assets; use minecraft-multiloader when one codebase must target both modern loaders."
Minecraft Modding Skill
Overview
This skill guides Codex through developing open-source Minecraft mods. Target platforms:
| Platform | MC Version | Java | Build System |
|---|---|---|---|
| NeoForge | 26.x current; 1.21.11 examples retained | Java 25 current; Java 21 on 1.21.x | Gradle + ModDevGradle |
| Forge | 1.20.1 legacy lane | Java 17 | Gradle + ForgeGradle 6 |
| Fabric | 26.x current; 1.21.11 examples retained | Java 25 current; Java 21 on 1.21.x | Gradle + Fabric Loom |
| Architectury (multiloader) | 26.x or 1.21.x | Match Minecraft | Gradle + Architectury Loom |
Always confirm the platform and Minecraft version from gradle.properties or build.gradle
before writing any mod-specific code.
Minecraft 26.1 introduced Java 25 and unobfuscated game executables. For 26.x projects, start from the current loader generator or example mod and preserve its build layout. Do not copy the 1.21.11 mapping, Loom plugin, remapping task, or Java 21 snippets in this skill into a 26.x project. Fabric 26.x uses the non-remapping Loom path and official names; NeoForge 26.x should start from the current NeoForge generator. Treat the detailed API references here as the legacy 1.21.x lane unless a section explicitly says 26.x.
Routing Boundaries
Use when: the task is Java/Kotlin mod code, registry/event work, networking, datagen wiring, and loader APIs.Do not use when: the task is command-only vanilla logic (minecraft-commands-scripting) or pure datapacks (minecraft-datapack).Do not use when: the task targets Paper/Bukkit plugins (minecraft-plugin-dev).
1. Identifying the Platform
# NeoForge project signature
grep -r "net.neoforged" gradle.properties build.gradle settings.gradle 2>/dev/null | head -5
# Forge 1.20.1 project signature
grep -r "net.minecraftforge" gradle.properties build.gradle settings.gradle 2>/dev/null | head -5
# Fabric project signature
grep -r "fabric" gradle.properties build.gradle settings.gradle 2>/dev/null | head -5
# Read mod ID and version
cat gradle.properties
Key files per platform:
- NeoForge:
src/main/resources/META-INF/neoforge.mods.toml, annotated@Modmain class - Forge 1.20.1:
src/main/resources/META-INF/mods.toml,net.minecraftforge:forgedependency - Fabric:
src/main/resources/fabric.mod.json, class implementingModInitializer - Architectury:
common/,fabric/,neoforge/subprojects
2. Build & Test Commands
# Build the mod jar
./gradlew build
# Run the Minecraft client to test
./gradlew runClient
# Run a dedicated server to test
./gradlew runServer
# Run game tests (NeoForge JUnit-style game tests)
./gradlew runGameTestServer
# Run data generation (generates JSON assets automatically)
./gradlew runData
# Remove this project's generated build outputs before a fresh rebuild
./gradlew clean
# Check for dependency updates (optional)
./gradlew dependencyUpdates
./gradlew build runs the project's configured build tasks. Candidate mod jars are
usually under build/libs/, but task names and file names are project-specific.
Treat the build output as compilation evidence, then identify the intended
distributable before publishing it.
3. Project Layout (NeoForge)
src/
main/
java/<groupId>/<modid>/
MyMod.java ← @Mod entry point
block/
ModBlocks.java ← DeferredRegister.Blocks
MyCustomBlock.java
item/
ModItems.java ← DeferredRegister.Items
entity/
ModEntities.java ← DeferredRegister.Entities
menu/ ← custom GUI containers
recipe/
worldgen/
datagen/
ModDataGen.java ← GatherDataEvent handler
providers/
resources/
META-INF/
neoforge.mods.toml ← mod metadata (renamed from mods.toml in NeoForge 1.20.5+)
assets/<modid>/
blockstates/ ← JSON blockstate definitions
models/
block/ ← block model JSON
item/ ← item model JSON
items/ ← 1.21.x item-definition JSON
textures/
block/ ← 16×16 PNG textures
item/
lang/
en_us.json ← translation strings
data/<modid>/
recipe/ ← crafting recipe JSON (26.x)
loot_table/
blocks/ ← per-block loot table JSON
tags/
blocks/
items/
4. Project Layout (Forge 1.20.1)
Use this layout only when minecraft_version=1.20.1 and the project depends on
net.minecraftforge:forge. Forge 1.20.1 is not NeoForge: keep mods.toml,
net.minecraftforge.* imports, Java 17, and ForgeGradle 6 patterns.
src/
main/
java/<groupId>/<modid>/
MyMod.java <- @Mod entry point
block/
ModBlocks.java <- DeferredRegister.Blocks
item/
ModItems.java <- DeferredRegister.Items
datagen/
ModDataGen.java <- GatherDataEvent handler
resources/
META-INF/
mods.toml <- Forge metadata
assets/<modid>/ <- client assets
data/<modid>/ <- server data using 1.20.1 paths
See references/forge-1.20.1-api.md before editing Forge 1.20.1 projects.
5. Project Layout (Fabric)
src/
main/
java/<groupId>/<modid>/
MyMod.java ← implements ModInitializer
client/
MyModClient.java ← implements ClientModInitializer
block/
item/
mixin/ ← Mixin classes
resources/
fabric.mod.json
Read the complete source ↗