Skip to main content
skill CX Codex

minecraft-datapack — Claude Code skill: what it does, how to install

The minecraft-datapack skill for Claude Code creates and debugs vanilla Minecraft 1.21.x and 26.x datapacks. It builds folder structures, functions, loot tables, and pack.mcmeta without mods.

MIT 300 installs ★ 211 updated 2026-10-11

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add Jahrome907/minecraft-agent-skills --skill minecraft-datapack -a claude-code
Open on GitHub

What minecraft-datapack does

The skill organizes and edits datapack assets for vanilla Minecraft releases across 1.21.x and 26.x. It builds standard folder layouts under data/, sets up engine tags for load.json and tick.json in the minecraft namespace, and writes JSON files for advancements, predicates, recipes, and loot tables.

Metadata handling changes sharply at pack format 82. For Minecraft 1.21.8 and older, the file requires integer pack_format. From 1.21.9 onwards, patch targets require integer pairs such as [88, 0] in min_format and max_format. Writing decimal values like 94.1 causes engine errors, which this skill prevents by pinning exact patch arrays.

The tool strictly targets vanilla datapack file trees: projects requiring Java mod loaders or standalone command lines outside a pack directory are out of scope.

What it helps with

  • generate valid datapack directory trees and namespace folders
  • write exact pack.mcmeta files for legacy and modern format schemas
  • configure minecraft:load and minecraft:tick functions
  • build loot tables, advancements, predicates, and function macros

Example prompts for the agent

  • Create a new Minecraft 1.21.4 datapack with tick and load functions
  • Update pack.mcmeta for Minecraft 1.21.10 using modern format arrays
  • Write an mcfunction macro in mypack that greets a player using $(name)

How to install minecraft-datapack

1Skills CLI (Vercel)

npx skills add Jahrome907/minecraft-agent-skills --skill minecraft-datapack -a claude-code

2Manually: put the files in place

~/.claude/skills/minecraft-datapack/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/minecraft-datapack/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about minecraft-datapack

How to install minecraft-datapack in Claude Code?

Run npx skills add Jahrome907/minecraft-agent-skills --skill minecraft-datapack -a claude-code in your terminal.

What does the minecraft-datapack skill do?

It scaffolds, edits, and checks Minecraft datapack structures, including functions, loot tables, tags, and version-specific pack.mcmeta files.

How does pack.mcmeta differ between 1.21.8 and 1.21.9?

Version 1.21.8 uses a single integer pack_format: 81. Starting with 1.21.9, Minecraft expects integer pairs in min_format and max_format like [88, 0] rather than floating-point numbers.

Source text

SKILL.md · MIT
---
name: minecraft-datapack
description: "Create, edit, and debug vanilla Minecraft 26.x and 1.21.x datapacks, including functions, advancements, recipes, loot tables, predicates, tags, and pack metadata. Use when the deliverable is a datapack file tree without Java or loader APIs."
---

# Minecraft Datapack Skill

Inspect `pack.mcmeta` and the target Minecraft version before editing. Preserve
an existing target unless migration is requested; metadata numbers alone do not
make older command or registry schemas compatible. Check the edited files with
the bundled validator and test in-game when available.

## Skill Scope

### Routing Boundaries
- `Use when`: the deliverable is datapack files (`pack.mcmeta`, `data/...`) and `.mcfunction`/JSON content.
- `Do not use when`: the request is command-only snippets not tied to a datapack file tree (`minecraft-commands-scripting`).
- `Do not use when`: the request requires loader APIs, Java code, or runtime mod behavior (`minecraft-modding`).

---

## Pack Metadata

