🇺🇸English
File Organization
This skill enables an AI agent to bring order to cluttered directories. Given a target path, the agent scans all files, classifies them using a configurable rule set, and moves them into a well-structured directory tree. It supports organization by file type, modification date, project association, or priority level. Advanced features include duplicate detection via content hashing, consistent naming conventions, dry-run previews, and automated archival of stale files.
Workflow
-
Scan the Target Directory Recursively enumerate all files in the specified directory. Collect metadata for each file: name, extension, size, creation date, modification date, and content hash (SHA-256, computed lazily for duplicate detection). Skip hidden files and system files (e.g., .DS_Store, Thumbs.db) by default, but allow the user to include them via configuration.
-
Classify Files by Rule Set Apply the active organization strategy to assign each file to a destination folder. The default strategy groups by file type using a built-in extension map (e.g., .pdf → documents/, .png → images/, .mp3 → audio/). Alternative strategies include: group by modification date (2025/01/, 2025/02/), group by project name inferred from path prefixes or filename tags, or group by a priority label embedded in the filename (e.g., URGENT-report.pdf → priority-high/). Users can supply a custom rule file in YAML or JSON to override or extend any strategy.
-
Detect and Handle Duplicates Compare content hashes across all scanned files. When duplicates are found, keep the most recently modified copy in the target location and move older copies to a _duplicates/ staging folder. Present a summary of duplicates to the user for review before permanent deletion. Optionally, replace duplicates with symbolic links to the canonical copy to save disk space while preserving path references.
-
Apply Naming Conventions Normalize filenames according to the configured convention. Options include: kebab-case (quarterly-report-2025.pdf), snake_case (quarterly_report_2025.pdf), or date-prefixed (2025-01-15_quarterly-report.pdf). Strip special characters, collapse whitespace, and transliterate Unicode to ASCII when requested. Preserve original extensions. Log every rename so the operation is reversible.
-
Execute the Move Plan (or Dry Run) Before moving any files, generate a complete move plan showing source and destination for every file. In dry-run mode (the default for first invocation), display the plan and ask for confirmation. Once confirmed, create destination directories as needed and move files atomically. Write a manifest file (_organization-log.json) to the root of the target directory recording every action taken, enabling a full undo.
-
Archive Stale Files Optionally identify files that have not been accessed or modified within a configurable threshold (default: 12 months). Move these files to an _archive/ directory, preserving the organized subfolder structure. Compress the archive folder into a .tar.gz or .zip if requested. Notify the user of the total space reclaimed.
Usage
Point the agent at a directory and specify the organization strategy. If no strategy is given, the agent defaults to organizing by file type.
"Organize my ~/Downloads folder by file type."
"Sort the files in /data/raw-exports by modification date, using YYYY/MM subfolders."
"Organize ~/Projects/acme-app using this config file: .file-org-rules.yaml"
A custom rule file looks like this:
# .file-org-rules.yaml
strategy: type
naming: kebab-case
date_prefix: true
archive_after_days: 365
type_map:
documents: [pdf, docx, txt, md, csv]
images: [jpg, jpeg, png, gif, svg, webp]
audio: [mp3, wav, flac, aac]
video: [mp4, mov, avi, mkv]
archives: [zip, tar, gz, rar, 7z]
code: [py, js, ts, go, rs, java, c, cpp, h]
data: [json, xml, yaml, yml, toml, sql]
ignore:
- node_modules
- .git
- __pycache__
Examples
Example 1 — Organizing a Messy Downloads Folder
Before:
~/Downloads/
├── IMG_4012.jpg
├── IMG_4012 (1).jpg ← duplicate
├── Q3 Financial Report.pdf
├── meeting-notes.txt
├── setup_installer.exe
├── song.mp3
├── profile photo.PNG
├── data_export.csv
├── slides_final_v2.pptx
├── backup.zip
└── vacation vid.mp4
User input:
"Organize ~/Downloads by file type. Use kebab-case naming. Detect duplicates."
Agent output (dry-run preview):
Scan complete: 11 files found, 1 duplicate detected.
Duplicate: IMG_4012 (1).jpg is identical to IMG_4012.jpg (SHA-256 match)
→ Moving IMG_4012 (1).jpg to _duplicates/
Move plan:
IMG_4012.jpg → images/img-4012.jpg
profile photo.PNG → images/profile-photo.png
Q3 Financial Report.pdf → documents/q3-financial-report.pdf
meeting-notes.txt → documents/meeting-notes.txt
data_export.csv → documents/data-export.csv
slides_final_v2.pptx → presentations/slides-final-v2.pptx
song.mp3 → audio/song.mp3
vacation vid.mp4 → video/vacation-vid.mp4
setup_installer.exe → applications/setup-installer.exe
backup.zip → archives/backup.zip
Confirm? (yes / no / edit plan)
After (once confirmed):
~/Downloads/
├── _duplicates/
│ └── img-4012-1.jpg
├── _organization-log.json
├── applications/
│ └── setup-installer.exe
├── archives/
│ └── backup.zip
├── audio/
│ └── song.mp3
├── documents/
│ ├── data-export.csv
│ ├── meeting-notes.txt
│ └── q3-financial-report.pdf
├── images/
│ ├── img-4012.jpg
│ └── profile-photo.png
├── presentations/
│ └── slides-final-v2.pptx
└── video/
└── vacation-vid.mp4
Example 2 — Organizing a Project Repository with a Standard Structure
User input:
"Reorganize ~/code/my-api into a standard Go project layout. Move source files, tests, configs, and docs into conventional locations."
Agent output (dry-run preview):
Detected project type: Go (found go.mod)
Proposed structure:
cmd/my-api/main.go ← entry point (moved from ./main.go)
internal/handlers/ ← HTTP handlers (moved from ./handlers/)
internal/models/ ← data models (moved from ./models/)
internal/service/ ← business logic (moved from ./service/)
pkg/ ← exported library code (empty — populate later)
configs/config.yaml ← moved from ./config.yaml
docs/api-spec.md ← moved from ./API.md
scripts/migrate.sh ← moved from ./migrate.sh
test/integration/ ← moved from ./integration_tests/
go.mod ← unchanged
go.sum ← unchanged
README.md ← unchanged
7 files moved, 3 directories created, 2 files unchanged.
Import paths in Go files updated automatically.
Confirm? (yes / no / edit plan)
Best Practices
- Always start with a dry run. Never move files without showing the user a complete plan first. Accidental reorganization of a working project directory can break builds and tooling.
- Preserve a manifest log. Write every action (moves, renames, deletions) to a JSON log file at the root of the target directory. This makes the operation fully reversible.
- Respect version control. If the target directory is inside a Git repository, use
git mv instead of a raw filesystem move so that history is preserved. Warn the user if uncommitted changes exist.
- Handle filename collisions. When two different files would map to the same destination path, append a numeric suffix (e.g.,
report.pdf and report-1.pdf) rather than overwriting silently.
- Skip known dependency directories. Exclude
node_modules/, .git/, __pycache__/, vendor/, and similar tool-managed directories by default. Reorganizing these breaks package managers.
Edge Cases
- Empty directories left behind. After moving files out of a folder, check whether the source folder is now empty. Offer to remove empty directories to keep the tree clean.
- Symbolic links and hard links. Do not follow symbolic links during the scan — record them as links and ask the user how to handle them (move the link, resolve to the target, or skip).
- Files with no extension. Classify extensionless files as
other/ by default. If the file has a shebang line (e.g., #!/usr/bin/env python3), infer the type from the interpreter.
- Very large directories ( >10,000 files). Process files in batches and provide a progress indicator. Avoid loading the entire file list into memory at once.
- Permission errors. If a file cannot be read or moved due to filesystem permissions, log it, skip it, and continue with the remaining files. Present a summary of skipped files at the end.
- Network or external drives. Warn the user that reorganizing files on a network share or external drive may be significantly slower and that interrupted operations could leave files in an inconsistent state. Recommend working on a local copy first.
Weekly Installs
–
Repository
seb1n/awesome-a…t-skills
GitHub Stars
51
First Seen
–
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
