@jarrodmedrano/claude-skills 1.0.2 → 1.0.3

package/.claude/skills/game-design-theory/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: game-design-theory
+description: >
+  Game design consulting based on Richard Rouse III's Game Design Theory and Practice.
+  Use when helping with game design decisions, player psychology, gameplay systems,
+  storytelling, playtesting, or evaluating fun. Provides frameworks for understanding
+  what players want, creating engaging gameplay mechanics, balancing challenge and fun,
+  non-linear design, in-game storytelling, and effective playtesting practices.
+  NOT for coding or programming - focused on design philosophy and player experience.
+---
+
+# Game Design Theory Skill
+
+A design consulting framework based on principles from "Game Design: Theory & Practice" by Richard Rouse III.
+
+## When to Use This Skill
+
+- Evaluating game concepts for player appeal
+- Designing gameplay mechanics and systems
+- Analyzing why a game is or isn't fun
+- Balancing difficulty and challenge
+- Creating non-linear experiences
+- Integrating story with gameplay
+- Planning and conducting playtesting
+- Making design trade-off decisions
+
+## Core Philosophy
+
+Games are about **player experience**, not designer intention. The goal is to merge the "designer's story" with the "player's story"—allowing players to feel authorship over their experience while guided by thoughtful design.
+
+> "Not to make something sell, something very popular, but to love something, and make something that we creators can love. It's the very core feeling we should have in making games." — Shigeru Miyamoto
+
+## Quick Reference
+
+### Why Players Play
+1. **Challenge** - Engaging the mind, learning through problem-solving
+2. **Socialization** - Shared experiences, connection with others
+3. **Dynamic Solitary Experience** - Interactive engagement without social demands
+4. **Bragging Rights** - Achievement, mastery, self-satisfaction
+5. **Emotional Experience** - Tension, catharsis, meaningful feelings
+6. **Fantasy** - Escapism, becoming someone else, safe experimentation
+
+### What Players Expect
+- A **consistent world** with predictable cause-and-effect
+- Clear **understanding of boundaries** and possible actions
+- **Reasonable solutions** to work (multiple paths to success)
+- **Direction** without hand-holding
+- **Incremental progress** toward goals
+- **Immersion** maintained throughout
+- A **fair chance** at success
+- To **do**, not to watch
+- To **not get hopelessly stuck**
+
+### Elements of Good Gameplay
+- **Emergence**: Systems interacting to create unplanned, player-discovered solutions
+- **Non-linearity**: Multiple paths, solutions, orderings, and optional content
+- **Appropriate Reality Modeling**: Only simulate what serves fun
+- **Teaching Through Play**: First minutes make or break engagement
+- **Transparent Controls**: Input that disappears into instinct
+
+## Detailed References
+
+For deeper guidance, consult these reference files:
+
+- **Player Psychology**: See [references/player-psychology.md](references/player-psychology.md) for why players play and what they expect
+- **Gameplay Elements**: See [references/gameplay-elements.md](references/gameplay-elements.md) for emergence, non-linearity, and system design
+- **Storytelling**: See [references/storytelling.md](references/storytelling.md) for in-game narrative techniques
+- **Playtesting**: See [references/playtesting.md](references/playtesting.md) for testing practices and balancing
+- **Design Principles**: See [references/design-principles.md](references/design-principles.md) for focus, teaching, and I/O design
+
+## Design Evaluation Framework
+
+When evaluating a game design, ask:
+
+1. **Player Motivation**: Which core motivations does this serve? (Challenge, Social, Solitary, Bragging, Emotional, Fantasy)
+2. **Expectation Alignment**: Does the design honor what players expect?
+3. **Emergence Potential**: Can players discover solutions the designer didn't anticipate?
+4. **Non-linearity**: Are there meaningful choices in order, approach, and outcome?
+5. **Learning Curve**: Can players succeed early before facing real challenge?
+6. **Immersion Maintenance**: What might break suspension of disbelief?
+7. **Balance Reality**: Is the simulation serving fun, or drowning in tedium?
+
+## Common Design Pitfalls
+
+| Pitfall | Symptom | Solution |
+|---------|---------|----------|
+| Overly Linear | Player feels "on rails" | Add order/approach choices |
+| Anticipatory-Only Design | Only hardcoded solutions work | Build systems, not cases |
+| Reality Obsession | Tedious simulation of mundane details | Model only what's fun |
+| Inconsistent Rules | Same action gives different results randomly | Ensure predictable cause-effect |
+| Tutorial Overload | Players skip to "real game" | Teach through safe early gameplay |
+| Hidden Information | Players fail without knowing why | Provide clear feedback |
+| Designer's Ego | "Players will adjust" | Playtest with fresh eyes |
+| Difficulty Blindness | "It's not that hard" | Your game is too hard. Always. |
+
+## Key Mantras
+
+- **"Your game is too hard."** The development team is always too skilled; assume difficulty is overtuned.
+- **"Show, don't tell."** In-game storytelling > cut-scenes > manuals.
+- **"Less is more."** Every control added must justify its complexity cost.
+- **"Players want to do, not watch."** Minimize non-interactive sequences.
+- **"The player's story matters most."** Let their choices shape the experience.

