Agent-Skills.md

Agent Skills: File Organizer

Use when files are scattered across directories, Downloads is cluttered, duplicates are wasting space, folder structure has grown chaotic, or a directory needs cleanup before archiving or migrating to a new machine.

UncategorizedID: marcusrbrown/.dotfiles/file-organizer

Repository

marcusrbrown/.dotfiles
marcusrbrown
20

Install this agent skill to your local

pnpm dlx add-skill https://github.com/marcusrbrown/.dotfiles/tree/HEAD/.config/opencode/skills/file-organizer

Skill Files

Browse the full folder contents for file-organizer.

Download Skill

Loading file tree…

.config/opencode/skills/file-organizer/SKILL.md

Skill Metadata

Name
file-organizer
Description
Use when files are scattered across directories, Downloads is cluttered, duplicates are wasting space, folder structure has grown chaotic, or a directory needs cleanup before archiving or migrating to a new machine.

File Organizer

Overview

Systematic file organization for macOS and Linux. Analyze → categorize → plan → confirm → execute → verify. Every destructive operation requires explicit user approval.

First step: Detect the platform (uname -s) and use the matching command variants from commands-reference.md. If a required tool is missing, stop and explain — never guess.

When to Use

  • Downloads folder overflowing with months/years of unsorted files
  • Can't find files because they're scattered across directories
  • Duplicate files wasting disk space
  • Folder structure grown organically and no longer makes sense
  • Preparing to archive old projects or migrate machines
  • Setting up organization for a new directory

When NOT to use:

  • Git repository internals (use git tools instead)
  • Application data directories (~/Library/ on macOS, ~/.local/share/ on Linux)
  • Cloud-synced directories you don't own (shared team drives)

Quick Reference

| Phase | Action | Key Rule | |-------|--------|----------| | Scope | Ask: which directory, what problem, what to avoid, how aggressive | Never assume — always confirm scope | | Detect | Run uname -s to determine macOS vs Linux | Use matching command variants from reference | | Analyze | Survey file types, sizes, dates using safe read-only commands | See commands-reference.md for platform-specific commands | | Categorize | Group by type, purpose, or date | Match user's mental model, not yours | | Plan | Present tree diagram + change list + "needs decision" bucket | User must approve before any changes | | Execute | mkdir -p then mv with logging | One category at a time; stop on conflicts | | Verify | Show before/after summary + maintenance tips | Confirm nothing was lost |

Safety Rules (NON-NEGOTIABLE)

  1. Always confirm before any mv, rm, or rename operation
  2. Never delete without asking — prefer archiving over deletion
  3. Exclude dangerous paths: .git/, .dotfiles/, node_modules/, bare repo metadata
  4. Stay on the filesystem — use find -x (macOS) or find -xdev (Linux) to prevent scanning mounted volumes, network shares, or backup trees
  5. Quote all paths — spaces, special chars, and option-like names break unquoted commands
  6. Warn about cloud storage — on macOS, file/md5/cat can trigger downloads of iCloud-evicted files. Check for dataless stubs first.
  7. Preserve timestamps — use mv (preserves by default) or cp -p when copying
  8. Log all moves — maintain a record so operations can be reversed
  9. Handle dotfiles explicitly — du * and ls * skip hidden files; find includes them. Be consistent.
  10. Never touch bare git repos — ~/.dotfiles and similar GIT_DIR setups look like junk but are critical infrastructure

Common Mistakes

| Mistake | Fix | |---------|-----| | Using GNU-only find -printf on macOS | BSD find has no -printf. Use stat or -exec basename. See commands-reference.md | | Scanning without filesystem boundary flag | Accidentally includes mounted volumes and backups. Always use -x (macOS) or -xdev (Linux) | | Wrong md5/md5sum pipeline for dedup | macOS uses md5 -r, Linux uses md5sum. Output format differs — see reference for correct awk pipeline | | Deleting "duplicates" that are hardlinks | Check inodes first — see hardlink check in reference | | Running du -sh * for size survey | Misses hidden directories. Use du -shx .[!.]* * or explicit find | | Organizing inside app data dirs | ~/Library/ (macOS) and ~/.local/share/ (Linux) — reorganizing breaks apps | | Moving cloud-synced files without warning | Triggers re-sync; can delete across devices if not careful |

Reference Files

  • commands-reference.md — platform-aware commands for analysis, duplicate detection, and organization. Shows macOS/Linux variants where they differ, portable commands where they don't.