YeetGeese/AI Docs/05-SKILLS-REFERENCE.md

# Skills, Agents, and Commands Reference

This document provides a reference for AI assistants working with YeetGeese. It describes available capabilities, when to use them, and best practices for interaction.

---

## Table of Contents

1. [Available Skills](#available-skills)
2. [Agent Types & Use Cases](#agent-types--use-cases)
3. [Command Reference](#command-reference)
4. [Prompt Templates](#prompt-templates)
5. [Best Practices](#best-practices)

---

## Available Skills

### `customize-opencode`

**Purpose:** Configure and modify the AI assistant's own settings, including:
- `opencode.json`, `opencode.jsonc` files
- `.opencode/` configuration directory
- `~/.config/opencode/` user settings
- Agent definitions (subagents, skills, plugins, MCP servers)
- Permission rules

**When to use:** When configuring the AI assistant itself, not for project code.

**Example:**
```
"Adjust the maximum context window size for this session."
```

---

### `make-pr` — Pull Request Creation

**Purpose:** Create comprehensive pull requests from the current branch to a target branch (default: `develop`) with human-readable change overviews and testing strategies.

**Capabilities:**
- Generating human-readable PR descriptions summarizing all changes
- Listing testing strategies for each major change area
- Validating changes before PR submission
- Formatting PR descriptions with clear, organized sections
- Identifying breaking changes and migration notes

**When to use:**
- When ready to submit a pull request from your current branch
- Before pushing code that requires peer review
- To ensure all changes are properly documented and validated
- When creating PRs for features, fixes, or refactoring

**Input required:**
- Target branch (default: `develop`)
- Optional custom PR title override
- Optional specific testing requirements

**Example prompt:**
```
"Create a pull request from move_docs to develop. The changes include moving 
all AI documentation files into an 'AI Docs' folder with organized structure."
```

---

## Agent Types & Use Cases

### `code-gen` — Code Generation

**Purpose:** Write new code, implement features, create boilerplate.

**Capabilities:**
- GDScript 4 implementation
- Scene graph construction descriptions
- Resource file (`.tres`) schema design
- Signal declarations and connections
- Method implementations matching project conventions

**When to use:**
- Implementing a new tower or projectile type
- Adding a feature to existing systems
- Creating boilerplate for common patterns
- Writing unit tests

**Input required:**
- Target file path or node description
- Desired behavior/goal
- Any constraints (e.g., "must use Resource for stats")

**Example prompt:**
```
"Create a GDScript 4 class `ImpactEffect.gd` that extends Area2D. It should:
1. Detect collision with enemies in _body_entered
2. Emit signal 'effect_triggered' with damage and target Node2D
3. Apply random color variation to its texture
4. Set lifespan to 0.8 seconds
5. Include comments explaining each step"
```

---

### `debug-helper` — Debugging Assistance

**Purpose:** Analyze errors, suggest debugging strategies, interpret profiler output.

**Capabilities:**
- Error message interpretation (Godot/IDE/compiler)
- Suggesting debugging tool usage (Scene Debugger, Physics Monitor)
- Profiling tips and bottleneck identification
- Common pitfall recognition (e.g., physics tunneling, navmesh gaps)

**When to use:**
- When an error occurs during implementation
- When code behaves unexpectedly
- When performance issues appear in profiler

**Input required:**
- Error message or log output
- Relevant file paths and line numbers if available
- Brief description of expected vs. actual behavior

**Example prompt:**
```
"This tower stops firing after 30 seconds even though fire_rate is set to 1.0. 
Error: 'get_tree()' returned null at runtime. Debug it."
```

---

### `refactor-assistant` — Refactoring Support

**Purpose:** Break up large scripts, improve code organization, add documentation.

**Capabilities:**
- Splitting monolithic scripts into smaller nodes
- Extracting methods into separate components
- Adding documentation and type hints
- Applying project conventions consistently

**When to use:**
- Scripts are growing beyond 150 lines
- Multiple unrelated behaviors in one node
- Need to improve readability before review

**Input required:**
- File path or code snippet
- Refactoring goal (e.g., "split into state machines")
- Target organization style

**Example prompt:**
```
"Refactor this 400-line EnemyMob.gd into smaller components:
1. Extract navigation logic to NavigationComponent
2. Extract attack behavior to AttackState
3. Keep health/currency handling in base class
4. Add documentation comments for each section"
```

---

### `test-generator` — Test Generation

**Purpose:** Create unit tests for game logic systems.

**Capabilities:**
- Writing Godot test cases using `@tool` functions
- Setting up mock scenes and signals
- Testing Resource-based stat changes
- Validating collision detection and hit calculations

**When to use:**
- After implementing core logic that should be validated
- Before refactoring (to preserve behavior)
- When adding critical game mechanics

**Input required:**
- System or function being tested
- Expected inputs and outputs
- Edge cases to cover

**Example prompt:**
```
"Create tests for TowerBase._can_build_at(). Test:
1. Returns true in valid tower placement zones
2. Returns false inside enemy navmesh
3. Returns false when grid coordinate exceeds bounds
4. Returns false if parent node is null"
```

---

### `design-patterns` — Design Pattern Suggestions

**Purpose:** Recommend architecture patterns suited to specific problems.

**Capabilities:**
- Suggesting ECS for complex entity management
- Recommending FSM for enemy AI states
- Proposing event-driven systems for decoupled components
- Advising on data-oriented vs. object-oriented design

**When to use:**
- Before implementing a new system
- When performance becomes an issue
- When refactoring existing code

**Input required:**
- Problem description (e.g., "I need many entities with simple movement")
- Performance constraints if any
- Preferred Godot nodes or patterns already in use

**Example prompt:**
```
"I'm building a system for 50+ projectiles that need to track targets, apply damage, and handle collision. 
Current approach: individual RigidBody2D for each projectile. 
What pattern would scale better?"
```

---

### `balance-helper` — Balance Analysis

**Purpose:** Analyze math relationships and suggest tuning adjustments.

**Capabilities:**
- Calculating damage per second (DPS) from fire rate and projectile stats
- Estimating kill time based on enemy HP and total damage sources
- Suggesting resource stat ranges that preserve balance space
- Identifying scaling relationships between tower levels

**When to use:**
- Before adding new towers/enemies with different power levels
- When gameplay feels too easy or difficult
- During tuning phase of wave progression

**Input required:**
- Current stats (damage, fire rate, enemy HP)
- Desired behavior description (e.g., "kill time should scale with tier")
- Resource file structure if applicable

**Example prompt:**
```
"Current: goose damage=15, fire_rate=1.0/s, chicken HP=80. 
Tower Level 2 has 4 geese. Calculate total DPS and suggest enemy HP range 
for level-appropriate difficulty (aim for ~30s wave duration)."
```

---

### `level-design-helper` — Level Design Assistance

**Purpose:** Plan layout, progression, and pacing for levels or zones.

**Capabilities:**
- Wave progression suggestions (spawn rates, path complexity)
- Tower placement zone recommendations
- Pacing analysis for difficulty curves
- Zone-based checkpoint design

**When to use:**
- Before creating a new level or wave sequence
- When gameplay feels too repetitive or frustrating
- During playtesting feedback analysis

**Input required:**
- Level description (size, available zones)
- Current wave structure if any
- Difficulty curve goals

**Example prompt:**
```
"I have 4 tower placement zones along a path with 3 turns. 
Current waves: linear difficulty increase. 
Suggest a progression that introduces new mechanics at zone boundaries."
```

---

### `doc-generator` — Documentation Generation

**Purpose:** Create documentation from existing code or planning data.

**Capabilities:**
- Generating API docs from GDScript class structures
- Writing changelogs from commit history
- Creating release notes with feature summaries
- Producing onboarding guides from project structure

**When to use:**
- Before releasing a version
- After implementing a major feature set
- When new team members join the project

**Input required:**
- Source code or commit messages
- Feature list for changelog entries
- Target audience (developers, players)

**Example prompt:**
```
"Generate API documentation for the WaveRunner system:
1. Describe each public method and its parameters
2. List signals emitted with their payloads
3. Document the Resource dependencies
4. Include usage examples"
```

---

### `onboarding-guide` — Onboarding Documentation

**Purpose:** Create setup tutorials and getting-started guides for new developers.

**Capabilities:**
- Environment setup instructions (OS-specific)
- Project structure explanation
- Editor scene loading order
- Common first tasks with examples

**When to use:**
- Before bringing on new team members
- When updating project structure significantly
- For release candidate documentation

**Input required:**
- Target OS versions supported
- Required Godot version and plugins
- Team conventions to teach

**Example prompt:**
```
"Write an onboarding guide for a new developer joining YeetGeese:
1. Explain folder structure (src/core, src/towers, etc.)
2. Show how to run the game from main.tscn
3. Describe the tower placement workflow
4. List common commands for debugging"
```

---

### `api-specs` — API Specification

**Purpose:** Define external interfaces and save/load contracts.

**Capabilities:**
- Defining save file format schemas
- Documenting modding API endpoints
- Specifying network message protocols
- Creating serialization guides

**When to use:**
- Before implementing persistent storage
- When enabling mod support
- For multiplayer networking design

**Input required:**
- Interface type (save format, mod API, network protocol)
- Required functionality list
- Platform constraints

**Example prompt:**
```
"Define a save file format for YeetGeese:
1. Must store unlocked towers and their levels
2. Must include currency progress and wave number
3. Use Godot Resource serialization (.tres files)
4. Include version field for backward compatibility"
```

---

## Command Reference

### Code Writing Commands

| Command | When to use |
|---------|-------------|
| `create file <path>` | For new classes, scenes, or resource files |
| `modify file <path>` | For adding methods or changing existing code |
| `describe scene <path>` | To generate scene tree descriptions for AI understanding |

### Review Commands

| Command | When to use |
|---------|-------------|
| `review code <path>` | For checking convention compliance |
| `optimize performance <scope>` | For profiling suggestions in specific areas |
| `debug error <message>` | For interpreting errors and suggesting fixes |

### Documentation Commands

| Command | When to use |
|---------|-------------|
| `generate docs` | For API documentation from code |
| `write changelog` | After implementing features or fixing bugs |
| `create onboarding guide` | For new developer setup instructions |

---

## Prompt Templates

### Feature Implementation Template

```
Context: I'm implementing [feature name] in [system/file].
Current state: [brief description of existing code/structure]
Goal: [what this feature should do]
Constraints: [any restrictions like "must use Resource" or "no UI changes"]

Please provide:
1. Complete, runnable GDScript 4 code with comments
2. Scene hierarchy description if new scenes are needed
3. Any new Resources (.tres) and their structure
4. Signal declarations and connection points
```

### Debugging Template

```
Error context: [where the error occurred]
Error message: [full error output]
Expected behavior: [what should have happened]
Actual behavior: [what actually happened]
Debug steps tried: [what you've already attempted]

Please provide:
1. Root cause analysis
2. Minimal fix with explanation
3. Prevention strategy for future occurrences
```

### Refactoring Template

```
Current code: [file path or snippet]
Issues to address: [e.g., "too monolithic", "missing docs"]
Refactoring goals: [what you want to achieve]
Target patterns: [any existing patterns to match]

Please provide:
1. Proposed refactored structure
2. New files and their responsibilities
3. Migration steps for existing code
```

---

## Best Practices

### 1. Always Provide Context First

Before asking for code, share:
- The relevant file path or node description
- The GDScript version being used (Godot 4.x)
- Key related signals and methods already in place

**Good:**
```
"Create an ImpactEffect.gd extending Area2D with these existing methods:
- _body_entered(var area): called on collision
- emit_signal('effect_triggered', damage, target)"
```

**Bad:**
```
"I need a collision effect for projectiles."
```

### 2. Specify Godot 4 Conventions

When requesting code, remind AI of conventions:
- Use typed signals: `signal health_changed(new_health: float)`
- Prefer `@onready` over `$` in scripts
- Type variables and return values consistently
- Keep scenes modular (compose behavior across nodes)

### 3. Reference Existing Architecture

When implementing features, reference existing patterns:
```
"Implement this using the same pattern as TowerBase.fire_at():
- Use projectile_res.instantiate() for new goose projectiles
- Spawn from $ProjectileSpawner.global_position
- Add to parent tree immediately after instantiation"
```

### 4. Specify Resource Dependencies Early

If your project uses Resources for balance:
```
"Create a Resource-based stats file for this tower:
- Fields: damage (float), fire_rate (float), cooldown_reduction (float)
- Make it loadable as a Godot Resource (.tres)
- Show how the tower reads its stats on _ready()"
```

### 5. Ask for Complete, Runnable Code

When requesting implementations:
```
"Return complete, runnable GDScript 4 code with:"
"- Comments explaining each major section"
"- Type annotations for all variables and methods"
"- Signal declarations at top of class"
```

---

## Summary

**Use these skills strategically:**
- `code-gen`: For new features and boilerplate
- `debug-helper`: When errors occur or behavior is wrong
- `refactor-assistant`: Before code grows unmanageable
- `test-generator`: After implementing critical logic
- `design-patterns`: When architecture becomes unclear
- `make-pr`: When ready to submit a pull request from current branch

**Always provide:**
- File paths, node names, and Godot version context
- Desired behavior in terms of existing patterns
- Constraints (Resource usage, signal conventions)

**When in doubt:** Reference `AI_HELP.md` for project-specific conventions before asking questions.