organizing-files

Organizing Files

Overview

Every file has a home. Find it, move it, never delete it. This skill enforces a consistent macOS file organization structure across Desktop, Documents, Downloads, and iCloud Drive — optimized for software engineers who also have personal documents, media, and credentials scattered around.

Principles

1. No deletions — move files, never remove them
2. iCloud Documents = central hub — organized subfolders, backed up automatically
3. Desktop = clean workspace — only actively-used files
4. Downloads = temporary inbox — local-only, clear regularly into Documents
5. Git repos stay local — ~/dev/ must never be inside iCloud (sync breaks .git, node_modules)
6. Sensitive files get isolated — credentials, recovery codes, identity docs in dedicated folders
7. Inspect before sorting — read images, check EXIF/metadata, understand content before categorizing

Phase 1: Explore

Before moving anything, understand what exists. Launch parallel exploration agents:

Agent	Target	Purpose
1	~/Desktop/	File types, sizes, screen recordings vs docs
2	~/Documents/	Current structure, migration folders, images
3	~/Downloads/	File type breakdown, duplicates, installers
4	iCloud Drive root	Loose files, subfolders, empty folders
5	~/dev/	Confirm git repos are local, not in iCloud

Check iCloud sync status:

• stat ~/Desktop and stat ~/Documents — check if symlinked to iCloud
• brctl status — check iCloud sync daemon
• Look for migration folders (Desktop - <Mac Name>, Documents - <Mac Name>)

iCloud path mapping: When iCloud Desktop & Documents is enabled, ~/Desktop and ~/Documents point to iCloud Drive. The iCloud Drive root is at ~/Library/Mobile Documents/com~apple~CloudDocs/. Files at that root are separate from Desktop/Documents — they're loose files in the drive itself.

Phase 2: Inspect Content

Don't sort by filename alone. Inspect actual content. Each exploration agent must visually read images and check metadata:

File Type	Inspection Method
Images (.jpg, .png, .heic)	Read the image file visually (Claude can see images) to understand what it shows — is it a headshot, org chart, screenshot, meme, stock photo, or personal photo? Then mdls for EXIF (camera, GPS, dimensions, date)
PDFs	mdls for author, page count, title, creation date, security/encryption. Read small PDFs to understand content.
Spreadsheets (.xlsx, .csv)	head -2 for CSV headers, mdls for author/dates
Code files (.ts, .tsx, .py)	head -10 to understand purpose
Videos (.mov, .mp4)	mdls for duration, resolution, codec, creation date
Audio (.mp3, .m4a)	mdls for title, artist, duration
Hidden files (.*)	Check for dotfiles — config files, secrets, system files. Include in exploration.

Visual image inspection is critical. Filenames like IMG_6284.jpg or 20991151.jpg tell you nothing. Reading the image reveals whether it's a wedding invitation, a stock photo for a website, an office selfie, or a screenshot of credentials. Always read images with the Read tool.

Flag these immediately:

