This commit is contained in:
@@ -0,0 +1,494 @@
|
||||
# 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."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user