SKILL.md

File Organizer

When to Use This Skill

Your Downloads folder is a chaotic mess
You can't find files because they're scattered everywhere
You have duplicate files taking up space
Your folder structure doesn't make sense anymore
You want to establish better organization habits
You're starting a new project and need a good structure
You're cleaning up before archiving old projects

What This Skill Does

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

Instructions

When a user requests file organization help:

Understand the Scope

Ask clarifying questions:
- Which directory needs organization? (Downloads, Documents, entire home folder?)
- 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)

Analyze Current State

Review the target directory:

# 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

Identify Organization Patterns

Based on the files, determine logical groupings:

By Type:
- Documents (PDFs, DOCX, TXT)
- Images (JPG, PNG, SVG)
- Videos (MP4, MOV)
- Archives (ZIP, TAR, DMG)
- Code/Projects (directories with code)
- Spreadsheets (XLSX, CSV)
- Presentations (PPTX, KEY)
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)

Find Duplicates

When requested, search for duplicates:

# Find exact duplicates by hash
find [directory] -type f -exec shasum -a 256 {} \;

Group by the digest field using a filename-safe script; the full output line includes paths.

Identical hashes are candidates: compare bytes and metadata before any removal.

Find files with similar names

find [directory] -type f -printf '%f\n' | sort | uniq -d

Find similar-sized files

find [directory] -type f -printf '%s %p\n' | sort -n


For each set of duplicates:

- Show all file paths
- Display sizes and modification dates
- Recommend which to keep (usually newest or best-named)
- **Important**: 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
- File types: [breakdown]
- Issues: [list problems]

## Proposed Structure

[Directory]/
├── Work/
│ ├── Projects/
│ ├── Documents/
│ └── Archive/
├── Personal/
│ ├── Photos/
│ ├── Documents/
│ └── Media/
└── Downloads/
├── To-Sort/
└── Archive/

## Changes I'll Make

1. **Create new folders**: [list]
2. **Move files**:
   - X PDFs → Work/Documents/
   - Y images → Personal/Photos/
   - Z old files → Archive/
3. **Rename files**: [any renaming patterns]
4. **Delete**: [duplicates or trash files]

## Files Needing Your Decision

- [List any files you're unsure about]

Ready to proceed? (yes/no/modify)

Execute Organization

After approval, organize systematically:
```
# Create folder structure
mkdir -p "path/to/new/folders"

# Move files with clear logging
mv "old/path/file.pdf" "new/path/file.pdf"

# Rename files with consistent patterns
# Example: "YYYY-MM-DD - Description.ext"
```
Important Rules:
- Always confirm before deleting anything
- Log all moves for potential undo
- Preserve original modification dates
- Refuse overwrite by default; show exact source/destination and preserve a reversible move manifest. Do not follow symlinks outside the authorized tree.
- Handle filename conflicts gracefully
- Stop and ask if you encounter unexpected situations

Provide Summary and Maintenance Tips

After organizing:

# Organization Complete! ✨

## What Changed

- Created [X] new folders
- Organized [Y] files
- Freed [Z] GB by removing duplicates
- Archived [W] old files

## New Structure

[Show the new folder tree]

## Maintenance Tips

To keep this organized:

1. **Weekly**: Sort new downloads
2. **Monthly**: Review and archive completed projects
3. **Quarterly**: Check for new duplicates
4. **Yearly**: Archive old files

## Quick Commands for You

# Find files modified this week

find . -type f -mtime -7

# Sort downloads by type

[custom command for their setup]

# Find duplicates

[custom command]

Want to organize another folder?

Best Practices

Folder Naming

Use clear, descriptive names
Avoid spaces (use hyphens or underscores)
Be specific: "client-proposals" not "docs"
Use prefixes for ordering: "01-current", "02-archive"

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)
Remove download artifacts: "document-final-v2 (1).pdf" → "document.pdf"

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)

Example

User request:

Organize my Downloads folder into a predictable structure, show the proposed moves first, and avoid deleting files.

Limitations

Use this skill only when the task clearly matches the scope described above.
Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.