icloud-organizer

Files (1)

• SKILL.md

SKILL.md (first lines)

## What I do

This skill helps you organize and maintain your iCloud directory with:
- **Full Scan**: Complete analysis of all files (first run or periodic)
- **Light Scan**: Quick check for new/changed files only
- **Smart Organization**: Recommends logical directory structure and naming conventions
- **De-duplication**: Finds and removes duplicate files using hash-based detection
- **De-clutter**: Identifies old/unaccessed files as candidates for deletion

## When to use me

Use this skill when you want to:
- First-time organization of a messy iCloud directory
- Regular maintenance to keep things organized
- Find and remove duplicate files
- Clean up old, unused files

## Directory Structure Recommendation

### Recommended: Hybrid Approach (Category + Date)

```
iCloud Drive/
├── Documents/
│   ├── Work/
│   │   ├── 2024/
│   │   ├── 2025/
│   │   └── 2026/
│   ├── Personal/
│   │   └── 2026/
│   └── Archives/
├── Images/
│   ├── Screenshots/
│   ├── Photos/
│   └── Screens/
├── Videos/
├── Audio/
├── Projects/
└── Downloads/
```

### Alternative Approaches

**Pure Category** (best for small, focused collections):
```
Documents/
├── Contracts/
├── Receipts/
└── Reports/
```

**Pure Date** (best for chronological records):
```
2024/
├── 01_January/
├── 02_February/
└── ...
```

**Pros/Cons Summary:**

| Approach | Pros | Cons |
|----------|------|------|
| Category + Date | Best of both, scalable | More complex |
| Pure Category | Easy to find type | Can mix unrelated |
| Pure Date | Chronological order | Hard to find by topic |
| Project-based | All related files together | Overhead for small files |

## Naming Convention Recommendation

### Format: `[Date]_[Category]_[Description]_[Version].ext`

**Examples:**
- `2026-04-15_Work_ProjectProposal_v1.pdf`
- `2026-03-20_Personal_TaxReturn_2025.pdf`
- `2026-01-05_Receipt_Amazon_Order-123.pdf`

### Key Rules

1. **Date Format**: Always use `YYYY-MM-DD` at the beginning (sorts chronologically)
2. **Separator**: Use underscores `_` instead of spaces
3. **Lowercase**: Use lowercase for consistency
4. **Version**: Use `v1`, `v2` instead of "final", "final2", "REALLY_FINAL"
5. **No Special Characters**: Avoid `/`, `:`, `*`, `?`, `"`, `<`, `>`, `|`

## Metadata Files

### Benefits
- **Preserve Dates**: Store original creation dates if lost during transfer
- **Search Enhancement**: Add searchable tags and descriptions
- **Context**: Add project info, people, locations
- **Backup**: Extra copy of important metadata

### Drawbacks
- **Extra Files**: Doubles file count
- **Maintenance**: Can become stale/out of sync
- **Tool Support**: Not all apps understand sidecar files
- **Clutter**: May feel unnecessary for simple files

### Recommendation
Use metadata files for:
- Photos (to preserve EXIF data)
- Important documents (contracts, legal)
- Files that have been transferred between systems

For routine files, skip metadata to avoid clutter.

## De-duplication Strategy

### Approach
1. **Group by Size**: Files with unique sizes cannot be duplicates
2. **Quick Hash**: Use xxHash/MD5 for fast comparison
3. **Full Hash**: SHA-256 for final verification
4. **Preserve Original**: Keep oldest or most descriptive filename

### Hash Algorithms
- **xxHash**: Very fast, good for first pass (blake2b also excellent)
- **SHA-256**: Slower but cryptographic certainty
- **Combined**: Fast pre-filter + slow final check

From ihandley/opencode-config, MIT.

More from ihandley/opencode-config