package/.claude/skills/game-design-theory/design-principles.md

@@ -0,0 +1,308 @@
+# Design Principles
+
+Core principles for maintaining focus, teaching players, and designing effective input/output systems.
+
+## Focus
+
+> "Developing a game for two years with a team of twenty people can sometimes more resemble a war than the creation of art."
+
+During development conflicts, games become unfocused. Maintaining a clear vision throughout is essential to creating something coherent and compelling.
+
+### Establishing Focus
+
+Before development begins, define:
+1. **Core experience**: What feeling/experience defines this game?
+2. **Primary mechanics**: What does the player DO most of the time?
+3. **Target audience**: Who is this for?
+
+Everything should serve the focus. Features that don't—however cool—dilute the game.
+
+### The Function of Focus
+
+Focus acts as a filter:
+- "Does this feature serve our core experience?" → Yes: Consider. No: Cut.
+- "Does this mechanic support our primary gameplay?" → Yes: Develop. No: Simplify.
+
+**Example decisions**:
+- Action game focused on combat → Limit inventory management
+- Puzzle game focused on logic → Reduce time pressure
+- Exploration game focused on discovery → Add secrets, reduce combat
+
+### Maintaining Focus Through Conflict
+
+Team members will have different visions:
+- Programmer wants technical showcase
+- Artist wants visual fidelity
+- Designer wants systemic depth
+- Producer wants safe market bet
+
+**Focus resolves conflicts**: When disagreements arise, return to established focus. Which approach better serves the core experience?
+
+### Changing Focus
+
+Sometimes mid-development discoveries require focus adjustment:
+- Playtest reveals unexpected fun in secondary system
+- Technical limitations prevent core vision
+- Market conditions shift
+
+**Rules for changing focus**:
+1. Change deliberately, not by drift
+2. Communicate change to entire team
+3. Re-evaluate all existing work against new focus
+4. Accept some rework as necessary
+
+### Sub-Focuses
+
+Large games may have distinct sections with different focuses:
+- Combat levels vs. puzzle levels
+- Hub world vs. dungeons
+- Story sequences vs. gameplay sequences
+
+Each sub-section can have its own sub-focus that serves the game's overall focus.
+
+---
+
+## Teaching the Player
+
+The first few minutes determine whether players continue or quit.
+
+> "When a player tells a friend about your game, she will often remember those first few minutes and say, 'Well, it was a little weird to get used to' or, preferably, 'It was great. I jumped right into the game and found all this cool stuff.'"
+
+### The Manual Is Dead
+
+In the past, games relied on manuals to teach players. This worked when:
+- Games were simpler
+- Players were more dedicated
+- There was no alternative
+
+**Today's reality**:
+- Manuals unread (or PDFs unopened)
+- Players expect to learn by playing
+- Friction in first minutes = uninstall
+
+### Teaching Through Gameplay
+
+Introduce complexity incrementally:
+
+1. **Movement first**: Let player master basic navigation
+2. **Then jumping/climbing**: Vertical gameplay after horizontal
+3. **Then simple combat**: Enemies that test basics
+4. **Then advanced mechanics**: Combinations, special moves
+
+Each layer builds on mastery of previous layer.
+
+### Safe Learning Environments
+
+**Prince of Persia approach**:
+- First breakaway floor: Non-lethal fall
+- First spikes: Easy to notice and avoid
+- Later encounters: Deadly, but player has learned
+
+**Half-Life approach**:
+- Opening sequence: Immersive but safe
+- Time to experiment with controls
+- Enemies introduced gradually
+
+### The Forgiveness Window
+
+Early mistakes should be forgiving:
+- Don't punish experimentation
+- Let players fail safely
+- Teach consequences without severe penalty
+
+Later, when players understand the rules, challenge them properly.
+
+### Tutorial Levels: Handle With Care
+
+**The problem**: Players skip tutorials to reach "real game."
+
+**The solution**: 
+- Make tutorials optional
+- Make early "real game" easy enough to learn in
+- Tutorial should supplement, not replace, good early design
+
+**Half-Life did both**: Optional training level + forgiving opening sequence.
+
+### Rewards During Learning
+
+Players need positive reinforcement early:
+- Celebrate small accomplishments
+- Draw them in with success
+- "This game is easy, I'm good at this!"
+- Then gradually increase challenge
+
+The goal: Player is invested before difficulty ramps up.
+
+### Common Mistake: Too Hard at Start
+
+Odyssey's opening was too punishing:
+- Player shipwrecked, weaponless
+- Monsters attack within seconds
+- Cave hidden in woods (later moved to open)
+
+**Lesson**: However obvious the solution seems to you, players are experiencing it fresh.
+
+---
+
+## Input: Controls
+
+> "Nothing is more frustrating than knowing exactly what you want your game-world character to do but being unable to actually get him to do that because the controls will not let you."
+
+### The Invisibility Goal
+
+Perfect controls disappear—player thinks "jump" and character jumps without conscious thought of which button.
+
+Every moment spent thinking about controls = moment pulled out of game experience.
+
+### Simplicity Over Complexity
+
+The keyboard has 100+ keys. Games have used nearly all of them.
+
+**The problem**: Complex controls favor expert players, alienate novices.
+
+**Console advantage**: Limited buttons force designers to refine, combine actions, focus on essentials.
+
+**Result**: Easier to learn, more players can enjoy.
+
+### Mouse-Only Success
+
+Games like Diablo, StarCraft, and The Sims use mouse as primary input.
+
+**Advantages**:
+- Non-gamers already know the mouse
+- Minimal learning curve
+- Intuitive point-and-click
+
+### Multiple Input Methods
+
+Provide multiple ways to do the same thing:
+- StarCraft: Right-click OR button bar OR hotkeys
+- Console games: D-pad OR analog stick
+
+Different players prefer different methods. Let them choose.
+
+### Standard Conventions
+
+Don't reinvent controls unnecessarily.
+
+**Gettysburg! example**: Used click-and-drag instead of click-and-click for ordering troops. Marginally better, but confusion from non-standard approach outweighed benefit.
+
+**Principle**: Use established conventions unless your innovation is significantly better—and playtested to prove it.
+
+### Configurable Controls
+
+**PC games**: Must allow key remapping. Many players will use defaults, so make defaults good, but power users need customization.
+
+**Console games**: Controller layouts often standardized by genre. Deviation is jarring.
+
+### The Complexity Creep of 3D
+
+3D games require: forward, backward, left, right, up, down, turn left, turn right, pitch up, pitch down...
+
+And that's before any gameplay actions.
+
+**Successful 3D games**: Often restrict to ground plane (Mario 64, Quake, Tomb Raider), reducing control complexity.
+
+### Controller Burnout
+
+Over development, team adapts to poor controls.
+
+**What seems natural to team**: May be impossible for newcomers.
+
+**Solution**: First-impression testing specifically for controls. Watch new players struggle. Fix what they can't figure out.
+
+---
+
+## Output: Communicating Game State
+
+Players need to understand what's happening in the game-world.
+
+### Game-World View as Primary Output
+
+Most information should come through the game itself:
+- Character animation shows health
+- Enemy behavior shows awareness state
+- Environment shows progress/danger
+
+The less that requires HUD, the more immersive the experience.
+
+### HUD Design
+
+When HUD is necessary:
+- **Visual over numerical**: Health bar > health percentage
+- **Minimal footprint**: Every pixel of HUD blocks game view
+- **Glanceable**: Player should understand at a glance
+- **Consistent location**: Don't move elements around
+
+**Trend**: HUDs getting smaller or disappearing. Oddworld: Abe's Oddysee has no HUD—health shown through animation.
+
+### Feedback Loops
+
+Player does action → Game responds → Player learns
+
+**Critical failures**:
+- Action with no visible feedback
+- Delayed feedback
+- Ambiguous feedback
+
+**Example**: If shooting enemy in weak spot, enemy should visibly react (recoil, scream) so player knows they're on the right track.
+
+### Information Players Must Have
+
+- Current health/resources
+- Objective/goal status
+- Threat awareness (enemies approaching)
+- Progress indicators
+
+If game tracks it and player needs it, player must be able to access it.
+
+### Hidden Information
+
+Some information intentionally hidden (enemy exact health, loot tables) for mystery/discovery.
+
+**Rule**: Hide for design reasons, not because you forgot to display it.
+
+---
+
+## The Input/Output Loop
+
+Controls (input) and feedback (output) form a loop:
+1. Player wants action
+2. Player performs input
+3. Game processes action
+4. Game provides output
+5. Player perceives result
+6. Player decides next action
+
+### Latency Kills
+
+Any delay in this loop breaks flow:
+- Input lag: Character responds slowly
+- Visual lag: Screen doesn't update
+- Audio lag: Sound mismatched with action
+
+Tight loop = immersive. Loose loop = frustrating.
+
+### Proprioception in Games
+
+In real life, you know where your body is without looking (proprioception).
+
+In games, players develop similar sense for their character—but only with consistent controls and feedback.
+
+> "When your controls are perfect, the wall separating the player from the game-world comes down."
+
+---
+
+## Design Principle Summary
+
+| Principle | Application |
+|-----------|-------------|
+| Maintain Focus | Filter all decisions through core experience |
+| Teach by Doing | Early game IS the tutorial |
+| Forgive Early | Severe punishment comes after mastery |
+| Reward Learning | Positive reinforcement builds engagement |
+| Simplify Input | Fewer controls = broader audience |
+| Use Conventions | Innovate mechanics, not controls |
+| Show, Don't Number | Visual feedback over data displays |
+| Complete the Loop | Tight input → output → input cycle |
+| Watch Newcomers | Fresh eyes reveal what you've normalized |

