file-organizer
Intelligently structures, cleans, and deduplicates directories and workspaces across systems. Trigger when a user needs to: (1) Standardize chaotic folders (e.g., Downloads, Documents), (2) Clean up d
SKILL.mdskills/file-organizer/SKILL.md
GitHubFile Organizer
This is a self-contained skill. Do NOT load external files or reference external directories unless specifically instructed by the user.
1. Trigger Scenarios & Decision Trees
Workflow Decision Tree
graph TD
A[Organization Request] --> B{Primary Goal?}
B -->|De-clutter & Group| C[Taxonomy & Sorting Workflow]
B -->|Find Duplicates| D[Deduplication Workflow]
B -->|Stale File Cleanup| E[Archiving Workflow]
C --> C1[Analyze folder contents, extensions & sizes]
C1 --> C2[Propose taxonomy tree -> Seek user approval]
C2 --> C3[Dry-run moves -> Log changes -> Execute]
D --> D1[Find matches: size -> name -> md5 hash]
D1 --> D2[Group & present duplicates with timestamps]
D2 --> D3[Seek explicit deletion confirmation -> Execute]
2. Constraints & Freedom Calibration
- Destructive Actions (Low Freedom): Do not delete files or folders automatically. You must prompt the user for explicit confirmation before every single deletion or permanent cleanup command.
- Active Directory Structuring (Medium Freedom): When organizing work files or repositories, respect system directories (e.g.,
.git,.vscode,node_modules). Never move configuration folders or active development projects without verification. - Folder Classification Hierarchy (High Freedom): Design classifications suited to the user's specific context (e.g., sorting by project phases, clients, file formats, or chronological order).
3. Expert-Level Knowledge Delta
Duplicate Identification Tradeoffs
To optimize performance and accuracy when searching for duplicates:
| Matching Level | Computational Cost | Reliability | Edge Cases |
|---|---|---|---|
| Name Match | Very Low | Low (False Positives) | Different versions of files with default names (e.g., invoice.pdf). |
| Size Match | Low | Medium | Empty files (0 bytes) or placeholder files of identical size. |
| MD5/SHA256 Hash | High (Reads full file) | High (Definitive) | Extremely large video files; calculate hash on first 1MB for early exit. |
Rule of Thumb: Filter first by size, then by filename/extension, and finally calculate the file hash only for candidate matches of identical size.
4. Mindset & Actionable Procedures
Self-Inquiry Checklist
- Am I about to run a move (
mv) command? Have I checked if there are file name collisions in the destination directory? - Are there configuration files (e.g.,
.env,.gitignore) or application libraries that would break if moved? - Did I perform a dry-run log of changes before shifting the physical directory structure?
- How does the proposed taxonomy reduce the user's future cognitive load for retrieving these files?
Step-by-Step Execution Sequence
- Scope & Assessment:
- Find file count and total size:
du -sh [directory]. - Analyze file type distribution:
find [dir] -type f | sed 's/.*\.//' | sort | uniq -c.
- Find file count and total size:
- Taxonomy Design:
- Draft a proposed structure. Avoid deep nesting (limit folder depth to 3 levels max). Use prefix sorting (e.g.,
01-active,02-archive) where sequence matters.
- Draft a proposed structure. Avoid deep nesting (limit folder depth to 3 levels max). Use prefix sorting (e.g.,
- Conflict Checks:
- Search duplicates using candidate size filters first, then hashing.
- Check for name conflicts: if
file.pdfalready exists intarget/, prepare a renaming suffix:file_YYYY-MM-DD.pdf.
- Dry-run & Execution:
- Show user: (1) Old layout vs. New layout, (2) Count of moves, (3) Candidates for deletion.
- Execute moves using clear, verbose scripts that log changes.
5. Anti-Patterns & Never-Lists
| Action | Why Avoid It | Correction/Alternative |
|---|---|---|
NEVER run destructive commands (rm, rm -rf) without user approval. |
Can cause irreversible data loss of valuable documents or configurations. | Always ask the user to confirm the files to delete, or move them to a temporary trash folder first. |
| NEVER move active programming repositories or git directories. | Breaks references, commits, relative imports, and pathing in build pipelines. | Exclude folders containing .git, node_modules, or build systems from automation. |
| NEVER run recursive organization on the entire system root or home directory. | Alters critical config paths, application profiles, and system defaults. | Limit scopes strictly to localized user folders (e.g., Downloads, Desktop, Documents). |
| NEVER write moving scripts without handling filename collisions. | Moving files with the same name into the same folder will silently overwrite content. | Write script logic that renames conflicting files with timestamps or unique numbers. |
6. Error Scenarios & Fallbacks
Destination Name Collision
- Scenario: Moving
report.docxto/Documents/Work/but/Documents/Work/report.docxalready exists. - Fallback: Use modification timestamps. Append the date or a sequence number to the new file:
report_2026-07-17.docxorreport_1.docx.
Permission Denied
- Scenario: Moving files fails due to file locks or user privilege restrictions.
- Fallback: Skip the locked file, log the error path, continue organizing the remaining files, and report the skipped paths to the user.
Broken Symlinks
- Scenario: Moving target files breaks symlinks pointing to them.
- Fallback: Find symlinks targeting the source files using
find -L . -xtype land update the symlink destinations to point to the new paths.