File Organization

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.