| Minecraft Version | Preferred `pack` metadata |
|-------------------|---------------------------|
| 1.21 / 1.21.1     | `pack_format: 48` |
| 1.21.2 / 1.21.3   | `pack_format: 57` |
| 1.21.4            | `pack_format: 61` |
| 1.21.5            | `pack_format: 71` |
| 1.21.6            | `pack_format: 80` |
| 1.21.7 / 1.21.8   | `pack_format: 81` |
| 1.21.9 / 1.21.10  | `min_format: [88, 0]`, `max_format: [88, 0]` |
| 1.21.11           | `min_format: [94, 1]`, `max_format: [94, 1]` |
| 26.1              | `min_format: [101, 1]`, `max_format: [101, 1]` |
| 26.2              | `min_format: [107, 1]`, `max_format: [107, 1]` |
| 26.3              | `min_format: [121, 0]`, `max_format: [121, 0]` |

Use `pack_format` for a legacy-only target through data pack format 81. Starting
with data pack format 82 in 1.21.9, define both explicit `min_format` and
`max_format` values. A range that includes a legacy format below 82 must also
retain `pack_format` and `supported_formats`; do not include
`supported_formats` for a modern-only range.
For a legacy-compatible range, `supported_formats` may be one integer, a
two-integer inclusive range, or an object with integer `min_inclusive` and
`max_inclusive` fields.
For exact patch targeting, use `[major, minor]` arrays for both `min_format` and
`max_format`, including `.0` versions such as `[88, 0]`. A single integer is
equivalent to `[major, 0]` for `min_format`, while a single integer in
`max_format` allows any minor version on that major line. Do not write decimal
JSON numbers such as `94.1`.

Keep `pack.mcmeta` exact for the patch you target instead of trying to span the
multiple Minecraft releases with one metadata block.

---

## Directory Layout

```
my-datapack/
├── pack.mcmeta
└── data/
    ├── <namespace>/           ← use your pack's name (e.g., mypack)
    │   ├── function/
    │   │   ├── main.mcfunction
    │   │   └── tick.mcfunction
    │   ├── advancement/
    │   │   └── custom_advancement.json
    │   ├── recipe/
    │   │   └── custom_recipe.json
    │   ├── loot_table/
    │   │   └── custom_loot.json
    │   ├── predicate/
    │   │   └── is_night.json
    │   ├── item_modifier/
    │   │   └── add_name.json
    │   └── tags/
    │       ├── block/
    │       │   └── climbable.json
    │       ├── entity_type/
    │       │   └── bosses.json
    │       └── function/
    │           └── custom_flow.json  ← manually invoked tag
    └── minecraft/
        └── tags/function/
            ├── load.json             ← engine tag; runs on /reload
            └── tick.json             ← engine tag; runs every game tick
```

---

## `pack.mcmeta`

### 1.21.8 and earlier

```json
{
  "pack": {
    "pack_format": 81,
    "description": "My Custom Datapack v1.0"
  }
}
```

### Deliberate legacy-to-modern compatibility range

Use this form only when the pack actually supports both sides of the format-82
boundary. Mojang requires the retained legacy fields for this range.

```json
{
  "pack": {
    "pack_format": 81,
    "supported_formats": [81, 88],
    "min_format": [81],
    "max_format": [88],
    "description": "My compatible datapack"
  }
}
```

### 1.21.9 / 1.21.10

```json
{
  "pack": {
    "min_format": [88, 0],
    "max_format": [88, 0],
    "description": "My Custom Datapack v1.0"
  }
}
```

### 1.21.11

```json
{
  "pack": {
    "min_format": [94, 1],
    "max_format": [94, 1],
    "description": "My Custom Datapack v1.0"
  }
}
```

### 26.3

```json
{
  "pack": {
    "min_format": [121, 0],
    "max_format": [121, 0],
    "description": "My Custom Datapack v1.0"
  }
}
```

---

## Function Tags (load / tick)

The engine recognizes the `minecraft:load` and `minecraft:tick` tags, so these
files must use the `minecraft` namespace. A `load.json` or `tick.json` in a
custom namespace is a valid custom tag name, but it has no automatic behavior.

### `data/minecraft/tags/function/load.json`
```json
{
  "values": [
    "<namespace>:setup"
  ]
}
```

### `data/minecraft/tags/function/tick.json`
```json
{
  "values": [
    "<namespace>:tick"
  ]
}
```

