---
name: file-organizer
description: Intelligently organizes files and folders by understanding context, finding duplicates, suggesting better structures, and automating cleanup tasks.
license: Apache-2.0
metadata:
  version: "1.0"
  category: devtools
---

# File Organizer

Personal organization assistant that helps maintain a clean, logical file structure without the mental overhead of constant manual organization.

## When to Use This Skill

- Your repo has notes, drafts, and files scattered everywhere
- You can't find files because they're in the wrong directories
- You have duplicate files taking up space
- Your folder structure doesn't make sense anymore
- You're starting a new project and need a good structure
- You're cleaning up before archiving old projects
- A repository has grown organically and needs restructuring

## What This Skill Does

1. **Analyzes Current Structure**: Reviews your folders and files to understand what you have
2. **Finds Duplicates**: Identifies duplicate files across your system
3. **Suggests Organization**: Proposes logical folder structures based on your content
4. **Automates Cleanup**: Moves, renames, and organizes files with your approval
5. **Maintains Context**: Makes smart decisions based on file types, dates, and content
6. **Reduces Clutter**: Identifies old files you probably don't need anymore

## How to Use

### Example Requests

```
Help me organize this repo — notes and drafts are everywhere
```

```
Find duplicate files in this project
```

```
Review the folder structure and suggest improvements
```

```
Clean up old files I haven't touched in 6+ months
```

## Instructions

When a user requests file organization help:

1. **Understand the Scope**

   Ask clarifying questions:
   - Which directory needs organization?
   - What's the main problem? (Can't find things, duplicates, too messy, no structure?)
   - Any files or folders to avoid? (Current projects, sensitive data?)
   - How aggressively to organize? (Conservative vs. comprehensive cleanup)

2. **Analyze Current State**

   Review the target directory. Example commands (adjust for your OS):
   ```bash
   # Get overview of current structure
   ls -la [target_directory]

   # Check file types and sizes
   find [target_directory] -type f -exec file {} \; | head -20

   # Identify largest files
   du -sh [target_directory]/* | sort -rh | head -20

   # Count file types
   find [target_directory] -type f | sed 's/.*\.//' | sort | uniq -c | sort -rn
   ```

   Summarize findings:
   - Total files and folders
   - File type breakdown
   - Size distribution
   - Date ranges
   - Obvious organization issues

3. **Identify Organization Patterns**

   Based on the files, determine logical groupings:

   **By Type**: Documents, Images, Videos, Archives, Code/Projects, Spreadsheets, Presentations

   **By Purpose**: Work vs. Personal, Active vs. Archive, Project-specific, Reference materials, Temporary/scratch files

   **By Date**: Current year/month, Previous years, Very old (archive candidates)

4. **Find Duplicates**

   When requested, search for duplicates. Example commands (adjust for your OS):
   ```bash
   # Find exact duplicates by hash
   find [directory] -type f -exec md5sum {} \; | sort | uniq -d -w32

   # Find files with same name
   find [directory] -type f -printf '%f\n' | sort | uniq -d
   ```

   For each set of duplicates:
   - Show all file paths
   - Display sizes and modification dates
   - Recommend which to keep (usually newest or best-named)
   - **Always ask for confirmation before deleting**

5. **Propose Organization Plan**

   Present a clear plan before making changes:

   ```markdown
   # Organization Plan for [Directory]

   ## Current State
   - X files across Y folders
   - [Size] total
   - Issues: [list problems]

   ## Proposed Structure
   [Show the new folder tree]

   ## Changes
   1. Create new folders: [list]
   2. Move files: [summary]
   3. Rename files: [any renaming patterns]
   4. Delete: [duplicates or trash files]

   ## Files Needing Your Decision
   - [List any ambiguous files]

   Ready to proceed? (yes/no/modify)
   ```

6. **Execute Organization**

   After approval, organize systematically:
   - Always confirm before deleting anything
   - Log all moves for potential undo
   - Preserve original modification dates
   - Handle filename conflicts gracefully
   - Stop and ask if you encounter unexpected situations

7. **Provide Summary and Maintenance Tips**

   After organizing, provide:
   - What changed (files moved, duplicates removed, space freed)
   - The new folder structure
   - Maintenance schedule (weekly/monthly/quarterly tips)
   - Quick commands for future cleanup

## Best Practices

### Folder Naming
- Use clear, descriptive names
- Avoid spaces (use hyphens or underscores)
- Be specific: "client-proposals" not "docs"

### File Naming
- Include dates: "2024-10-17-meeting-notes.md"
- Be descriptive: "q3-financial-report.xlsx"
- Avoid version numbers in names (use version control instead)

### When to Archive
- Projects not touched in 6+ months
- Completed work that might be referenced later
- Old versions after migration to new systems
- Files you're hesitant to delete (archive first)