Intelligent File Organizer

The Problem: Taming File Chaos

Downloads, desktops, and project folders often become digital dumping grounds, cluttered with documents, images, code snippets, installers, and media files from various sources. Manually sorting them is tedious, error-prone, and makes critical files hard to locate later. For knowledge workers and developers juggling diverse file types, this disorganization creates a significant drag on workflow.

How the Skill Works: Core Capabilities

file-organizer automates this process, acting as more than a simple script—it's an agent with planning and interactive confirmation built-in.

1. Intelligent Scanning: Using Glob patterns or Bash commands, it first inventories all files in a target directory (default depth of 1, extensible via --recursive), analyzing extensions, modification dates, or size.
2. Multi-Mode Categorization: Based on user instructions, it applies one of three strategies:
   • By File Type (default): Maps files to predefined categories like 'Documents', 'Images', 'Code'.
   • By Date (--mode date): Creates a hierarchical directory structure like 2023/09/.
   • Custom Rules: Users can provide a custom mapping of extensions to folder names (e.g., .pdf -> 'Ebooks'), enabling highly personalized organization.
3. The Safety Net: Preview & Confirm: This is a critical step. Before any files are moved, the agent generates a detailed organization plan, showing file counts per category and target paths. The user must review and approve this plan before execution proceeds. This prevents unintended consequences.
4. Execution & Reporting: Once confirmed, the agent creates the necessary directories, moves (or copies) the files, and outputs a final report with statistics.

Important Constraints and Considerations

• Scan Depth: By default, it only processes files in the root of the target folder and does not recurse into subdirectories. Explicitly request --recursive for deep-level organization.
• Safety by Design: Files are never overwritten. Naming conflicts are resolved by appending a numeric suffix (e.g., _1). Files starting with a dot (.) are skipped by default unless explicitly instructed otherwise.
• Permissions and Scale: Files larger than 500MB trigger a confirmation prompt. Files without read/write permissions are skipped and noted in the final report.
• Operation Modes: Supports moving (default) or copying (--copy) files. The source directory's empty folders are preserved by default; cleanup requires a specific user request (--clean-empty-dirs).
  In essence, this is a cautious, transparent file organization assistant that ensures a controllable process through its "plan, confirm, execute" workflow.