### `data/<namespace>/function/setup.mcfunction`
```mcfunction
# Runs once on /reload
scoreboard objectives add deaths deathCount
scoreboard objectives add kills playerKillCount
tellraw @a {"text":"[MyPack] Loaded!","color":"green"}
```

### `data/<namespace>/function/tick.mcfunction`
```mcfunction
# Runs every tick — KEEP THIS SHORT
# Only put fast, targeted operations here
execute as @a[scores={deaths=1..}] run function mypack:on_death_check
```

---

## Commands and Function Syntax

### Execute subcommands (datapack-specific patterns)
```mcfunction
# Chained execute — common datapack pattern for conditional per-player logic
execute as @a[gamemode=!spectator] at @s if block ~ ~-1 ~ #minecraft:logs run give @s minecraft:apple

# store result into score (bridge between NBT world and scoreboard state)
execute store result score @s mypack.health run data get entity @s Health

# in: run logic in another dimension
execute in minecraft:the_nether run say This runs in the Nether
```

### Storage NBT (datapack-specific global state)
```mcfunction
# Storage is the datapack-native key-value store — persists across /reload
data modify storage mypack:data config.difficulty set value "hard"
data get storage mypack:data config.difficulty

# Copy live entity data into storage for macro use or cross-function state
data modify storage mypack:log last_player_pos set from entity @s Pos
```

