Index of every page on this site: llms.txt
All skills
Run it yourself

Designs grid and logic puzzle games in any engine: match-3 cascades, Sokoban pushing, unique-solution grids (nonogram, Sudoku), exact undo and solver-checked levels. Use for a Candy Crush-like, Sokoban or Picross, or broken cascades, drifting undo or unsolvable levels. Not for physics puzzlers (`platformer`, `physics-tuning`) or card games (`card-game`).

Use this Skill: https://skilld.dev/gh/gamedev-skills/awesome-gamedev-agent-skills/puzzle

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈91 tokens for metadata: the name and description. ≈1.6k when used: this file. ≈1.5k more on demand in 1 file.

Description uses 4.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈365 characters, or 4.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Puzzle

Owns discrete board puzzles: the rules engine, resolution order, undo, solvability and level difficulty. The board model is the only truth; the view replays the list of changes each move produced.

When to use

  • The player changes a discrete board with moves and the board resolves by rules: matching, pushing, sliding, merging, or pure logic deduction.
  • Writing a solver or generator, ordering levels by difficulty, fixing undo or soft-locks.

When not to use: physics-driven puzzles and puzzle platformers (platformer, physics-tuning); turn-based dungeon runs (roguelike); card zones (card-game).

Workflow

  1. Model the board as plain data (grid of cell values plus counters and RNG state) with a pure apply(state, move) -> (state, events) function. The view animates events.
  2. Write the rule resolver for the family (below) and loop until stable where rules cascade.
  3. Undo from day one: push a snapshot (or invertible command) before every move, including score, move counters and RNG state. Add restart, which thinky puzzles need as much as undo.
  4. Write a solver early (BFS or A* over states for push and slide puzzles, a line or constraint solver for logic grids, move-existence for match-3). It validates every level, measures difficulty and powers hints.
  5. Order levels by measured difficulty, introducing one mechanic at a time: a level that teaches it alone, a level that tests it, then one that combines it with a known mechanic.
  6. Check it. Run these in the project's test runner and report the numbers:
    • the solver solves every shipped level; print minimum moves and states explored per level and flag levels whose order disagrees with difficulty;
    • logic grids: the solver finds exactly one solution without guessing;
    • undo: hash the full state, make a random move, undo, and compare hashes (1,000 times);
    • match-3: 10,000 random boards after generation have no ready-made match and at least one valid move;
    • input during a resolving cascade is ignored or queued, never applied mid-resolution.

Rule families and numbers

Family Rules that matter Starting numbers
Match-3 4 in a line makes a line-clear piece, an L or T of 5 makes an area bomb, 5 in a line makes a colour bomb (Candy Crush naming) 8x8 or 9x9 board, 5-6 colours (fewer colours, more cascades), hint after about 5 s idle
Push (Sokoban) push one box, never pull; dead squares (non-goal corners, wall edges with no goal) difficulty from minimum pushes and states explored, not board size
Slide (15-puzzle) half of random arrangements are unsolvable check inversion parity (refs §7)
Merge (2048) slide, merge equal neighbours once per move, then spawn the original spawns a 2 with 90% chance and a 4 with 10%
Logic grids exactly one solution, reachable by deduction alone grade difficulty by the hardest deduction rule the solver needed
Rule-changing (Baba Is You style) rules are board objects; re-derive the rule set after every move, before win checks test every rule word against every object type

No-guess generation is standard for logic puzzles: Simon Tatham's Mines, for example, ensures by default that the whole grid can be deduced from the first opening.

Pattern 1: resolve to stability (match-3)

def resolve(board, rng):
    events, chain = [], 0
    while True:
        matches = find_matches(board)              # runs of 3+, rows and columns
        if not matches:
            break
        chain += 1
        specials = specials_from(matches)          # decide BEFORE clearing (shape and swap cell)
        events.append(("clear", matches, chain))
        clear(board, matches); place(board, specials)
        events.append(("fall", apply_gravity(board)))
        events.append(("spawn", refill(board, rng)))   # seeded RNG, saved in undo snapshots
    if not has_valid_move(board):
        events.append(("shuffle", reshuffle_until_playable(board, rng)))
    return events

Gotchas

  • Cascades miss matches → resolution ran once. Loop until no matches (Pattern 1).
  • Special piece appears in the wrong cell → specials decided after clearing. Decide from the match shape and the swapped cell first.
  • Undo rerolls the refill → RNG state not in the snapshot; players learn to undo for better pieces. Snapshot board, score, counters and RNG state together.
  • Visuals desync from the board → animation code reads a half-updated board. Animate the event list; lock or queue input until it finishes.
  • Soft-lock with no moves → no deadlock check. Detect and reshuffle (keep piece counts, no free matches) or end the level.
  • Unsolvable generated level → random scramble with no check. Generate backwards from the solved state with inverse moves (pull for Sokoban), or generate and solve, with the seed kept.
  • Two valid answers in a logic grid → generator never checked uniqueness. Run the solver for a second solution and reject or add a clue.
  • Difficulty jumps → levels ordered by designer guess. Order by solver effort and teach one mechanic at a time.
  • Box pushed into a dead corner with no hint → no dead-square detection. Precompute dead squares and offer restart or flag them.

References

  • references/board-and-resolution.md: read when writing match-3 gravity, refill and deadlock code, cascade scoring, Sokoban pushing, logic-grid validity checks, undo strategies, solvable generation and sliding-tile parity, or input locking during animation.

Related: level-design (teaching order), procedural-gen (seeded generators), save-systems (progress, daily seeds), game-feel (match pops, chain feedback), godot-tilemap or unity-tilemap-2d (board rendering).

Version notes

Last verified: 2026-11-11.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts8d3 checks · Risk SAFE
  • Gen Agent Trust Hub9d

    This skill provides architectural patterns, pseudocode, and design workflows for building various puzzle game genres such as match-3, Sokoban, and logic grids. It includes references to established game implementations and provides guidance on implementing robust systems for undo, solving, and difficulty balancing. No security issues or malicious patterns were identified.

  • Socket8d

    No alerts

  • Snyk9d

    Risk: LOW · No issues

Signed by skilld at c6ca6c4. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated last week

README badge

README badge for gamedev-skills/awesome-gamedev-agent-skills/puzzle