File Organizer

Scan, deduplicate, and organize files in a directory by type, generating a dry-run plan before optionally moving files without deleting anything.

Security Scan

The skill's code and instructions match its stated purpose (scanning, deduplicating, and moving files) and request no credentials or external installs; exercise normal caution because running with --execute will move files.

Purpose & Capability

Name/description align with included scripts. All required actions (scanning, hashing, duplicate detection, planning, moving, manifest generation) are implemented locally; no unrelated credentials, binaries, or network endpoints are requested.

Instruction Scope

SKILL.md instructs the agent to scan local directories and run included Python scripts — exactly the expected scope. The scripts can move (not delete) files when run with --execute; dry-run is the default. Be aware that an agent or user could explicitly pass --execute --yes to perform moves without an interactive prompt.

Install Mechanism

No install spec or external downloads; this is an instruction-only skill with bundled Python scripts. Nothing is pulled from remote URLs or package registries.

Credentials

The skill requests no environment variables, credentials, or config paths. All file and path access is limited to directories the user supplies to the scripts.

Persistence & Privilege

The skill is not always-enabled and does not modify other skills or global agent settings. It can be invoked autonomously (platform default), but it does not request elevated persistence or special privileges.

Assessment

This skill appears coherent and implements the described functionality locally. Before running any execution step that moves files: 1) Always run the dry-run (default) and inspect the generated plan/plan.json; 2) Do not run with --execute --yes until you have reviewed the plan — the --yes flag skips confirmation and will let the script move files; 3) Consider running scans against a small test directory first to confirm behavior; 4) Make a backup (or ensure files are in a recoverable state) if you plan to move large or important collections; 5) If you need different category mappings, review or edit references/categories.md before executing. If you want extra assurance, manually review the bundled scripts (they are included) — they perform local filesystem operations only and do not contact external services.

Scans a target directory, categorizes files by type, finds duplicates, and generates (or executes) a cleanup plan. Dry-run by default — always shows what will happen before doing it.

Scripts

All scripts live in scripts/. Run with python3. No third-party dependencies.

Script	Purpose
scan.py	Walk a directory, output JSON inventory
find_duplicates.py	Find duplicate files by content hash
organize.py	Generate and optionally execute a move plan
manifest.py	Produce a markdown before/after manifest

Category mappings (extension → folder) are in references/categories.md. Read it if asked about supported file types or to customize mappings.

Typical Workflow

1. Scan the directory

python3 scripts/scan.py ~/Downloads --output /tmp/scan.json

Add --hash to pre-compute hashes (needed for duplicate detection without a separate pass).

2. Find duplicates (optional)

python3 scripts/find_duplicates.py /tmp/scan.json --output /tmp/dupes.json

Or scan and deduplicate in one step:

python3 scripts/find_duplicates.py --directory ~/Downloads

3. Generate organization plan (dry run)

python3 scripts/organize.py /tmp/scan.json --output /tmp/plan.json

Or scan + plan in one step:

python3 scripts/organize.py --directory ~/Downloads

Key flags:

• --dest ~/Downloads/Organized — custom destination (default: <dir>/Organized/)
• --flat — don't preserve subdirectory structure
• --dry-run — default, shows plan without moving anything
• --execute — actually move files (prompts for confirmation)
• --execute --yes — skip confirmation prompt

4. Execute the plan

python3 scripts/organize.py /tmp/scan.json --execute
# or skip the prompt:
python3 scripts/organize.py /tmp/scan.json --execute --yes

5. Generate manifest

# From plan JSON
python3 scripts/manifest.py --plan /tmp/plan.json --output /tmp/manifest.md

# Before/after comparison (run scan.py twice)
python3 scripts/manifest.py --before /tmp/before.json --after /tmp/after.json --output /tmp/diff.md

# Simple inventory
python3 scripts/manifest.py --scan /tmp/scan.json --output /tmp/inventory.md

Safety Rules

• organize.py never deletes files — only moves them
• Dry-run is the default; --execute must be explicit
• Symlinks are skipped (never moved)
• Destination conflicts are flagged in the plan and skipped during execution (unless --yes)
• Hidden files/dirs (.dotfiles) are skipped by default; use --include-hidden to include them

Common Scenarios

"Clean up my Downloads folder" → Run scan + organize dry-run, show the plan summary, ask user to confirm before executing.

"Find duplicate files in my Desktop" → Run find_duplicates.py --directory ~/Desktop, report groups sorted by wasted space.

"Organize my files and save a report" → Run scan → organize (dry-run) → confirm → organize (execute) → manifest to markdown.

"What file types are supported?" → Read references/categories.md and summarize the category mappings.

Output Locations

Default destination for organized files: <target_dir>/Organized/ Subfolders are created per category: Images/, Documents/, Videos/, etc. Files with unrecognized extensions go to Other/.