• Files with GPS coordinates embedded (privacy risk)
• Credential files (AWS keys, recovery codes, passwords)
• Password-protected/encrypted documents
• Identity documents (ID cards, driver's licenses, passports)
• Symlinks pointing to external drives or other locations — don't move these, note them

Phase 3: Plan the Structure

Target Folder Tree

~/Documents/                          # iCloud-synced central hub
├── Personal/
│   ├── Identity/                     # ID docs, driver's license, passports
│   ├── Financial/                    # Tax, salary, stock, receipts, invoices
│   ├── Legal/                        # Contracts, agreements, leases
│   ├── Medical/                      # Health records, insurance
│   ├── Travel/                       # Bookings, itineraries, travel insurance
│   ├── Orders/                       # Online order receipts
│   └── Resumes/
│       ├── Mine/                     # Own resume versions
│       └── Others/                   # Candidates' CVs
│
├── Work/
│   ├── <Company>/                    # Primary company folder
│   │   ├── Exports/                  # Data exports, reports
│   │   ├── Analytics/                # Query results, usage data
│   │   ├── Screenshots/              # App screenshots, org charts
│   │   ├── Feature Demos/            # Named demo videos
│   │   └── HR/                       # HR surveys, research
│   ├── <Previous Company>/           # Old employer docs
│   ├── Documentation/                # Technical docs, blog posts, meeting notes
│   └── Job Descriptions/             # JDs for hiring
│
├── Media/
│   ├── Photos/
│   │   ├── Headshots/                # Professional photos + variants
│   │   ├── DSLR/                     # Camera photos by shoot
│   │   └── Personal/                 # Phone photos, misc images
│   ├── Logos & Branding/             # Company logos, SVGs, design assets
│   ├── AI Generated/                 # Midjourney, DALL-E, Gemini outputs
│   ├── GIFs & Memes/                 # Animated GIFs, reaction images, slackmojis
│   ├── Audio/                        # Music, voice recordings
│   ├── Screen Recordings/            # Generic recordings, by month
│   │   ├── YYYY-MM/                  # Organized by year-month
│   │   └── ...
│   └── Videos/                       # Other video files
│
├── Technical/
│   ├── 3D Printing/                  # GCODE, STEP, STL files
│   ├── Code Snippets/                # Loose .ts, .tsx, .py files
│   ├── Config Backups/               # TablePlus, keybindings, dotfiles
│   └── Design Files/                 # PSD, Figma exports
│
├── Sensitive/                        # Credentials and recovery files
│   ├── Recovery Codes/               # Browser, VPN, 2FA recovery
│   └── Cloud Credentials/            # AWS, GCP, etc.
│
└── Archive/
    ├── Installers/                   # DMG, PKG, ZIP app installers
    ├── Old Backups/                  # Device backups, PST archives
    ├── Old Firmware/                 # Router firmware, device updates
    └── Misc/                         # UUID-named files, unknown docs, logs

Desktop — Keep Empty

Move everything off Desktop into the structure above. Desktop is a workspace, not storage.

Downloads — Clear Into Documents

Everything in Downloads should be sorted into ~/Documents/ subfolders. Downloads is a temporary landing zone.

iCloud Root — No Loose Files

All loose files at iCloud Drive root move into ~/Documents/ subfolders. Only system symlinks (Desktop, Documents) should remain at root.

Phase 4: Execute

Execution Order

1. Create all target directories with mkdir -p
2. Move iCloud root loose files → Documents subfolders
3. Move iCloud subfolder contents → Documents subfolders
4. Flatten migration folders (Desktop - <Mac Name>, Documents - <Mac Name>) → Documents
5. Move Downloads files → Documents subfolders
6. Handle duplicates — keep both, rename with date suffix: file (2025-12-15).ext
7. Verify all moves completed

Duplicate Handling

When the same filename exists in multiple locations:

# Keep both, rename the duplicate with its modification date
mv "duplicate.pdf" "duplicate (2025-12-15).pdf"

Never overwrite. Never delete. Always preserve both copies.

Sensitive Files

After moving credentials to Sensitive/, remind the user:

• AWS keys should live in a password manager, not the filesystem
• Recovery code images should be encrypted or vault-stored
• GPS-tagged photos should be stripped before sharing publicly

Phase 5: Verify

After all moves:

1. ls ~/Desktop/ — should be empty or near-empty
2. ls ~/Downloads/ — should be empty (existing files moved)
3. find ~/Documents/ -maxdepth 2 -type d | sort — verify folder tree
4. Check for any files left behind in iCloud root
5. Count files per category — sanity check totals match original counts

Red Flags — STOP

Thought	Action
"I'll sort by extension/filename"	INSPECT CONTENT — read images visually, check metadata, peek at CSVs. A .pdf could be financial or junk.
"I'll delete these old installers"	NO DELETIONS — move to Archive/Installers/
"Git repos should be in Documents"	NEVER — ~/dev stays local, outside iCloud
"I'll merge these duplicates"	KEEP BOTH — rename with date suffix
"Credentials are fine in Documents"	ISOLATE in Sensitive/ folder, warn user
"I'll organize Downloads later"	DO IT NOW — Downloads is the biggest mess
"Desktop needs some files on it"	EMPTY IT — Desktop is a workspace, not storage

Anti-Patterns

Extension-only sorting: Moving all .pdf to one folder ignores that PDFs span financial docs, identity docs, resumes, and junk. Always inspect content.

Flat category folders: Don't dump 50 spreadsheets into one folder. Use subcategories (Exports/, Analytics/, HR/).

Ignoring iCloud root: Users forget iCloud Drive root has its own loose files separate from Desktop/Documents. Always check it.

Skipping metadata: EXIF data reveals GPS coordinates (privacy risk), camera models (helps identify photo sources), and creation dates (helps determine if files are current or archival).

Moving git repos to iCloud: iCloud sync corrupts .git directories and creates conflicts with node_modules, __pycache__, and other generated files. Development repos must stay local.