file-organizer-skill
Organize files in directories by grouping them into folders based on their extensions or date. Includes Dry-Run, Recursive, and Undo capabilities.
About this skill
This skill provides a robust utility for automatically organizing messy file directories. It can group files into new subfolders based on their file extensions (e.g., all `.jpg` files into a `JPG` folder) or by date (e.g., `2023/January` for files created in January 2023), making it ideal for managing photo collections, downloaded archives, or cluttered project folders. It incorporates essential safety features like a `dry-run` mode to preview changes without execution, conflict resolution for duplicate filenames, and a crucial `undo` capability that reverts the last organization using a generated history file. The skill also supports recursive scanning for deep cleaning nested directories and generates an audit log (`organize_history.json`) for transparency. Users benefit from significant time savings in manual file sorting, reduced clutter, and improved navigability of their file systems. Its flexibility with sorting criteria, combined with robust safety mechanisms, makes it a powerful tool for maintaining an orderly digital environment without fear of irreversible mistakes.
Best use case
The primary use case for `file-organizer-skill` is decluttering and structuring chaotic digital folders. It's particularly beneficial for individuals or developers who frequently download files, manage large photo archives, or deal with project directories that accumulate various file types over time. By automating the categorization of files, users can quickly bring order to their data, making it easier to locate specific items and maintain a clean and efficient workspace.
Organize files in directories by grouping them into folders based on their extensions or date. Includes Dry-Run, Recursive, and Undo capabilities.
The target directory will be restructured into subfolders, with files neatly grouped by their extensions or creation dates, and an `organize_history.json` file generated for tracking and undo purposes.
Practical example
Example input
Organize all files in my 'Downloads' folder by extension, but first show me what changes will be made without moving anything.
Example output
Dry Run: 50 files would be moved. .pdf files -> pdf/, .jpg files -> jpg/, etc. No files moved. Organization complete for /path/to/folder. 120 files moved. History logged to /path/to/folder/organize_history.json.
When to use this skill
- When a directory contains many different file types that need categorizing.
- When organizing large collections of photos or documents by creation date.
- When you need to perform a dry run to preview file movements before execution.
- When you need to quickly revert a previous file organization operation.
When not to use this skill
- When you need highly specific, custom sorting logic beyond extensions or dates.
- When files are already perfectly organized and require no changes.
- When operating on critical system directories where accidental modification could cause instability without careful dry-run verification.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/file-organizer-skill/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How file-organizer-skill Compares
| Feature / Agent | file-organizer-skill | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | easy | N/A |
Frequently Asked Questions
What does this skill do?
Organize files in directories by grouping them into folders based on their extensions or date. Includes Dry-Run, Recursive, and Undo capabilities.
How difficult is it to install?
The installation complexity is rated as easy. You can find the installation instructions above.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
Related Guides
Best AI Skills for ChatGPT
Find the best AI skills to adapt into ChatGPT workflows for research, writing, summarization, planning, and repeatable assistant tasks.
Top AI Agents for Productivity
See the top AI agent skills for productivity, workflow automation, operational systems, documentation, and everyday task execution.
AI Agents for Freelancers
Browse AI agent skills for freelancers handling client research, proposals, outreach, delivery systems, documentation, and repeatable admin work.
SKILL.md Source
# File Organizer (Gold Standard) ## Features - **Smart Sorting**: Group by Extension (Default) or Date (Year/Month). - **Safety**: Conflict resolution (auto-rename), Dry Run mode, and Undo capability. - **Deep Clean**: Recursive scanning option. - **Audit**: Generates `organize_history.json` for tracking. ## Usage ### Basic Sort (by Extension) ```bash python3 scripts/organize.py /path/to/folder ``` ### Date Sort (Year/Month) Great for photos or archives. ```bash python3 scripts/organize.py /path/to/folder --date ``` ### Dry Run (Simulate) See what *would* happen without moving anything. ```bash python3 scripts/organize.py /path/to/folder --dry-run ``` ### Undo Revert changes using the history file. ```bash python3 scripts/organize.py --undo /path/to/folder/organize_history.json ``` ## Config Modify `scripts/organize.py` `get_default_mapping()` to add custom extensions.
Related Skills
filesystem
Advanced filesystem operations for listing files, searching content, batch processing, and directory analysis. Supports recursive search, file type filtering, size analysis, and batch operations like copy/move/delete. Use when you need to: list directory contents, search for files by name or content, analyze directory structures, perform batch file operations, or analyze file sizes and distribution.
find-skills
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
Budget & Expense Tracker — AI Agent Financial Command Center
Track every dollar, enforce budgets, spot spending patterns, and build wealth — all through natural conversation with your AI agent.
yt-dlp
A robust CLI wrapper for yt-dlp to download videos, playlists, and audio from YouTube and thousands of other sites. Supports format selection, quality control, metadata embedding, and cookie authentication.
time-checker
Check accurate current time, date, and timezone information for any location worldwide using time.is. Use when the user asks "what time is it in X", "current time in Y", or needs to verify timezone offsets.
pihole-ctl
Manage and monitor local Pi-hole instance. Query FTL database for statistics (blocked ads, top clients) and control service via CLI. Use when user asks "how many ads blocked", "pihole status", or "update gravity".
mermaid-architect
Generate beautiful, hand-drawn Mermaid diagrams with robust syntax (quoted labels, ELK layout). Use this skill when the user asks for "diagram", "flowchart", "sequence diagram", or "visualize this process".
memory-cache
High-performance temporary storage system using Redis. Supports namespaced keys (mema:*), TTL management, and session context caching. Use for: (1) Saving agent state, (2) Caching API results, (3) Sharing data between sub-agents.
mema
Mema's personal brain - SQLite metadata index for documents and Redis short-term context buffer. Use for organizing workspace knowledge paths and managing ephemeral session state.
media-compress
Compress and convert images and videos using ffmpeg. Use when the user wants to reduce file size, change format, resize, or optimize media files. Handles common formats like JPG, PNG, WebP, MP4, MOV, WebM. Triggers on phrases like "compress image", "compress video", "reduce file size", "convert to webp/mp4", "resize image", "make image smaller", "batch compress", "optimize media".
edge-tts
Text-to-speech conversion using node-edge-tts npm package for generating audio from text. Supports multiple voices, languages, speed adjustment, pitch control, and subtitle generation. Use when: (1) User requests audio/voice output with the "tts" trigger or keyword. (2) Content needs to be spoken rather than read (multitasking, accessibility, driving, cooking). (3) User wants a specific voice, speed, pitch, or format for TTS output.
ocr-local
Extract text from images using Tesseract.js OCR (100% local, no API key required). Supports Chinese (simplified/traditional) and English.