File Organizer Studio

A practical skill for organizing messy file systems — covering directory structure planning, automated file sorting, duplicate detection, naming conventions, and maintenance workflows for Downloads folders, project directories, and document archives.

When to Use This Skill

Choose File Organizer Studio when you need to:

• Clean up a chaotic Downloads or Documents folder
• Establish a consistent file organization system
• Detect and remove duplicate files
• Sort files automatically by type, date, or project
• Create naming conventions for team file sharing

Consider alternatives when:

• You need cloud storage management (use a cloud storage skill)
• You need code repository organization (use a project structure skill)
• You need database file management (use a data management skill)

Quick Start

Copy
# Scan a directory and propose an organization plan
claude "Analyze my ~/Downloads folder and suggest an organization structure. Sort files by type and move them to appropriate directories."

Copy
import os
import shutil
from pathlib import Path
from collections import defaultdict

def organize_downloads(source_dir="~/Downloads"):
    source = Path(source_dir).expanduser()

    # File type categories
    categories = {
        "Documents": {".pdf", ".doc", ".docx", ".txt", ".xlsx", ".csv", ".pptx", ".md"},
        "Images": {".jpg", ".jpeg", ".png", ".gif", ".svg", ".webp", ".ico"},
        "Videos": {".mp4", ".mov", ".avi", ".mkv", ".webm"},
        "Audio": {".mp3", ".wav", ".flac", ".aac", ".ogg"},
        "Archives": {".zip", ".tar", ".gz", ".rar", ".7z"},
        "Code": {".py", ".js", ".ts", ".html", ".css", ".json", ".yaml"},
        "Installers": {".dmg", ".pkg", ".exe", ".msi", ".deb", ".rpm"},
    }

    # Build reverse lookup
    ext_to_category = {}
    for category, exts in categories.items():
        for ext in exts:
            ext_to_category[ext] = category

    # Scan and sort
    moved = defaultdict(int)
    for item in source.iterdir():
        if item.is_file() and not item.name.startswith("."):
            ext = item.suffix.lower()
            category = ext_to_category.get(ext, "Other")
            dest_dir = source / category
            dest_dir.mkdir(exist_ok=True)
            shutil.move(str(item), str(dest_dir / item.name))
            moved[category] += 1

    print("Files organized:")
    for cat, count in sorted(moved.items()):
        print(f"  {cat}: {count} files")

organize_downloads()

Core Concepts

Directory Structure Templates

Use Case	Structure	Key Principle
Personal files	By category (Documents, Photos, etc.)	Easy to browse
Project work	By project, then by type	Context together
Date-based	YYYY/MM/ subdirectories	Chronological retrieval
Client work	By client, then by project	Client isolation

Duplicate Detection

Copy
import hashlib
from pathlib import Path
from collections import defaultdict

def find_duplicates(directory):
    """Find duplicate files by content hash."""
    hash_map = defaultdict(list)

    for file_path in Path(directory).rglob("*"):
        if file_path.is_file():
            file_hash = hashlib.md5(file_path.read_bytes()).hexdigest()
            hash_map[file_hash].append(file_path)

    duplicates = {h: paths for h, paths in hash_map.items() if len(paths) > 1}

    total_wasted = 0
    for file_hash, paths in duplicates.items():
        size = paths[0].stat().st_size
        wasted = size * (len(paths) - 1)
        total_wasted += wasted
        print(f"\nDuplicates ({len(paths)} copies, {size/1024:.1f}KB each):")
        for p in paths:
            print(f"  {p}")

    print(f"\nTotal wasted space: {total_wasted/1024/1024:.1f}MB")
    return duplicates

Naming Conventions

Copy
## File Naming Rules

### General Pattern
{date}_{project}_{description}.{ext}
Example: 2024-12-15_clientx_proposal-v2.pdf

### Rules
1. Use lowercase with hyphens (no spaces, no CamelCase)
2. Date prefix for chronological sorting (YYYY-MM-DD)
3. Version suffix when applicable (-v2, -v3)
4. No special characters except hyphens and underscores

### Bad Names → Good Names
- "Final FINAL (2).docx" → "2024-12-15_report-final.docx"
- "Screenshot 2024-12-15 at 3.45.23 PM.png" → "2024-12-15_dashboard-bug.png"
- "Copy of budget.xlsx" → "2024-12-15_budget-draft.xlsx"

Configuration

Parameter	Description	Example
source_dir	Directory to organize	"~/Downloads"
strategy	Organization strategy	"by_type" / "by_date"
dry_run	Preview changes without moving files	true
detect_duplicates	Find and report duplicate files	true
naming_convention	File naming pattern	"{date}_{description}"
exclude_patterns	Files/dirs to skip	[".*", "node_modules"]

Best Practices

1. Always do a dry run first — Before moving thousands of files, preview what will happen. Print the source and destination for each file and review the plan. One wrong category mapping can scatter files into the wrong directories.

2. Organize by project for active work, by type for archives — Files you're actively working on benefit from being grouped by project (all assets together). Files you're archiving benefit from type-based organization (all PDFs together) because you search by format when retrieving old files.

3. Use consistent date formats: YYYY-MM-DD — This format sorts correctly alphabetically, is unambiguous (unlike MM/DD vs DD/MM), and works across all operating systems. Use it for file names, folder names, and any date-based organization.

4. Set up automated organization rules — Manual cleanup works once but doesn't last. Use tools like Hazel (macOS), organize-cli (cross-platform), or a cron job with your own script to automatically sort new files as they arrive.

5. Review and purge quarterly — Organization without purging leads to organized clutter. Every quarter, review old files: delete what's no longer needed, archive what might be needed someday, and keep active files in your working directories.

Common Issues

Files with the same name collide during organization — Multiple "report.pdf" files from different sources overwrite each other. Add timestamps or source identifiers to filenames before moving, or use a collision-handling strategy (append -1, -2 suffix).

Organization system is too complex to maintain — A system with 15 nested folder levels and a 50-page naming guide won't be followed. Keep it to 2-3 levels of hierarchy and 3-5 simple naming rules. Complexity is the enemy of consistency.

Important files get buried in the wrong category — A PDF that's both a "document" and a "project deliverable" doesn't fit neatly into either category. Use a "working" or "active" folder for current projects that bypasses the type-based system, and only categorize files when they move to archive status.