package/.claude/skills/game-design-theory/gameplay-elements.md

@@ -0,0 +1,213 @@
+# Gameplay Elements
+
+The core mechanics and systems that make games compelling.
+
+## Unique Solutions
+
+One of the most exciting moments as a designer is hearing players describe successful tactics you never anticipated. Games should create situations where player creativity can flourish.
+
+### Anticipatory vs. Complex Systems
+
+**Anticipatory Design** (Limited):
+- Designer predicts what players might try
+- Hardcodes specific solutions to work
+- Problem: Can't anticipate everything
+
+**Complex Systems Design** (Preferred):
+- Create consistent systems with properties
+- Let systems interact naturally
+- Solutions emerge from system rules, not case-by-case coding
+
+**Example - Pressure Plate Puzzle**:
+
+*Anticipatory approach*: "Puzzle solved if player uses rocks, weapons, or monsters"
+- Fails when player tries snow from a Blizzard spell
+
+*Systems approach*: "Every object has weight; puzzle solved when correct total weight placed"
+- Works for any weighted object automatically
+- Player discovers that their Blizzard spell creates enough snow to trigger the plate
+
+### Emergence
+
+When multiple consistent systems run in parallel, emergent strategies appear—solutions the designer never anticipated.
+
+**Centipede "Blob Strategy" Example**:
+Players discovered:
+1. Flea drops problematic mushrooms
+2. Flea doesn't appear on first wave
+3. Flea triggered by few mushrooms in bottom screen half
+
+**Emergent solution**: Clear all mushrooms on wave one, then only allow mushrooms in bottom-right quadrant. Flea never appears.
+
+Ed Logg (the designer) didn't anticipate this. That's good design—players feel clever for discovering it.
+
+**Design Principle**: The more complex systems working correctly in parallel, the more varied and interesting player solutions become. See Civilization as the gold standard.
+
+---
+
+## Non-Linearity
+
+Non-linearity gives interactivity meaning. Without it, games might as well be movies.
+
+### Types of Non-Linearity
+
+#### 1. Storytelling
+Story branches based on player choices. Most neglected form—many games have non-linear gameplay but completely linear stories.
+
+#### 2. Multiple Solutions
+Any challenge should have multiple ways to overcome it:
+- Not every player thinks the same way
+- Different solutions suit different playstyles
+- Enables player creativity and ownership
+
+#### 3. Order
+Let players choose which challenges to attempt first:
+- Put aside frustrating puzzles, work on others
+- Return refreshed to difficult challenges
+- Avoid "stuck on one thing, can't progress" syndrome
+
+#### 4. Selection
+Let players skip certain challenges entirely:
+- Complete 2 of 3 available quests
+- Choose challenges matching their strengths
+- Optional side-quests for additional depth
+
+### Implementation Example: Odyssey
+
+A highly non-linear RPG design:
+- Two quests available on first island (with multiple solutions each)
+- Clever players can skip both quests entirely
+- Next five islands freely navigable in any order
+- Quests optional but make the game easier
+- Multiple endings based on player goals
+
+**Result**: No two players experience the game the same way.
+
+### Why Non-Linearity Gets Cut
+
+**Producer argument**: "If players only need to do X, why spend money on Y and Z?"
+
+**Designer ego**: "I want players to experience everything I created."
+
+**Response**: Non-linearity isn't waste—it's player agency. Players who feel trapped become frustrated. Replayability is a bonus, not the primary goal.
+
+### The Purpose of Non-Linearity
+
+> The true point of non-linearity is to surrender some degree of authorship to the player.
+
+**Self-fulfilling prophecy**: "Players don't finish games anyway, so no need for non-linearity."
+
+Reality: Players fail to finish *because* they get stuck at linear bottlenecks. Non-linear games let players route around obstacles.
+
+### Balance: Not Too Much
+
+Too much non-linearity = aimless wandering.
+
+"In our game, players can do anything!" often ships as "solve puzzles on rails."
+
+**Ideal**: Freedom + Guidance. Players feel free while designer maintains coherent experience.
+
+---
+
+## Modeling Reality
+
+### The Reality Trap
+
+More realistic ≠ more fun.
+
+**What would more reality add to Tetris or Centipede?** Nothing.
+
+**What would more realistic economics add to Civilization?** Tedium.
+
+> "Films are life with the dull bits cut out." — Alfred Hitchcock
+
+Games should be life with even more dull bits cut out.
+
+**Example of too much reality**: Games requiring players to feed characters regularly. Eating scheduled meals isn't what people think of when imagining adventure.
+
+### Benefits of Reality Modeling
+
+Reality provides instant familiarity:
+- Players know what's reasonable
+- Implicit goals (SimCity: players know what a "good city" looks like)
+- Intuitive expectations
+
+### The Reality Expectations Problem
+
+Once you model reality, players expect more reality:
+- Early FPS games had no jumping → Players: "Why can't I jump over waist-high obstacles?"
+- Added jumping → "Why can't I crouch?"
+- Added crouching → "Why can't I lie flat on the ground?"
+
+**Contrast with abstract games**: In Tetris, players never question their capabilities because boundaries were arbitrary from the start.
+
+### Design Balance
+
+Strike a balance between reality and abstraction:
+- What does gameplay need?
+- What does story/setting require?
+- What can the engine handle?
+
+**Critical insight**: More reality is not always better. Simulate only what serves fun.
+
+---
+
+## Rewards
+
+Players need positive reinforcement, especially early on.
+
+### Early Rewards Strategy
+
+1. Start simple—basic actions only
+2. Reward small accomplishments
+3. Draw player in: "Ha ha, this game is easy!"
+4. Gradually increase challenge
+5. Player already invested, sees increased difficulty as surmountable
+
+### Learning Through Rewards
+
+**Prince of Persia approach**:
+- First breakaway floor is non-lethal
+- Spikes introduced in survivable situations
+- Later encounters less forgiving, but player has learned
+
+**Half-Life approach**:
+- Safe, interesting introduction
+- Time to learn controls without dying
+- Tutorial level exists but isn't required—main game also teaches
+
+### Tutorial Levels
+
+Problems:
+- Often not fun to play
+- Players skip them to reach "real game"
+- Can't replace making early game itself easy
+
+**Solution**: Tutorial for players who want it, but design early game to be forgiving regardless.
+
+---
+
+## The Role of AI
+
+Good AI serves gameplay, not realism.
+
+### Goals of Game AI
+
+1. **Challenge the player** - Appropriate difficulty
+2. **Not do dumb things** - Avoid immersion-breaking stupidity
+3. **Be unpredictable** - Fresh experience on replay
+4. **Assist storytelling** - Behaviors that fit narrative
+5. **Create a living world** - Ambient behaviors
+
+### The Sloped Playing Field
+
+AI doesn't need to play by the same rules as players:
+- Rubber-banding in racing games
+- AI with different (often worse) information than players
+- Difficulty adjustment behind the scenes
+
+**Key**: AI should *feel* fair even if it isn't technically equivalent.
+
+### How Real is Too Real?
+
+Sometimes realism improves AI (enemies can't see through walls), sometimes it hurts fun. Design for player experience, not simulation accuracy.