file-organizer

name	file-organizer
description	Scan messy local folders and output a simple metadata inventory for non-technical users. Use when users want to understand what files they have without moving or renaming anything. Exports a CSV and terminal preview with only source_path, source, type, and date.

File Organizer

Use this skill to inspect files safely without mutating files.

Follow this workflow

1. Scan the input directory recursively.
2. Exclude noisy folders (.git, node_modules, Library, and user-provided excludes).
3. Parse each file with metadata-first rules:
   • date priority: filename date pattern -> mtime -> ctime
   • source priority: parent directory name -> filename prefix rules -> Unknown
   • type: extension uppercase without dot (for example PDF, JPG, PY)
4. Output only these fields:
   • source_path
   • source
   • type
   • date
5. Generate organization-report.csv in the output directory.

Use the CLI

python3 scripts/organize_files.py \
  --input /path/to/folder \
  --output /path/to/report-dir

Key options

• --exclude ".git,node_modules,Library"
• --preview-limit 20

Safety rules

• Do not move, rename, copy, or delete files.
• Keep this skill scan-only.