---
name: godot-organize-files-2ce749b524f8
version: 3.0.0
displayName: Organize Project File Structure
description: >
  Use when Godot project has scattered files with no clear organization. Detects
  assets, scripts, scenes, and resources in root or inconsistent locations.
  Automatically creates organized directory structure following Godot best practices,
  moves files preserving references, and updates all dependencies.
author: Asreonn
license: MIT
category: game-development
type: tool
difficulty: beginner
audience: [developers]
keywords:
  - godot
  - file-organization
  - directory-structure
  - project-cleanup
  - best-practices
  - asset-management
  - gdscript
  - godot-project
platforms: [macos, linux, windows]
repository: https://github.com/asreonn/godot-superpowers
homepage: https://github.com/asreonn/godot-superpowers#readme

permissions:
  filesystem:
    read: ["*"]
    write: ["*"]
    move: true
    delete: false
  git: true

behavior:
  auto_rollback: true
  validation: true
  git_commits: true

outputs: "Organized directory structure, moved files with preserved references, git commits"
requirements: "Git repository, Godot 4.x"
execution: "Fully automatic with reference preservation"
integration: "Part of godot-organize-project orchestrator, works with organize-assets and organize-scripts"
---

# Organize Project File Structure

## Core Principle

**Clear structure = easy navigation.** Files should be where you expect them.

## What This Skill Does

Finds projects like:
```
my_game/
├── project.godot
├── player.gd
├── enemy.gd
├── sprite1.png
├── sound.wav
├── level1.tscn
├── main_menu.tscn
├── utility.gd
└── ... (50 more files in root)
```

Transforms to:
```
my_game/
├── project.godot
├── assets/
│   ├── sprites/
│   │   └── sprite1.png
│   └── audio/
│       └── sound.wav
├── scenes/
│   ├── levels/
│   │   └── level1.tscn
│   └── ui/
│       └── main_menu.tscn
└── scripts/
    ├── player.gd
    ├── enemy.gd
    └── utility.gd
```

## Detection Patterns

Identifies:
- Files in root directory that should be organized
- Inconsistent naming (CamelCase, snake_case mixed)
- Assets mixed with code
- No logical grouping by type or domain

## When to Use

### Starting New Project
Establish structure from the beginning.

### Inheriting Legacy Project
Project has grown organically without structure.

### Preparing for Collaboration
Team needs consistent file locations.

### Before Major Refactoring
Clean structure makes refactoring easier.

## Process

1. **Scan** - Inventory all project files and current structure
2. **Analyze** - Determine file types and relationships
3. **Plan** - Create target directory structure
4. **Move** - Relocate files preserving all references
5. **Update** - Fix paths in .tscn, .gd, project.godot
6. **Validate** - Ensure all references still work
7. **Commit** - Git commit per logical grouping moved

## Standard Structure

### Recommended Organization

```
project_root/
├── project.godot
├── assets/
│   ├── sprites/
│   │   ├── characters/
│   │   ├── enemies/
│   │   ├── items/
│   │   └── environment/
│   ├── audio/
│   │   ├── music/
│   │   ├── sfx/
│   │   └── voice/
│   ├── fonts/
│   ├── materials/
│   ├── shaders/
│   └── models/       # For 3D projects
├── scenes/
│   ├── characters/
│   ├── enemies/
│   ├── levels/
│   ├── ui/
│   └── components/
├── scripts/
│   ├── characters/
│   ├── enemies/
│   ├── components/
│   ├── managers/
│   └── utility/
├── resources/
│   ├── items/
│   ├── enemies/
│   └── abilities/
├── addons/           # Third-party plugins
└── docs/             # Documentation (optional)
```

## What Gets Created

- Organized directory structure
- Moved files with preserved references
- Updated .tscn files with new paths
- Updated script preload() paths
- Updated project.godot autoloads
- Git commits documenting organization

## Smart Analysis

**Detects file types:**
- **Assets** - .png, .jpg, .wav, .ogg, .ttf, .glb
- **Scenes** - .tscn, .scn
- **Scripts** - .gd, .cs
- **Resources** - .tres, .res
- **Config** - .cfg, .json, project.godot

**Determines grouping:**
- By type (sprites, scripts, scenes)
- By domain (characters, enemies, ui)
- By function (components, managers, utilities)

## Integration

Works with:
- **godot-organize-assets** - Further organizes asset files
- **godot-organize-scripts** - Further organizes script files
- **godot-organize-project** (orchestrator) - Runs as part of full organization

## Safety

- All file references preserved during moves
- Godot's .import files updated automatically
- Rollback on validation failure
- Original structure preserved in git history

## When NOT to Use

Don't reorganize if:
- Project already has clear structure
- Mid-development sprint (bad timing)
- Custom structure intentionally different
- External tools rely on current paths

## Path Updates

### Script Updates
```gdscript
# Before
var scene = preload("res://player.tscn")

# After
var scene = preload("res://scenes/characters/player.tscn")
```

### Scene Updates
```ini
# Before
[ext_resource path="res://player.gd" type="Script"]

# After
[ext_resource path="res://scripts/characters/player.gd" type="Script"]
```

### Autoload Updates
```ini
# Before
[autoload]
GameManager="*res://game_manager.gd"

# After
[autoload]
GameManager="*res://scripts/managers/game_manager.gd"
```

## Organization Strategies

### By Type (Simple Projects)
Group all sprites together, all scripts together.

### By Domain (Medium Projects)
Group by game concept (characters, enemies, levels).

### By Feature (Large Projects)
Group by feature (combat system, inventory system).

### Hybrid
Combine strategies (assets by type, scripts by domain).

## Benefits

- **Discoverability** - Find files where you expect them
- **Scalability** - Structure supports growth
- **Onboarding** - New team members navigate easily
- **Consistency** - Same structure across projects
- **Tooling** - Tools work better with organized projects

## Common Patterns

| Before | After |
|--------|-------|
| `player.gd` in root | `scripts/characters/player.gd` |
| `sprite.png` in root | `assets/sprites/characters/sprite.png` |
| `level.tscn` in root | `scenes/levels/level.tscn` |
| `item_data.tres` in root | `resources/items/item_data.tres` |

## Configuration

Can be customized for:
- Different naming conventions
- Alternative structures (src/ instead of scripts/)
- Project-specific requirements
- Team preferences

Default follows Godot best practices and community standards.


---
Source attribution: Asreonn
Original project: https://github.com/Asreonn/godot-superpowers/blob/8f8a561b7766e6f56939124e0203a00b41f64fb8/mini-skills/godot-organize-files/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2026 Godot Superpowers Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: Asreonn
Original project: https://github.com/Asreonn/godot-superpowers/blob/8f8a561b7766e6f56939124e0203a00b41f64fb8/mini-skills/godot-organize-files/SKILL.md
Attribution basis: Source repository record

Fields of work: Development & Engineering
Roles: Frontend Developer, Game Developer
Specialties: Backend
Tools: Godot
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: ab8d5b313f4ef23f70071b11a34c3e31fdb60e90ab19ebe9313c37a91d5a3e7c