For full command syntax, selectors, and scoreboard operations see the
[Minecraft Wiki — Commands](https://minecraft.wiki/w/Commands) reference.
The `minecraft-commands-scripting` skill covers command-only work in depth.

---

## Macros (1.20.2+)

Macro functions let you pass dynamic arguments to a function.

### Define a macro function (`data/mypack/function/greet.mcfunction`)
```mcfunction
# Macro argument: $(name)
$tellraw @a {"text":"Welcome $(name)!","color":"gold"}
$scoreboard players set $(name) points 0
```

### Call with `run function` + `with`
```mcfunction
# Pass values from storage
data modify storage mypack:tmp input set value {name:"Steve"}
function mypack:greet with storage mypack:tmp input

```

---

## Registry data examples

Read [references/data-examples.md](references/data-examples.md) when authoring
advancements, recipes, loot tables, predicates, or tags. Load only the relevant
section and keep existing namespaces and version targets.

## Worldgen Overrides

### Override biome noise (`data/minecraft/worldgen/noise_settings/overworld.json`)
Edit inside an existing copy — do NOT create from scratch without the full JSON.
Get the vanilla version from the Minecraft jar: `jar xf minecraft.jar data/`.

### Override a biome's spawn costs (through 26.2)

For 26.3, use the biome's `minecraft:gameplay/natural_mob_spawns` environment
attribute instead; the old top-level `spawn_costs` field was removed.
```json
{
  "spawn_costs": {
    "minecraft:zombie": {
      "energy_budget": 0.12,
      "charge": 0.7
    }
  }
}
```

---

## Installation & Testing

Place the pack folder or ZIP under the world's `datapacks/` directory, with
`pack.mcmeta` at its root. Then use these in-game commands:

```text
/datapack list
/datapack enable "file/my-datapack"
/datapack disable "file/my-datapack"
/reload
```

### Development workflow
1. Edit `.mcfunction` or `.json` files
2. Run the bundled validator to catch JSON and path errors before loading:
   ```bash
   ./scripts/validate-datapack.sh --root /path/to/datapack
   ```
3. If errors, fix and re-validate until clean
4. Run `/reload` in-game (or `/minecraft:reload` if a mod intercepts it)
5. Test with target command (e.g., `/function mypack:setup`, trigger an advancement)
6. Check `latest.log` for runtime errors (missing references, bad selectors)

---

## Common Errors

| Error | Cause | Fix |
|-------|-------|-----|
| `Unknown or invalid command` | Syntax error in function | Check whitespace, selector, trailing space |
| `Datapack did not load` | Invalid JSON in any file | Validate with `jq . < file.json` |
| `pack metadata mismatch` | Wrong `pack_format` or `min_format` / `max_format` values | Update `pack.mcmeta` for the exact Minecraft release |
| Function not running on tick | Missing engine tick tag or wrong namespace | Check `data/minecraft/tags/function/tick.json` |
| Macro error | `$` line but no `with` | Provide `with storage/entity/block` |

## Validator Script

Use the bundled validator script before shipping a datapack update:

```bash
# Run from the installed skill directory (for example `.codex/skills/minecraft-datapack`):
./scripts/validate-datapack.sh --root /path/to/datapack

# Strict mode treats warnings as failures:
./scripts/validate-datapack.sh --root /path/to/datapack --strict
```

What it checks:
- JSON validity for `pack.mcmeta` and `data/**/*.json`
- Legacy pluralized path mistakes for loot tables, functions, and block/item/function tags
- `data/minecraft/tags/function/load.json` and `tick.json` references resolve to local `.mcfunction` files
- custom-namespace `load.json` and `tick.json` names, which are valid but do not run automatically

---

## References

- Minecraft Wiki — Data Pack: https://minecraft.wiki/w/Data_pack
- Minecraft Java Edition 1.21.9 release notes: https://www.minecraft.net/en-us/article/minecraft-java-edition-1-21-9
- Minecraft Wiki — Function: https://minecraft.wiki/w/Function_(Java_Edition)
- Minecraft Wiki — Commands: https://minecraft.wiki/w/Commands
- Pack format history: https://minecraft.wiki/w/Pack_format
- NBT format: https://minecraft.wiki/w/NBT_format
- Predicate conditions: https://minecraft.wiki/w/Predicate
- Loot table format: https://minecraft.wiki/w/Loot_table

- [Mojang: Java Edition 26.3](https://www.minecraft.net/en-us/article/minecraft-java-edition-26-3)

© Jahrome907 · MIT · Jahrome907/minecraft-agent-skills

Similar skills

All skills for Game dev and 3D: Unity, Unreal, Godot, Blender →

From the same set13

The whole set →
minecraft-modding minecraft-modding writes and edits Minecraft mod code for NeoForge, Fabric 26.x, 1.21.x and Forge 1.20.1. Checks gradle.properties and build.gradle to confirm the loader and version before touching any code. CX Codex +1 966installs minecraft-testing minecraft-testing writes and runs automated tests for Minecraft mods and plugins using JUnit, MockBukkit, NeoForge GameTests, and Fabric GameTests. CX Codex +1 386installs minecraft-resource-pack minecraft-resource-pack is a skill that generates and troubleshoots Minecraft 1.21.x and 26.x resource packs, including block models, sound maps, and pack.mcmeta manifests. CX Codex +1 385installs minecraft-server-admin minecraft-server-admin runs the infrastructure side of Minecraft Java servers: Paper, Purpur, Folia, Velocity, Fabric, NeoForge. Useful when TPS drops or a proxy blocks logins. CX Codex +1 279installs minecraft-world-generation minecraft-world-generation is a Claude Code skill for building and debugging Minecraft world generation in datapacks, NeoForge, or Fabric. It activates for biome, dimension, structure, and worldgen registration tasks. CX Codex +1 269installs minecraft-plugin-dev minecraft-plugin-dev helps build, change, and debug Minecraft server plugins for Paper and Bukkit-derived servers. Useful for JavaPlugin APIs, events, commands, and configuration. CX Codex +1 267installs minecraft-multiloader minecraft-multiloader is a Claude Code skill that builds and maintains Architectury Minecraft mods for 26.x and 1.21.x across NeoForge and Fabric. It runs when both loaders need release artifacts. CX Codex +1 247installs minecraft-commands-scripting minecraft-commands-scripting writes and debugs Minecraft Java 26.x and 1.21.x commands, execute chains, scoreboards, and RCON scripts. Targets command logic directly without generating full datapack folder structures. CX Codex +1 241installs

Project sponsors

Companies that keep this analytics open