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
2. Agent Types & Use Cases
3. Command Reference
4. Prompt Templates
5. 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 (Gitea Web UI)

Purpose: On Gitea, pull requests are created directly via the web interface at:
https://gitea.letteka.com/letteka/YeetGeese/pulls/new/move_docs

How to use on Gitea:

1. Push changes to a branch (e.g., move_docs)
2. Visit the URL above or navigate via Gitea web UI
3. Create PR with descriptive title and body
4. Include testing strategies and validation status in description

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

Best practices for Gitea PRs:

• Use descriptive titles following conventional commits format
• Include file-by-file change summary in PR body
• List testing strategies: unit tests, integration tests, manual QA
• Mention any validation already performed locally
• Flag known issues or limitations clearly

---

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

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.