File System Organizer

---
name: "file-system-organizer"
description: "This skill scans a hard drive or SSD to find duplicate files, unnecessary items, and disorganized folders, then reorganizes them into logical categories and deletes redundant copies. Use this skill when the user says \"clean my drive\", \"find duplicates\", \"organize files\", or \"free space\". Do not use this skill for real-time file monitoring or for backing up data."
---

Purpose
This skill reorganizes a file system by removing duplicates, deleting obsolete files, and sorting remaining items into logical folders, freeing storage space.

## When to use
- The user requests a full cleanup of a drive or SSD.
- The user wants to find and remove duplicate files.
- The user needs to free up space by deleting unused files.
- The user wants to reorganize files into categories such as Models, Documents, Media, etc.

## When not to use
Use the **file-backup** skill instead for backing up data before making changes.

## Inputs
The skill requires the following information:
1. **root_path** – the absolute path of the drive or SSD to scan (e.g., `/mnt/data`).
2. **exclude_dirs** – optional list of directory names to skip (e.g., `['.git', 'node_modules']`).
3. **file_categories** – optional mapping of file extensions to target folders (e.g., `{'.py': 'Code', '.jpg': 'Images'}`).
4. **dry_run** – optional boolean; if true, the skill only reports actions without executing them.

If any input is missing, the skill will prompt the user for it.

## Steps
1. **Validate inputs** – Ensure `root_path` exists and is readable.
   *Why*: Prevents errors during traversal.
2. **Build file index** – Recursively walk `root_path`, collecting file paths, sizes, and hashes.
   *Why*: Enables duplicate detection and size calculations.
3. **Detect duplicates** – Group files by hash; identify groups with more than one file.
   *Why*: Identifies exact copies that can be removed.
4. **Determine retention policy** – For each duplicate group, keep the newest file (by modification time) and mark older ones for deletion.
   *Why*: Preserves the most recent version while freeing space.
5. **Identify obsolete files** – Scan for files older than a user‑defined threshold (e.g., 365 days) or matching patterns like `*.tmp`.
   *Why*: Removes files likely no longer needed.
6. **Categorize remaining files** – Use `file_categories` to map extensions to target folders; create missing folders under `root_path`.
   *Why*: Organizes files for easier retrieval.
7. **Move files** – Relocate each file to its target folder, preserving relative paths where appropriate.
   *Why*: Consolidates files into a logical structure.
8. **Delete marked files** – Remove duplicates and obsolete files unless `dry_run` is true.
   *Why*: Frees disk space.
9. **Generate report** – Summarize actions: number of files scanned, duplicates found, space freed, and final folder structure.
   *Why*: Provides user with clear outcome.

## Output format
```json
{
  "scanned_files": <int>,
  "duplicate_groups": <int>,
  "duplicates_deleted": <int>,
  "obsolete_files_deleted": <int>,
  "space_freed_bytes": <int>,
  "final_structure": {
    "<folder_name>": <int>,
    ...
  }
}
```

## Example
**Input**
```json
{
  "root_path": "/mnt/data",
  "exclude_dirs": [".git"],
  "file_categories": {".py": "Code", ".jpg": "Images"},
  "dry_run": false
}
```

**Output**
```json
{
  "scanned_files": 12345,
  "duplicate_groups": 67,
  "duplicates_deleted": 45,
  "obsolete_files_deleted": 12,
  "space_freed_bytes": 987654321,
  "final_structure": {
    "Code": 2345,
    "Images": 876,
    "Documents": 3456,
    "Media": 1234
  }
}
```

## Checks before finishing
- Confirm all targeted deletions are listed in the report.
- Ensure no files in `exclude_dirs` were moved or deleted.
- Verify that the final folder structure matches `file_categories` mapping.