Smart Folder Organizer

This skill provides a structured workflow for tidying up disorganized directories while ensuring data safety.

Core Mandates

1. Safety First: NEVER delete any file. Move files intended for deletion to specific subfolders within to_remove/ (e.g., to_remove/duplicates/ or to_remove/empty_folders/).
2. Strict Scoping: Operate ONLY within the current directory and its subdirectories. Never move or access files in the parent directory (..).
3. Preservation: If a file's category is ambiguous, move it to a Needs_Review/ folder rather than guessing incorrectly.
4. Large Files: For any file larger than 20MB, skip deep content analysis (such as reading PDF text) to prevent memory issues. Move these unanalyzed large files to a dedicated Needs_Review/LargeFiles/ directory.
5. Folder Handling: Recursively process all files within the current directory and its subdirectories. When moving files, place them in the categorized folders at the root level of the target directory (do not replicate the category structure inside every subfolder). Any empty subdirectories discovered or left behind must be moved to to_remove/empty_folders/.

Workflow

1. Smart Folder Detection

Before processing individual files, run scripts/detect_smart_folders.py <target_dir> to identify subdirectories that are already well-organized (e.g., git repositories, software projects, macOS app bundles).