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.
- Verify integrity after moves. After execution, compare the SHA-256 hash of each moved file against the original hash recorded during the scan to confirm no data corruption occurred.
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.
1---2name: file-organization3description: Automatically organizes files in a directory into a clean structure based on configurable rules — by file type, date, project, or priority — with support for duplicate detection, naming conventions, and archival strategies.4license: MIT5---67# File Organization89This 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.1011## Workflow12131. **Scan the Target Directory**14 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.15162. **Classify Files by Rule Set**17 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.18193. **Detect and Handle Duplicates**20 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.21224. **Apply Naming Conventions**23 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.24255. **Execute the Move Plan (or Dry Run)**26 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.27286. **Archive Stale Files**29 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.3031## Usage3233Point the agent at a directory and specify the organization strategy. If no strategy is given, the agent defaults to organizing by file type.3435```36"Organize my ~/Downloads folder by file type."37```3839```40"Sort the files in /data/raw-exports by modification date, using YYYY/MM subfolders."41```4243```44"Organize ~/Projects/acme-app using this config file: .file-org-rules.yaml"45```4647A custom rule file looks like this:4849```yaml50# .file-org-rules.yaml51strategy: type52naming: kebab-case53date_prefix: true54archive_after_days: 36555type_map:56 documents: [pdf, docx, txt, md, csv]57 images: [jpg, jpeg, png, gif, svg, webp]58 audio: [mp3, wav, flac, aac]59 video: [mp4, mov, avi, mkv]60 archives: [zip, tar, gz, rar, 7z]61 code: [py, js, ts, go, rs, java, c, cpp, h]62 data: [json, xml, yaml, yml, toml, sql]63ignore:64 - node_modules65 - .git66 - __pycache__67```6869## Examples7071### Example 1 — Organizing a Messy Downloads Folder7273**Before:**74```75~/Downloads/76├── IMG_4012.jpg77├── IMG_4012 (1).jpg ← duplicate78├── Q3 Financial Report.pdf79├── meeting-notes.txt80├── setup_installer.exe81├── song.mp382├── profile photo.PNG83├── data_export.csv84├── slides_final_v2.pptx85├── backup.zip86└── vacation vid.mp487```8889**User input:**90```91"Organize ~/Downloads by file type. Use kebab-case naming. Detect duplicates."92```9394**Agent output (dry-run preview):**95```96Scan complete: 11 files found, 1 duplicate detected.9798Duplicate: IMG_4012 (1).jpg is identical to IMG_4012.jpg (SHA-256 match)99 → Moving IMG_4012 (1).jpg to _duplicates/100101Move plan:102 IMG_4012.jpg → images/img-4012.jpg103 profile photo.PNG → images/profile-photo.png104 Q3 Financial Report.pdf → documents/q3-financial-report.pdf105 meeting-notes.txt → documents/meeting-notes.txt106 data_export.csv → documents/data-export.csv107 slides_final_v2.pptx → presentations/slides-final-v2.pptx108 song.mp3 → audio/song.mp3109 vacation vid.mp4 → video/vacation-vid.mp4110 setup_installer.exe → applications/setup-installer.exe111 backup.zip → archives/backup.zip112113Confirm? (yes / no / edit plan)114```115116**After (once confirmed):**117```118~/Downloads/119├── _duplicates/120│ └── img-4012-1.jpg121├── _organization-log.json122├── applications/123│ └── setup-installer.exe124├── archives/125│ └── backup.zip126├── audio/127│ └── song.mp3128├── documents/129│ ├── data-export.csv130│ ├── meeting-notes.txt131│ └── q3-financial-report.pdf132├── images/133│ ├── img-4012.jpg134│ └── profile-photo.png135├── presentations/136│ └── slides-final-v2.pptx137└── video/138 └── vacation-vid.mp4139```140141### Example 2 — Organizing a Project Repository with a Standard Structure142143**User input:**144```145"Reorganize ~/code/my-api into a standard Go project layout. Move source files, tests, configs, and docs into conventional locations."146```147148**Agent output (dry-run preview):**149```150Detected project type: Go (found go.mod)151152Proposed structure:153 cmd/my-api/main.go ← entry point (moved from ./main.go)154 internal/handlers/ ← HTTP handlers (moved from ./handlers/)155 internal/models/ ← data models (moved from ./models/)156 internal/service/ ← business logic (moved from ./service/)157 pkg/ ← exported library code (empty — populate later)158 configs/config.yaml ← moved from ./config.yaml159 docs/api-spec.md ← moved from ./API.md160 scripts/migrate.sh ← moved from ./migrate.sh161 test/integration/ ← moved from ./integration_tests/162 go.mod ← unchanged163 go.sum ← unchanged164 README.md ← unchanged1651667 files moved, 3 directories created, 2 files unchanged.167Import paths in Go files updated automatically.168169Confirm? (yes / no / edit plan)170```171172## Best Practices173174- **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.175- **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.176- **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.177- **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.178- **Skip known dependency directories.** Exclude `node_modules/`, `.git/`, `__pycache__/`, `vendor/`, and similar tool-managed directories by default. Reorganizing these breaks package managers.179- **Verify integrity after moves.** After execution, compare the SHA-256 hash of each moved file against the original hash recorded during the scan to confirm no data corruption occurred.180181## Edge Cases182183- **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.184- **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).185- **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.186- **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.187- **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.188- **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.
h4vzz