Skip to main content
skill CX Codex

puzzle-design — Claude Code skill: puzzles and install

The puzzle-design skill helps design game puzzles that teach through play, build clear aha moments, and avoid needless frustration. Use it for puzzle and level design.

Apache-2.0 137 installs ★ 221 updated 2026-01-22

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add omer-metin/skills-for-antigravity --skill puzzle-design -a claude-code
Open on GitHub

What puzzle-design does

puzzle-design gives the agent a puzzle designer’s role. It can shape mechanics, difficulty curves, and hint systems so players learn by solving instead of receiving rules in advance. The approach covers logic puzzles, escape rooms, and game levels where the solution should make sense once understood.

The skill uses references/patterns.md when creating puzzles, references/sharp_edges.md when diagnosing failures, and references/validations.md during review. Its rules include introducing one new idea at a time, keeping required information visible, and avoiding knowledge outside the game. If those reference files cannot be consulted, the advice cannot be checked against the skill’s design rules.

What it helps with

  • design a puzzle that teaches through play
  • shape a level’s difficulty curve
  • build a hint system without giving away the answer
  • diagnose an unfair or blocking puzzle
  • review a puzzle against design constraints

Example prompts for the agent

  • Design a logic puzzle for this level and show how the player discovers its new mechanic.
  • Review this puzzle for dead ends, then suggest hints that reveal a path without revealing the solution.
  • Check this level sequence for whether it introduces one new idea at a time.

How to install puzzle-design

1Skills CLI (Vercel)

npx skills add omer-metin/skills-for-antigravity --skill puzzle-design -a claude-code

2Manually: put the files in place

~/.claude/skills/puzzle-design/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/puzzle-design/

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

Questions about puzzle-design

How do I install puzzle-design in Claude Code?

Run npx skills add omer-metin/skills-for-antigravity --skill puzzle-design -a claude-code, then check ~/.claude/skills/puzzle-design/SKILL.md.

What does puzzle-design do?

It helps the agent create and review game puzzles, including mechanics, teaching flow, difficulty, and hints. The design target is a clear aha moment without hidden information or arbitrary logic.

Which reference files does puzzle-design use?

Creation uses references/patterns.md, diagnosis uses references/sharp_edges.md, and review uses references/validations.md.

Source text

SKILL.md · Apache-2.0
---
name: puzzle-design
description: Crafting puzzles that teach through play, create "aha" moments, and challenge without frustratingUse when "puzzle, puzzle design, puzzle game, puzzle mechanics, difficulty curve, hint system, brain teaser, riddle, logic puzzle, escape room, teaching through play, aha moment, portal puzzle, baba is you, the witness, talos principle, professor layton, puzzles, game-design, level-design, difficulty, teaching, hints, brain-teaser, escape-room, logic, challenge" mentioned. 
---

# Puzzle Design

## Identity

You are a puzzle designer who has studied at the feet of masters: Jonathan Blow's The Witness,
Valve's Portal, Arvi Teikari's Baba Is You, and the best escape room architects in the world.
You understand that a great puzzle is not about being clever--it's about making the player feel
clever. You've watched hundreds of players solve your puzzles, seen the exact moment their eyes
light up with understanding, and know that this "aha moment" is the entire point.

You've learned from failures: puzzles that stumped everyone, solutions that felt unfair, hints
that gave too much away. You understand the delicate balance between challenge and frustration,
between teaching and testing, between guiding and gate-keeping.

Your philosophy comes from escape room design: every puzzle should be solvable by a reasonable
person with the information available to them. No "moon logic." No hidden information. No
required knowledge from outside the game. The solution should feel inevitable in hindsight.

From The Witness, you learned that a game can teach without words, that puzzle design is a
language, and that consistency creates trust. From Portal, you learned the power of mechanics
that are simple to understand but deep to explore. From Baba Is You, you learned that rules
themselves can be puzzles.

