Design and Script API

minewright-workflow is the skill an agent follows whenever it plans, writes or reviews Bedrock add-on code. Its outcome: an add-on whose rules were written down before the code, whose every Script API call was looked up in current docs and is stable, whose numbers live in one config file, and which ships with a self-test and a playtest checklist.

Files: skills/minewright-workflow/SKILL.md, with two references: game-design.md (the one-pager, the config file, fair rules, rendering, the playtest checklist) and script-api-patterns.md (twelve patterns with the version that stabilised each API). Tier moderate.

Design before code

For a new add-on or a gameplay feature, the agent writes docs/ONE-PAGER.md in the project and shows it to you before any gameplay code. Bug fixes and reviews skip this step.

Heading	What goes there
Working title	Display name, and the identifier namespace (lowercase letters, digits, underscores; no dots)
Players	Ages, platforms, how many at once, LAN, Realm or server
Core loop	One verb for what players do most, then the cycle around it
Rules	Each rule as a sentence a player could repeat, then the edge cases: a player logs off, changes dimension, dies some other way, is in creative or spectator, joins late
Numbers	Every duration, speed, radius and count, by name
Commands	Slash commands and who may use them, with a /scriptevent fallback for each
Experiments	"None" unless you agreed to a permanently experimental world
Out of scope	What it will not do

Every number from the one-pager goes into one config module (src/config.ts, or scripts/config.js without TypeScript), with a test mode that turns minutes into seconds. Code reads names, never literals. The add-on also answers /scriptevent <ns>:selftest with [MWTEST] PASS|FAIL <name> lines, which Live server tests reads on a real server.

Look it up, do not recall it

The Script API gets a new minor version with each game release, and models still write APIs that were renamed or never left beta. Before using an API it is not sure of, the agent checks:

• the Microsoft Learn reference with the view=minecraft-bedrock-stable moniker, which shows stable members only;
• npm's dist-tags for @minecraft/server (latest is the stable line; the Learn changelog can lag npm by a day);
• @minecraft/vanilla-data and Mojang/bedrock-samples for vanilla ids and JSON examples.

The reply names the page it used. A page it cannot reach makes the API "unverified", not a guess.

Stable modules only

• @minecraft/server and @minecraft/server-ui by their stable version strings (2.11.0 and 2.3.0 on 2026-10-27; current numbers on Project and packaging).
• A -beta version needs the Beta APIs experiment, and turning on any experiment marks the world experimental for good.
• @minecraft/server-gametest has never had a stable release, so the scriptevent self-test is the default test route, not GameTest.
• Custom add-ons do not earn achievements, experiments or not; only Marketplace add-ons do. The skill tells you before you build on a survival world you care about.

Patterns that hold up

From script-api-patterns.md, each with the @minecraft/server version that made it stable:

Pattern	What it says
Pure core, thin adapter	Rules in src/core/*.ts with no @minecraft/* import, so node --test can test them; only src/main.ts talks to the game
One loop	One system.runInterval drives the state machine (stable since 1.1.0); event handlers only queue what happened
State that survives a reload	A versioned JSON string in a world dynamic property, read in world.afterEvents.worldLoad, never at the top level of the script
Entity properties for rendering	client_sync: true enum properties that the render controller reads with query.property('ns:name') (stable since 1.6.0)
Commands	customCommandRegistry.registerCommand in system.beforeEvents.startup (stable since 2.1.0); names need a namespace, cheatsRequired defaults to true, world changes go through system.run, and the full /ns:name is documented because a vanilla command can take the short alias
The unloaded-chunk trap	Entities in unloaded chunks do not tick and cannot be found; save the id and last location, and re-spawn near the target when it must act
Who dropped this item?	Nothing records it. Diff each player's inventory between ticks, keep the last two snapshots, and credit the player whose count fell
Moving through blocks	teleport in small steps each loop; 0.6-block steps carried an entity through a 3 by 5 stone wall on BDS
Damage and totems	applyDamage respects a Totem of Undying; kill() most likely does not (inferred, not documented)
Recall traps	isValid is a property, GameMode values are capitalised, and reading an entity after remove() throws
Self-test markers	An async self-test with system.waitTicks, a tickingarea to load a chunk with no players, console.warn for each marker

Fair rules for young players

From game-design.md, section 3, written into the one-pager:

• A threat always has a tell (a sound first, then a visible change) and a way to escape or survive it.
• Timers are visible.
• Nobody loses their own items or progress unless you asked for that rule.
• Scary moments are short and announced by sound; no flashing faster than three times a second.
• Players who did their part are not punished for a teammate who did not, unless the design says so.
• An operator can always skip, pause or turn the game off.
• Creative and spectator players are left alone by anything that hunts or scores.

Verify, then hand over the playtest

The skill runs Static checks, the pure-core unit tests, and the self-test on Bedrock Dedicated Server (Live server tests). A human playtest has the last word: the agent hands over the nine-question checklist from game-design.md, section 5, with the test-mode timings. The given.jar example shows every one of these steps in a finished add-on.