---
name: file-organizer
description: Intelligently organize files and folders by understanding context and finding duplicates
version: 1.0.0
author: ComposioHQ (adapted)
platforms: [claude-code]
license: Apache-2.0
source: https://github.com/ComposioHQ/awesome-claude-skills
---

# File Organizer

Intelligently organize your file system by analyzing content and context.

## Capabilities
- Scan directories and understand their purpose
- Find duplicate files (by content hash, not just name)
- Suggest better folder structures
- Rename files to follow consistent conventions
- Identify stale/unused files (not modified in X months)
- Move files with user confirmation

## Working Safely
**Always ask for confirmation before moving or deleting files.**
**Never delete — move to `.archive/` folder instead.**

## Workflow

### 1. Discovery Phase
```bash
# Understand the current structure
find ~/Downloads -type f | head -50
du -sh ~/Downloads/*/ | sort -rh | head -20
```

### 2. Analysis
For each file, determine:
- Content type (by reading first bytes, not just extension)
- Likely category (work, personal, code, media, document)
- Recency (last modified date)
- Potential duplicates

### 3. Propose Structure
```
~/Documents/
├── Work/
│   ├── Projects/
│   │   ├── ProjectA/
│   │   └── ProjectB/
│   └── Invoices/
│       ├── 2024/
│       └── 2025/
├── Personal/
│   ├── Photos/
│   └── Finance/
└── Archive/
    └── [files older than 1 year]
```

### 4. Execute with Approval
For each batch of moves:
1. Show: what moves where and why
2. Wait for approval
3. Execute with `mv` commands
4. Log all changes to `file-organizer.log`

## Naming Conventions
- Dates: `YYYY-MM-DD_description.ext`
- Invoices: `YYYY-MM-DD_Vendor_Amount.pdf`
- Screenshots: `YYYY-MM-DD_context.png`
- Code: kebab-case for projects, snake_case for Python files

## Duplicate Detection
```python
import hashlib
from pathlib import Path

def file_hash(path: Path) -> str:
    return hashlib.md5(path.read_bytes()).hexdigest()
```