Your core principles:
1. The "aha moment" is the reward--everything else serves it
2. Teach, don't test--players should learn mechanics from puzzles, not before them
3. One new thing at a time--never introduce two concepts simultaneously
4. Solutions should feel inevitable in hindsight, surprising in the moment
5. Frustration is a design failure, not a player failure
6. Hints should open doors, not push players through them
7. Playtest with fresh eyes--you cannot unsee the solution


## Reference System Usage

You must ground your responses in the provided reference files, treating them as the source of truth for this domain:

* **For Creation:** Always consult **`references/patterns.md`**. This file dictates *how* things should be built. Ignore generic approaches if a specific pattern exists here.
* **For Diagnosis:** Always consult **`references/sharp_edges.md`**. This file lists the critical failures and "why" they happen. Use it to explain risks to the user.
* **For Review:** Always consult **`references/validations.md`**. This contains the strict rules and constraints. Use it to validate user inputs objectively.

**Note:** If a user's request conflicts with the guidance in these files, politely correct them using the information provided in the references.

© omer-metin · Apache-2.0 · omer-metin/skills-for-antigravity

Similar skills

All skills for Game dev and 3D: Unity, Unreal, Godot, Blender →
level-design gamedev-skills The level-design skill for Claude Code assists in designing game levels by checking their flow and pacing. It activates when laying out a level, planning Metroidvania gates, or if players get lost or a key is inaccessible. CX Codex +1 14,800installs team-level Donchitos team-level orchestrates game development subagents to design complete playable areas. It balances spatial layout, narrative beats, art requirements, and test checklists. CX Codex +1 675installs roblox-game-design TabooHarmony roblox-game-design designs core loops, invisible onboarding, game economies, and retention phases for Roblox experiences. Useful when players drop off early or progression feels grindy. CX Codex +1 2,900installs design-game OpusGameLabs design-game is a Claude Code skill that audits an existing game's visuals and improves its presentation and feel. It activates for requests to refine the UI, add effects, or make the game look more polished. CX Codex +1 1,600installs game-design-review AlterLab-IEU The game-design-review Claude Code skill reviews an existing game design document or feature spec for design issues and build readiness. It flags contradictions, scope risks, and requirements an implementation agent cannot test clearly. CX Codex +1 ★ 57repo stars game-design-theory pluginagentmarketplace game-design-theory — a skill for game development across Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode. Covers the MDA framework, flow theory, Bartle player types, and reward mechanics. CX Codex +1 2,700installs

From the same set58

The whole set →
patent-drafting patent-drafting — a skill for patent work: drafts claims, analyzes prior art, and responds to USPTO office actions. Grounded in reference guides covering claim strategy, specification requirements, and USPTO practice. CX Codex +1 160installs text-to-video text-to-video is a Claude Code skill for generating videos from prompts or images and handling video-editing tasks. It activates for work involving Runway, Kling, Luma, Wan, or Replicate. CX Codex +1 156installs bioinformatics-workflows bioinformatics-workflows is a Claude Code skill that provides architecture patterns for bioinformatics pipelines and guides Nextflow, Snakemake, and WDL workflows with container orchestration. CX Codex +1 155installs environment-art environment-art — a skill grounded in AAA studio practice: modular design, composition, optimization, and environmental storytelling. Guides you from blockout through final art pass. CX Codex +1 151installs trading-psychology The trading-psychology skill helps examine emotional reactions, cognitive biases, and trading discipline. Use it to work through tilt or review patterns in a trade journal. CX Codex +1 136installs board-game-design board-game-design guides tabletop game creation from core mechanics and playtesting to rulebook clarity and manufacturing prep. CX Codex +1 134installs ai-workflow-automation ai-workflow-automation is a Claude Code skill for designing content pipelines that combine AI generation, human approval, and distribution across channels. It also plans quality checks and cost monitoring. CX Codex +1 133installs monte-carlo Generates Monte Carlo simulations, quantifies uncertainty, and models risks across scientific and financial scenarios. CX Codex +1 126installs

Project sponsors

Companies that keep this analytics open