[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M79PVGTYHH2KPA2RDWA0NFAZ":3,"skill-same:01M79PVGTYHH2KPA2RDWA0NFAZ":51},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":29,"updatedAt":30,"install":31,"resources":44},"01M79PVGTYHH2KPA2RDWA0NFAZ","puzzle",null,"Build a puzzle game: grid\u002Fboard state, move input, rule-based resolution (match-3 cascades, sokoban pushes, tile logic), scoring, and undo. Use for a match-3, sokoban, or grid-logic puzzle.","JunMystery\u002FAgent-Guidance","JunMystery","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F161468934?v=4","01M79MTMV8F0BY8NK1A92RA8A0","Jun","01M79MTMWCFBKPHN5B25E6V20B",0,"MIT","https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance\u002Fblob\u002Fmain\u002Fskills\u002Fpuzzle\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: puzzle\ndescription: >\n  Build a puzzle game: grid\u002Fboard state, move input, rule-based resolution (match-3 cascades, sokoban\n  pushes, tile logic), scoring, and undo. Use for a match-3, sokoban, or grid-logic puzzle.\n---\n\n# Puzzle\n\nA playbook for grid\u002Fboard puzzle games — the board model, move input, rule resolution\n(matching, pushing, logic), scoring, undo, and level progression. This is a **compositional**\nskill: it models board state and rules and presents them through a tilemap\u002FUI. It does not\nre-teach tilemaps; it defines the resolution loop and the correctness rules (clean state,\ndeterministic resolution, undo) that keep a puzzle fair and bug-free.\n\n## When to use\n\n- Use when the game is a **discrete board** the player changes with moves, and the board\n  **resolves by rules**: match-3\u002Ftile-matching, sokoban\u002Fblock-pusher, sliding puzzle, logic grid.\n- Use when designing match\u002Fcascade resolution, undo, level progression, or solvability.\n\n**When *not* to use:** real-time grid action with permadeath → `roguelike`. Card zones\u002Fturns →\n`card-game`. Physics-based \"puzzle platformer\" → `platformer` + `physics-tuning`. For the tile\nrendering, use `godot-tilemap` \u002F `unity-tilemap-2d`.\n\n## Core loop\n\n**Read the board → plan a move → make the move → the board resolves by its rules (match, push,\nfall, fill, cascade) → see progress toward the objective → repeat until solved\u002Ffailed.** The\nfun is the *planning*; the engine's job is to resolve each move **deterministically** and\npresent it clearly.\n\n## Must-have systems\n\n1. **Board model** — a grid of cells holding pieces; the single source of truth (logic, not visuals).\n2. **Move input** — swap, push, drag, rotate, or place; validate legality before applying.\n3. **Rule resolution** — detect and apply the genre's rule (matches, pushes, logic) until stable.\n4. **Cascades\u002Fchains** — when resolution changes the board, re-resolve until no more changes.\n5. **Objectives + scoring** — win\u002Flose conditions (score, clear all, reach goal); move\u002Ftime limits.\n6. **Undo** — revert the last move (and its resolution) exactly; essential for thinky puzzles.\n7. **Level progression + (often) generation** — hand-authored or generated **solvable** boards.\n8. **Feedback (\"juice\")** — clear, satisfying animation\u002Fsound for matches, falls, and chains.\n\n## Design knobs\n\n| Knob | Effect | Notes |\n|------|--------|-------|\n| Grid size \u002F shape | complexity | Square is standard; hex\u002Firregular change feel. |\n| Match\u002Fpush rule | genre identity | 3-in-a-row, shapes, push-into-goal, etc. |\n| Cascade scoring | reward depth | Bigger chains = exponential payoff. |\n| Move \u002F time limit | pressure | Move-limited = puzzly; time = arcade. |\n| Difficulty curve | learning | Introduce one mechanic at a time. |\n| Undo depth | forgiveness | Single-step vs. full history. |\n| Solvability guarantee | fairness | Generated boards must be solvable. |\n| Deadlock handling | no dead ends | Detect no-moves; shuffle or end (refs). |\n\n## Patterns\n\n### 1. Board model + match detection (logic separate from visuals)\n\n```python\n# Pseudocode. The board is the truth; rendering reads from it. (0,0) top-left, y grows down.\nboard = [[piece_or_empty for _ in range(W)] for _ in range(H)]\n\ndef find_matches(board):\n    matched = set()\n    for y in range(H):                       # horizontal runs of >= 3 equal pieces\n        run = 1\n        for x in range(1, W):\n            if board[y][x] and board[y][x] == board[y][x-1]: run += 1\n            else:\n                if run >= 3: matched |= {(y, k) for k in range(x-run, x)}\n                run = 1\n        if run >= 3: matched |= {(y, k) for k in range(W-run, W)}\n    # ... repeat the same scan vertically (columns) ...\n    return matched\n```\n\n### 2. Resolve → collapse → refill → cascade (repeat to stability)\n\n```python\n# Pseudocode. One player move can trigger a chain; loop until the board stops changing.\ndef resolve(board):\n    chain = 0\n    while True:\n        matches = find_matches(board)\n        if not matches: break                 # stable: resolution complete\n        chain += 1\n        score += score_for(matches, chain)    # later chain steps score more (see refs)\n        clear(board, matches)                  # remove matched pieces\n        apply_gravity(board)                   # pieces fall into the gaps\n        refill(board, rng)                      # spawn new pieces at the top (seeded RNG)\n    return chain\n```\n\n### 3. Undo via state snapshot or command\n\n```python\n# Pseudocode. Snapshot before each move; undo restores it exactly (board + score + counters + RNG).\ndef make_move(move):\n    history.append(snapshot(board, score, moves_left, rng.state))   # push BEFORE applying\n    apply(move); resolve(board); moves_left -= 1\n\ndef undo():\n    if history:\n        board, score, moves_left, rng.state = history.pop()   # exact revert, including refills\n```\n\nFor large boards prefer the **command** pattern (store the move + enough to invert it) over full\nsnapshots to save memory; snapshots are simplest and fine for small boards.\n\n## Pitfalls \u002F failure modes\n\n- **Mixing logic and visuals** → animations desync from state and cause bugs. The board model is\n  the single source of truth; the view only renders it.\n- **Resolving only once** → cascades\u002Fchains are missed. Loop resolution until the board is stable\n  (Pattern 2).\n- **Undo that doesn't restore everything** → score\u002Fmove-count\u002Frandom-state drift. Snapshot *all*\n  state, or make the move fully invertible. If undo skips the RNG state, redoing the same move\n  refills different pieces and players learn to \"reroll\" by undoing.\n- **Unseeded refill RNG** → can't reproduce a level \u002F no deterministic undo or daily puzzle. Seed it.\n- **Generated boards that aren't solvable** → unfair dead ends. Generate-and-verify, or generate\n  from a known solution backward (refs). A sliding-tile puzzle filled by a random shuffle is\n  unsolvable half the time; check the parity rule in refs §7.\n- **No deadlock detection** (match-3) → board with no valid moves softlocks. Detect \"no moves\"\n  and shuffle or end the level (refs).\n- **Difficulty spikes** → too many mechanics at once. Teach one mechanic per level before combining.\n- **Resolution mid-animation accepts input** → double-moves\u002Fcorruption. Lock input until the\n  board is stable.\n\n## Composition (build it from these skills)\n\n- **Board rendering:** `godot-tilemap` \u002F `unity-tilemap-2d` for the grid; `godot-ui-control` for HUD, score, and menus.\n- **Levels:** `level-design` for hand-authored puzzles and difficulty pacing; `procedural-gen` for solvable generated boards.\n- **Persistence:** `save-systems` for level progress, high scores, and seeded daily puzzles.\n- **Juice:** `game-feel` for match\u002Fcascade pop, screen shake, and chain feedback; the engine animation\u002F`Tween` skill for swaps\u002Ffalls\u002Fclears; `audio-design` for match and chain cues.\n- **Scripting:** `godot-gdscript` \u002F `unity-csharp-scripting` for the resolution loop and rules.\n\n## References\n\n- For match-3 detection\u002Fgravity\u002Frefill\u002Fcascade detail, deadlock detection and reshuffles,\n  sokoban\u002Frule-based puzzles, undo strategies, solvable generation, and scoring, read\n  `references\u002Fboard-and-resolution.md`.\n","# Puzzle\n\nA playbook for grid\u002Fboard puzzle games — the board model, move input, rule resolution\n(matching, pushing, logic), scoring, undo, and level progression. This is a **compositional**\nskill: it models board state and rules and presents them through a tilemap\u002FUI. It does not\nre-teach tilemaps; it defines the resolution loop and the correctness rules (clean state,\ndeterministic resolution, undo) that keep a puzzle fair and bug-free.\n\n## When to use\n\n- Use when the game is a **discrete board** the player changes with moves, and the board\n  **resolves by rules**: match-3\u002Ftile-matching, sokoban\u002Fblock-pusher, sliding puzzle, logic grid.\n- Use when designing match\u002Fcascade resolution, undo, level progression, or solvability.\n\n**When *not* to use:** real-time grid action with permadeath → `roguelike`. Card zones\u002Fturns →\n`card-game`. Physics-based \"puzzle platformer\" → `platformer` + `physics-tuning`. For the tile\nrendering, use `godot-tilemap` \u002F `unity-tilemap-2d`.\n\n## Core loop\n\n**Read the board → plan a move → make the move → the board resolves by its rules (match, push,\nfall, fill, cascade) → see progress toward the objective → repeat until solved\u002Ffailed.** The\nfun is the *planning*; the engine's job is to resolve each move **deterministically** and\npresent it clearly.\n\n## Must-have systems\n\n1. **Board model** — a grid of cells holding pieces; the single source of truth (logic, not visuals).\n2. **Move input** — swap, push, drag, rotate, or place; validate legality before applying.\n3. **Rule resolution** — detect and apply the genre's rule (matches, pushes, logic) until stable.\n4. **Cascades\u002Fchains** — when resolution changes the board, re-resolve until no more changes.\n5. **Objectives + scoring** — win\u002Flose conditions (score, clear all, reach goal); move\u002Ftime limits.\n6. **Undo** — revert the last move (and its resolution) exactly; essential for thinky puzzles.\n7. **Level progression + (often) generation** — hand-authored or generated **solvable** boards.\n8. **Feedback (\"juice\")** — clear, satisfying animation\u002Fsound for matches, falls, and chains.\n\n## Design knobs\n\n| Knob | Effect | Notes |\n|------|--------|-------|\n| Grid size \u002F shape | complexity | Square is standard; hex\u002Firregular change feel. |\n| Match\u002Fpush rule | genre identity | 3-in-a-row, shapes, push-into-goal, etc. |\n| Cascade scoring | reward depth | Bigger chains = exponential payoff. |\n| Move \u002F time limit | pressure | Move-limited = puzzly; time = arcade. |\n| Difficulty curve | learning | Introduce one mechanic at a time. |\n| Undo depth | forgiveness | Single-step vs. full history. |\n| Solvability guarantee | fairness | Generated boards must be solvable. |\n| Deadlock handling | no dead ends | Detect no-moves; shuffle or end (refs). |\n\n## Patterns\n\n### 1. Board model + match detection (logic separate from visuals)\n\n```python\n# Pseudocode. The board is the truth; rendering reads from it. (0,0) top-left, y grows down.\nboard = [[piece_or_empty for _ in range(W)] for _ in range(H)]\n\ndef find_matches(board):\n    matched = set()\n    for y in range(H):                       # horizontal runs of >= 3 equal pieces\n        run = 1\n        for x in range(1, W):\n            if board[y][x] and board[y][x] == board[y][x-1]: run += 1\n            else:\n                if run >= 3: matched |= {(y, k) for k in range(x-run, x)}\n                run = 1\n        if run >= 3: matched |= {(y, k) for k in range(W-run, W)}\n    # ... repeat the same scan vertically (columns) ...\n    return matched\n```\n\n### 2. Resolve → collapse → refill → cascade (repeat to stability)\n\n```python\n# Pseudocode. One player move can trigger a chain; loop until the board stops changing.\ndef resolve(board):\n    chain = 0\n    while True:\n        matches = find_matches(board)\n        if not matches: break                 # stable: resolution complete\n        chain += 1\n        score += score_for(matches, chain)    # later chain steps score more (see refs)\n        clear(board, matches)                  # remove matched pieces\n        apply_gravity(board)                   # pieces fall into the gaps\n        refill(board, rng)                      # spawn new pieces at the top (seeded RNG)\n    return chain\n```\n\n### 3. Undo via state snapshot or command\n\n```python\n# Pseudocode. Snapshot before each move; undo restores it exactly (board + score + counters + RNG).\ndef make_move(move):\n    history.append(snapshot(board, score, moves_left, rng.state))   # push BEFORE applying\n    apply(move); resolve(board); moves_left -= 1\n\ndef undo():\n    if history:\n        board, score, moves_left, rng.state = history.pop()   # exact revert, including refills\n```\n\nFor large boards prefer the **command** pattern (store the move + enough to invert it) over full\nsnapshots to save memory; snapshots are simplest and fine for small boards.\n\n## Pitfalls \u002F failure modes\n\n- **Mixing logic and visuals** → animations desync from state and cause bugs. The board model is\n  the single source of truth; the view only renders it.\n- **Resolving only once** → cascades\u002Fchains are missed. Loop resolution until the board is stable\n  (Pattern 2).\n- **Undo that doesn't restore everything** → score\u002Fmove-count\u002Frandom-state drift. Snapshot *all*\n  state, or make the move fully invertible. If undo skips the RNG state, redoing the same move\n  refills different pieces and players learn to \"reroll\" by undoing.\n- **Unseeded refill RNG** → can't reproduce a level \u002F no deterministic undo or daily puzzle. Seed it.\n- **Generated boards that aren't solvable** → unfair dead ends. Generate-and-verify, or generate\n  from a known solution backward (refs). A sliding-tile puzzle filled by a random shuffle is\n  unsolvable half the time; check the parity rule in refs §7.\n- **No deadlock detection** (match-3) → board with no valid moves softlocks. Detect \"no moves\"\n  and shuffle or end the level (refs).\n- **Difficulty spikes** → too many mechanics at once. Teach one mechanic per level before combining.\n- **Resolution mid-animation accepts input** → double-moves\u002Fcorruption. Lock input until the\n  board is stable.\n\n## Composition (build it from these skills)\n\n- **Board rendering:** `godot-tilemap` \u002F `unity-tilemap-2d` for the grid; `godot-ui-control` for HUD, score, and menus.\n- **Levels:** `level-design` for hand-authored puzzles and difficulty pacing; `procedural-gen` for solvable generated boards.\n- **Persistence:** `save-systems` for level progress, high scores, and seeded daily puzzles.\n- **Juice:** `game-feel` for match\u002Fcascade pop, screen shake, and chain feedback; the engine animation\u002F`Tween` skill for swaps\u002Ffalls\u002Fclears; `audio-design` for match and chain cues.\n- **Scripting:** `godot-gdscript` \u002F `unity-csharp-scripting` for the resolution loop and rules.\n\n## References\n\n- For match-3 detection\u002Fgravity\u002Frefill\u002Fcascade detail, deadlock detection and reshuffles,\n  sokoban\u002Frule-based puzzles, undo strategies, solvable generation, and scoring, read\n  `references\u002Fboard-and-resolution.md`.\n",{"name":5,"description":7},"main","5d0a87185c0e172c3901e2a6e5916b6d544b8b94","skills\u002Fpuzzle","https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance","https:\u002F\u002Fgithub.com\u002FJunMystery","AI is the typist, I am the architect. Building efficient, secure, and user-centric products through disciplined AI prompt engineering.","2026-11-13 17:41:25",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add JunMystery\u002FAgent-Guidance --skill puzzle",{"tool":37,"command":38},"bunx","bunx skills add JunMystery\u002FAgent-Guidance --skill puzzle",{"tool":40,"command":41},"pnpm","pnpm dlx skills add JunMystery\u002FAgent-Guidance --skill puzzle","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance\u002Fblob\u002Fmain\u002Fskills\u002Fpuzzle\u002FSKILL.md",true,[45],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"references\u002Fboard-and-resolution.md","REFERENCE","参考文档",5896,"https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance\u002Fblob\u002Fmain\u002Fskills\u002Fpuzzle\u002Freferences\u002Fboard-and-resolution.md",[52,58,64,70,76,82],{"skillNo":53,"name":54,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":55,"categories":56,"keywords":57,"publishedAt":19},"01M79QR1E309VJ6CTQKB32AWWA","zero-trust-architecture-cheat-sheet","https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance\u002Fblob\u002Fmain\u002Fskills\u002Fzero-trust-architecture-cheat-sheet\u002FSKILL.md",[],[],{"skillNo":59,"name":60,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":61,"categories":62,"keywords":63,"publishedAt":19},"01M79QQV7GHYR02DYGN41S23WN","xss-filter-evasion-cheat-sheet","https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance\u002Fblob\u002Fmain\u002Fskills\u002Fxss-filter-evasion-cheat-sheet\u002FSKILL.md",[],[],{"skillNo":65,"name":66,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":19},"01M79QQNSN7YB8XB61FFSCS3WH","xs-leaks-cheat-sheet","https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance\u002Fblob\u002Fmain\u002Fskills\u002Fxs-leaks-cheat-sheet\u002FSKILL.md",[],[],{"skillNo":71,"name":72,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M79QQHZZJKFDY9132G5A65C2","xpath-injection-prevention-cheat-sheet","https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance\u002Fblob\u002Fmain\u002Fskills\u002Fxpath-injection-prevention-cheat-sheet\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":19},"01M79QQB9ZSD3DJG8658EHQXR1","xml-security-cheat-sheet","https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance\u002Fblob\u002Fmain\u002Fskills\u002Fxml-security-cheat-sheet\u002FSKILL.md",[],[],{"skillNo":83,"name":84,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":19},"01M79QQ60WKV7PFMXWT9CW8PM6","xml-external-entity-prevention-cheat-sheet","https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance\u002Fblob\u002Fmain\u002Fskills\u002Fxml-external-entity-prevention-cheat-sheet\u002FSKILL.md",[],[]]