@jarrodmedrano/claude-skills 1.0.2 → 1.0.4

package/.claude/skills/level-design/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: level-design
+description: >
+  Level design consulting based on "Level Design: Processes and Experiences"
+  (CRC Press). Use when helping with spatial game design, environment layout,
+  player guidance, pacing, open-world planning, hiding linearity, themed
+  environments, procedural vs handmade content, play-personas, or evaluating
+  level quality. Covers horror level design, indie game practices, and
+  AAA open-world techniques. NOT for coding - focused on design philosophy
+  and player spatial experience.
+---
+
+# Level Design Skill
+
+A design consulting framework based on "Level Design: Processes and Experiences" edited by Christopher W. Totten (CRC Press, 2017).
+
+## Core Philosophy
+
+Level design is the **thoughtful execution of gameplay into gamespace for players to dwell in**. It sits at the intersection of programming, design, and art—implementing the game design vision while leading players through experiences without revealing the designer's presence.
+
+> "Level designers don't merely create things for players to do. They create situations that invite players to interpret who they are." — Brian Upton
+
+---
+
+## The Designer's Core Tasks
+
+1. **Guide without forcing** — Lead players through intended experiences while maintaining illusion of freedom
+2. **Teach through space** — Use environment to communicate mechanics, not tutorials
+3. **Control pacing** — Modulate intensity through spatial rhythm and stillness
+4. **Support narrative** — Align levels within overall game progression
+5. **Create consistency** — Establish and honor environmental rules players can rely on
+
+---
+
+## Quick Reference: Level Types
+
+| Type | Key Considerations |
+|------|-------------------|
+| **Linear** | Hide linearity through visual choice, narrative lures, environmental storytelling |
+| **Open-World** | POI density, anchor locations, subregions, orientation landmarks |
+| **Horror** | Anticipatory play, corners, one-way doors, visible-but-blocked escape |
+| **Procedural** | Horizontal vs vertical integration of handmade content |
+| **Indie/Focused** | Expand single core mechanic through level variation |
+
+---
+
+## Hiding Linearity
+
+Players must feel in control even when following a predetermined path.
+
+### Techniques
+
+| Technique | Description |
+|-----------|-------------|
+| **Coerced Progression** | Time pressure, pursuing enemies—no time to question the path |
+| **Environmental Signage** | In-world signs, color coding (Mirror's Edge red) |
+| **NPC Guides** | Companions who lead, escort targets who follow, enemies to chase |
+| **Narrative Lures** | Visible objectives, story hooks that pull forward |
+| **Forced Choice Illusion** | Block one path as player approaches, making "choice" feel organic |
+
+### What Breaks the Illusion
+
+- Arbitrary locked doors
+- Invisible walls
+- Flimsy barriers (yellow police tape blocking a superhero)
+- Clear artificial constraints without narrative justification
+
+**See**: `references/hiding-linearity.md`
+
+---
+
+## Anticipatory Play & Horror Design
+
+Horror isn't about jump scares—it's about **dread before the corner**.
+
+### The P.T. Framework
+
+- **Corners** — Hide what's ahead; players imagine horrors worse than you could show
+- **Ratchet Doors** — One-way progress; can't retreat, must face what's ahead
+- **Valve Doors** — Block progress temporarily; visible state reduces uncertainty about *if* blocked
+- **Visible Escape** — Show impossible exits to amplify feeling of being trapped
+
+### Key Principle
+
+> "Anticipatory play requires variety—the situation must evolve so players continually reassess. Static horrors become played out."
+
+**See**: `references/anticipatory-play.md`
+
+---
+
+## Open-World Planning (Burgess Method)
+
+Three living documents for large-scale world design:
+
+### 1. The World Map
+- Establish setting, scale, subregions
+- Plot anchor locations (story-critical, landmarks)
+- Include orienting features (visible from anywhere)
+- Plan natural boundaries (water, cliffs) over artificial walls
+
+### 2. The Master List (Excel)
+- Every location with X/Y coordinates
+- Columns for: designer, quest associations, footprint size, difficulty, encounter type
+- Scatter graph overlay on map image
+- Filter to visualize distribution patterns
+
+### 3. The Directory (Wiki)
+- Per-location pages with: status, goals, walkthrough, known issues, to-do
+- Category tags for filtering (by designer, by pass, by type)
+- Living documentation updated throughout development
+
+### POI Density
+
+The frequency of points of interest defines exploration feel:
+- **High density** = Theme park feel (GTA cities)
+- **Low density** = Vast, sparse exploration (Just Cause countryside)
+- **Non-uniform** = Urban cores dense, rural areas sparse (Fallout 4)
+
+**See**: `references/open-world-planning.md`
+
+---
+
+## Play-Personas
+
+Model player behavior before and after implementation.
+
+### The Process
+
+1. **Analyze mechanics** → Derive high-level behaviors from low-level actions
+2. **Create matrix** → Plot all behavioral combinations (2^n personas)
+3. **Select cast** → Choose 2-3 personas aligned with design vision
+4. **Associate affordances** → Link behaviors to spatial/ludic elements
+5. **Orchestrate** — Modulate which personas are viable throughout level
+6. **Validate** — Use telemetry to confirm players match expected personas
+
+### Example: Pac-Man
+
+High-level behaviors: Center vs periphery dwelling, early vs late pill eating, linear vs broken paths
+
+→ 8 persona combinations including "Fraidy Cat" (periphery, early pills, linear) and "Risk Taker" (center, late pills, broken)
+
+**See**: `references/play-personas.md`
+
+---
+
+## Themed Level Tropes
+
+Classic environmental themes with established mechanics and expectations:
+
+| Trope | Core Elements | Design Advantages |
+|-------|---------------|-------------------|
+| **Fire/Ice** | Environmental hazards, timing puzzles | Color variety, physics tweaks |
+| **Dungeon/Cavern** | Tileable textures, traps, treasure | Easily repeatable, expected danger |
+| **Factory** | Moving platforms, conveyers, gears | Repurposable mechanics, scalable difficulty |
+| **Jungle** | Vines, branches, water, wildlife | Fluid movement, colorful outdoor |
+| **Spooky** | Atmosphere, surprise, undead | Combines with any theme |
+| **Pirate** | Ships, treasure, melee, water | Action-ready, clear rewards |
+| **Urban** | Verticality, cover, vehicles | Real-world familiarity |
+| **Space Station** | Tech hazards, airlocks, zero-G | Sci-fi dungeon equivalent |
+| **Sewer** | Pipes, rats, rising water | Modern dungeon stand-in |
+
+**Mexican Pizza Technique**: Combine two tropes for fresh results (fire + graveyard, jungle + urban ruins)
+
+**See**: `references/themed-environments.md`
+
+---
+
+## Indie Level Design Practices
+
+When working with limited resources:
+
+| Practice | Description |
+|----------|-------------|
+| **Expand Core Mechanic** | One strong mechanic explored through level variation (VVVVVV) |
+| **Iterative Level Design** | Rapid prototyping, playtest early and often |
+| **Design Modes Not Levels** | Create systems that generate challenge (endless runners) |
+| **Embrace Emergence** | Simple rules, complex interactions |
+| **Object-Oriented Design** | Modular elements that combine predictably |
+
+### Qualities of Good Level Design
+
+- Maintain flow: challenge without anxiety or boredom
+- Balance freedom with constraints (illusion of control)
+- Enable mastery and emergent solutions
+- Balance risk and reward proportionally
+- Guide without being obvious
+
+**See**: `references/indie-practices.md`
+
+---
+
+## Procedural vs Handmade Integration
+
+Two integration models:
+
+### Vertical Integration
+Handmade thread runs through procedural content (FTL quest chains, Spelunky secrets)
+
+**Best for**: Narrative, puzzle sequences, coherent story beats
+
+### Horizontal Integration
+Procedural and handmade content interchangeable in same slot (Dungeon Crawl vaults, URR buildings)
+
+**Best for**: Ensuring specific gameplay moments, quality floors
+
+### Key Decision
+**Should players see which is which?**
+- **Yes** (DCSS): Visual variety, risk/reward clarity
+- **No** (URR): Quality perception, seamless experience
+
+**See**: `references/procedural-handmade.md`
+
+---
+
+## Level Evaluation Framework
+
+When evaluating a level design:
+
+1. **Player Guidance**: Can players find their way without obvious signposting?
+2. **Pacing**: Does intensity modulate appropriately? Are there moments of stillness?
+3. **Teaching**: Does the space teach mechanics before testing them?
+4. **Consistency**: Do environmental rules remain predictable?
+5. **Persona Fit**: Does the level support intended play styles?
+6. **Density**: Is POI distribution appropriate for the experience?
+7. **Linearity Illusion**: Do players feel in control of their path?
+
+---
+
+## Common Pitfalls
+
+| Pitfall | Symptom | Solution |
+|---------|---------|----------|
+| Obvious Rails | Player comments on being "on rails" | Add visual choice, narrative justification |
+| Empty Space | Players comment on emptiness | Increase POI density or justify sparseness |
+| Lost Players | Players wander aimlessly | Add orientation landmarks, environmental cues |
+| Played-Out Scares | Horror stops being scary | Keep threats evolving, limit exposure time |
+| Arbitrary Barriers | Players frustrated by blocked paths | Use narrative-justified or natural boundaries |
+| Tutorial Overload | Players skip to "real game" | Teach through safe early gameplay |
+
+---
+
+## Key Mantras
+
+- **"Hide the designer's hand."** Players should feel they're discovering, not being led.
+- **"Corners are always significant."** Transitions between visible and hidden create anticipation.
+- **"POI density defines feel."** Sparse = vast exploration; dense = action-packed.
+- **"Static threats become furniture."** Evolve dangers or limit exposure.
+- **"The illusion of choice is enough."** Players interpret forced choices as agency.
+- **"Mexican pizza your themes."** Combine familiar tropes for fresh experiences.

package/.claude/skills/level-design/anticipatory-play.md

@@ -0,0 +1,223 @@
+# Anticipatory Play & Horror Level Design
+
+Based on Chapter 9: "P.T. and the Play of Stillness" by Brian Upton.
+
+## Core Insight
+
+Horror games are scary not because of what happens, but because of what players **imagine** will happen. The best horror level design creates **anticipatory play**—moments of stillness where players' minds race with possibilities.
+
+> "We don't win a scary game by overcoming its challenges. We win by allowing it to thwart us."
+
+---
+
+## The Five Principles of Anticipatory Play
+
+### 1. Invitation
+Create situations where players feel invited to engage with ambiguity. Visible choices with unclear outcomes.
+
+### 2. Elaboration
+Choices should have clear, elaborated consequences. If you take path A, you can imagine what might happen.
+
+### 3. Predictability
+Some outcomes should be predictable—players need anchors to build expectations from.
+
+### 4. Uncertainty
+But not everything predictable. The tension between knowing and not-knowing creates anticipation.
+
+### 5. Satisfaction
+Even in horror, players need to feel resolution is possible. "Maybe this is it!" beats "I have no idea."
+
+---
+
+## The P.T. Level Analysis
+
+### The Layout
+A simple L-shaped corridor, looped infinitely:
+- Entrance door (one-way ratchet)
+- First half: visible, safe-feeling
+- Corner: hides second half
+- Second half: where bad things happen
+- Bathroom door: sometimes open, sometimes locked
+- Exit door (valve): blocks or allows progress
+- Front door: permanently locked—visible escape that's impossible
+
+### The Corner
+
+The most important element in the entire game.
+
+**Why corners work:**
+- Binary: Can't see around them, then can
+- Analog: You can peek, retreat, approach slowly
+- Ambiguous: Anything could be waiting
+- Controllable: Player chooses when to turn
+
+> "Just walking toward the corner and making the turn is enough to fill us with dread. It doesn't matter that most of the time nothing at all is waiting."
+
+**Corner vs. Door:**
+- Doors are abrupt reveals (open/closed)
+- Corners are gradual reveals (continuous unfolding)
+- Corners allow hesitation; doors demand commitment
+
+---
+
+## The Four Doors of P.T.
+
+### 1. The Ratchet Door (Entrance/Exit)
+One-way passage. You can only go forward.
+
+**Purpose:**
+- Eliminates backtracking as possibility
+- Forces players to face what's ahead
+- Removes problem-solving distraction ("maybe there's another way")
+- Focuses attention entirely on dread
+
+> "The implacable barrier of the one-way door behind us removes the temptation to treat our situation as a puzzle to be solved."
+
+### 2. The Valve Door
+Blocks progress sometimes. Visually obvious when locked.
+
+**Why separate from ratchet:**
+- Clear visual state (locked or open) from anywhere
+- Player knows immediately if blocked
+- No wasted time checking
+- Keeps attention on *what to do*, not *whether blocked*
+
+### 3. The Bathroom Door
+Source of specific horrors. Sometimes open, sometimes locked.
+
+**The Bathroom as Intensified Corner:**
+- Everything bad comes from here
+- Opening it requires crossing threshold into darkness
+- Game trains players to fear it through early jump scares
+- When forced inside, door closes—player feels they're *hiding*, not *trapped*
+
+### 4. The Front Door (Impossible Escape)
+Never opens. Permanently locked. But always visible.
+
+**Purpose:**
+- Reminder that escape *exists* as a concept
+- Tantalizingly close, never achievable
+- Amplifies horror by showing what you can't have
+- Without it, players might forget escape is even possible
+
+> "If you want players to feel trapped, you need to tantalize them with escape routes."
+
+---
+
+## Repetition and Training
+
+### The Loop Mechanism
+P.T. sends players through the same corridor repeatedly. At first, this is boring. Then:
+
+1. Something changes (jump scare)
+2. Players learn: changes happen in second half
+3. Future loops: anticipation builds before corner
+4. The corridor itself becomes the scare
+
+### Training Dread
+Early loops establish expectations:
+- First half = safe
+- Corner = transition
+- Second half = danger
+- Bathroom = source of danger
+
+Once trained, the game can scare without doing anything. The player's imagination does the work.
+
+---
+
+## The "Played Out" Problem
+
+### Static Threats Lose Power
+
+The fetus in the sink:
+- First glimpse: genuinely horrifying
+- After 30 seconds: unsettling
+- After 2 minutes: just furniture
+
+> "The longer we're trapped in the bathroom with it, the less scary the fetus becomes—it's played out as a locus of interpretive play."
+
+### Preventing Play-Out
+
+1. **Evolve the threat** — Movement, change, escalation
+2. **Limit exposure** — Brief glimpses, then gone
+3. **Keep it ambiguous** — Never fully explained
+4. **Multiple encounters** — Same threat in different contexts
+
+### The Lisa Ghost (Done Right)
+- Appears in multiple places
+- Always brief encounters
+- Retreats into darkness before becoming familiar
+- On balcony: visible only if you look up at right moment
+
+---
+
+## Architectural Horror Techniques
+
+### Visible/Invisible Balance
+- Balcony: Not in normal sightline, but visible if you look
+- Creates paranoia about unseen spaces
+- When something appears there, retroactive fear ("it was there all along")
+
+### Darkness as Canvas
+- Black windows in corridor
+- Dark back of balcony
+- These are blank spaces for imagination to fill
+
+### Misdirection Objects
+- Coat rack positioned to look human from corner of eye
+- Cluttered surfaces invite close inspection (reducing peripheral awareness)
+- Environmental details that distract from actual threats
+
+---
+
+## The Metaphysical Claustrophobia
+
+Horror games thwart agency deliberately:
+- Movement is slow
+- Aiming is inaccurate
+- Weapons are ineffective
+- Escape is impossible
+
+**This creates "possibility space claustrophobia":**
+- Not just trapped in space
+- Trapped in *options*
+- All choices feel bad
+- No good move exists
+
+> "You feel trapped in a too-small possibility space. Your options for action all feel dangerous and uncertain."
+
+---
+
+## Design Framework for Horror Levels
+
+### 1. Create Stillness
+Reduce interactive demands. Let players think, imagine, dread.
+
+### 2. Hide What's Ahead
+Corners, darkness, closed doors. The unknown is scarier than the known.
+
+### 3. Establish Then Subvert
+Train expectations, then break them. But not too often.
+
+### 4. Limit Exposure
+Brief glimpses of horror, not extended encounters.
+
+### 5. Show Impossible Escape
+Tantalize with exits that can't be used.
+
+### 6. Use One-Way Progress
+Eliminate backtracking as an option.
+
+### 7. Make Blocking Visible
+If players can't progress, make that clear—don't waste dread on uncertainty about state.
+
+### 8. Interpret Actions for Players
+When players can't act, design so their inaction *feels* like a choice.
+
+---
+
+## Key Principle
+
+> "Level design is not merely a matter of arranging things for players to do. It's also a matter of constructing situations that encourage players to hold still while they plan or interpret."
+
+The scariest moments in horror games aren't jump scares. They're the seconds before the jump scare that never comes.

package/.claude/skills/level-design/hiding-linearity.md

@@ -0,0 +1,181 @@
+# Hiding Linearity in Level Design
+
+Based on Chapter 10: "The Illusion of Choice" by João Raza and Benjamin Carter.
+
+## Core Principle
+
+A successful narrative-driven game must sustain the illusion of free will. The designer's job is to hide the contrivances of level design—go down *this* corridor, open *this* door—without making players feel their hand is forced.
+
+> "The illusion of motion in film is a trick of the brain that works every time. Hiding the artifice in a game depends on distraction and psychological suggestion."
+
+---
+
+## Coerced Progression
+
+The simplest approach: give players no time to question their path.
+
+### Time Pressure
+- Scrolling screens that push players forward (Super Mario Bros. 3 airship levels)
+- Collapsing environments
+- Pursuing enemies (Half-Life 2 opening)
+
+### The Call of Duty Stalingrad Technique
+Players queue for ammunition but are pushed onto the battlefield unarmed. Retreat means death from commanding officers. Players are too busy surviving to question direction.
+
+**Key insight**: When players are struggling to stay alive, they don't debate whether to backtrack.
+
+---
+
+## Environmental Guidance
+
+### Signage Systems
+- Painted arrows, floor markings
+- Color-coded paths (Mirror's Edge red highlights)
+- In-world signs that make sense contextually
+
+### Half-Life Approach
+Opening sequence has players navigate benign corridors. Security guards provide narrative excuses for blocked paths ("You don't have clearance"). Players follow painted lines to destinations—feeling like navigation, not railroading.
+
+### Highway 17 (Half-Life 2)
+The level is literally a road. Players know the destination is at the end of Highway 17. The road always leads forward. Simple, elegant, invisible guidance.
+
+---
+
+## NPC-Based Guidance
+
+### Escort Missions
+Vulnerable NPCs guide players while needing protection:
+- NPCs unlock doors players cannot (Half-Life retinal scanners)
+- NPCs know the route and lead the way
+- Players feel protective, not led
+
+### Companion Characters
+- Alyx Vance (Half-Life 2) guides without feeling like a guide
+- Ellie (The Last of Us) comments when players idle too long or explore pointlessly
+- Companions create social pressure to move forward
+
+### The Chase
+Instead of following a guide, chase an enemy:
+- Mirror's Edge: Faith chases an equally-capable enemy
+- Creates urgency without pursuit threat
+- Tarrying means losing the target
+
+---
+
+## Narrative Lures
+
+### Visual Objectives
+- Distant landmarks that players want to reach
+- Lit areas drawing attention through darkness
+- Unique architecture standing out from environment
+
+### Architectural Hierarchy
+Important paths should be:
+- More visually interesting
+- Better lit
+- More open
+- Feature unique elements
+
+Dead ends should be:
+- Visually less interesting
+- Darker
+- Narrower
+- More generic
+
+### The Door Metaphor
+- Open doors invite
+- Locked doors close off
+- But make sure locked doors have narrative justification
+
+---
+
+## What Breaks the Illusion
+
+### Arbitrary Barriers
+| Bad Example | Why It Fails |
+|-------------|--------------|
+| Yellow police tape | A superhero can't cross tape? |
+| Waist-high walls | Player can jump buildings but not fences |
+| Locked doors without context | Why is this door special? |
+| Invisible walls | No explanation at all |
+
+### Better Alternatives
+- Natural barriers (cliffs, water, fire)
+- Narrative barriers (guards, lockdowns, collapsed structures)
+- Overwhelming force (too many enemies in wrong direction)
+- Environmental hazards (radiation, toxic air)
+
+---
+
+## The Forced Choice
+
+When there's only one real option, design the moment so players interpret constraint as choice.
+
+### P.T. Bathroom Example
+The player is trapped in the bathroom. The door is mechanically locked—player can't open it. But because the handle rattles as if something's trying to get in, players feel like they're *hiding*, not *trapped*.
+
+> "The game creates a situation where there's a particular action we want to take. It then responds as though we had done what we wanted to do, even though there's no way for us to do it."
+
+### RPG Main Quests
+Players feel they *choose* to storm the castle and rescue the princess. In reality, there's no other option. The illusion of agency is enough.
+
+---
+
+## Branching Illusions
+
+### The Fork Technique
+1. Present players with two paths
+2. As player approaches one, block it (enemies appear, door locks, explosion)
+3. Player "chooses" the remaining path
+4. Both paths lead to the same destination anyway
+
+### The Hub-and-Spoke
+Players can explore "freely" but:
+- All paths return to a central hub
+- True progress gates require specific items/actions
+- Exploration feels optional but forward path is singular
+
+---
+
+## Audio and Attention Cues
+
+### Sound Design
+- Distant sounds draw attention toward objectives
+- Ambient audio creates "safe" vs "dangerous" zones
+- Music intensifies toward correct paths
+
+### Lighting
+- Brighter areas feel more inviting
+- Players naturally move toward light
+- Use darkness to discourage wrong paths
+
+---
+
+## Testing Linearity Hiding
+
+### Player Observation
+Watch for:
+- Players commenting on feeling "on rails"
+- Players attempting to go backward or off-path
+- Frustration at barriers
+- Questions about why paths are blocked
+
+### Successful Hiding
+Players should:
+- Feel like they're exploring
+- Not notice most blocked paths
+- Accept narrative barriers without question
+- Report feeling "in control"
+
+---
+
+## Summary Framework
+
+1. **Time pressure** eliminates questioning
+2. **Environmental cues** guide without forcing
+3. **NPCs** provide social and narrative direction
+4. **Narrative lures** pull players forward
+5. **Forced choices** feel like agency
+6. **Barriers need justification**—narrative or natural
+
+The goal isn't to give players freedom—it's to make them *feel* free while experiencing your intended sequence.