file-organizer

Overview

Analyzes the contents of a specified folder, examining file names, types, dates, and optionally content, then proposes an organized folder structure with consistent naming. Presents a full reorganization plan for user approval before touching any files. Never moves, renames, or deletes files without explicit confirmation.

Workflow

<Definition - Organization Strategy> How to group files into folders:

• date: Group by creation/modification date (year/month or year/quarter)
• type: Group by file extension category (documents, images, spreadsheets, code, media, archives)
• project: Group by inferred project association (from naming patterns or content)
• topic: Group by content topic (requires reading file headers/content)
• auto-detect: Analyze existing patterns and pick the most natural grouping </Definition - Organization Strategy>

<Definition - Naming Conventions>

• kebab-case: lowercase-words-separated-by-hyphens.ext
• snake_case: lowercase_words_separated_by_underscores.ext
• PascalCase: EachWordCapitalized.ext
• camelCase: firstWordLowerThenCapitalized.ext
• date-prefix: YYYY-MM-DD_descriptive-name.ext
• original: keep existing filenames, only reorganize into folders
• other: user-defined custom pattern (collected during preferences step) </Definition - Naming Conventions>

<Definition - Reorganization Plan> A table mapping every file from its current location to its proposed new location, including the action type (move, rename, move+rename, unchanged). Must include a summary count and a rollback reference. </Definition - Reorganization Plan>

<Workflow - Setup Preferences description="Collect and save the user's file organization preferences to memory." tools=[recall_memories, save_to_memory] triggers=["set up file organization preferences", "change my file organization settings", "update my organization preferences"]

1. [Agent] Recall existing file organization preferences from memory. Query: "file organization preferences, max folder depth, collision strategy, scan threshold". [Decide] Are existing preferences found?
   • Yes -> [Ask user] "Here are your current preferences:
     • Max folder depth: [value]
     • Collision strategy: [value]
     • Large folder scan threshold: [value]
     • Default naming convention: [value] Want to update any of these?"
   • None found -> proceed to step 2.
2. [Ask user] Collect preferences:
   • "Max folder depth? (how many levels of nesting, e.g. 3)"
   • "Collision strategy? When two files would get the same name: numeric suffix (_01, _02), parenthetical suffix ((1), (2)), or ask each time?"
   • "Large folder threshold? Above how many files should I sample for content analysis instead of reading all? (e.g. 200)"
   • "Default naming convention? (kebab-case, snake_case, PascalCase, camelCase, date-prefix, original, or describe your own)" Validate: User provides at least max depth and collision strategy. If fails: Use sensible defaults (depth: 3, collision: numeric suffix, threshold: 200, naming: kebab-case) and confirm with user.
3. [Agent] Save all preferences to memory with hint: "file organization preferences for file-organizer skill". Validate: save_to_memory confirms signal recorded. If fails: Report the error and present preferences in chat so user has a record.

</Workflow - Setup Preferences>

<Workflow - Organize description="Scan a folder, analyze content, propose and execute a reorganization plan using saved preferences." tools=[get_current_time, recall_memories, save_to_memory, folder_list, file_read, file_read_pdf, file_read_docx, file_read_pptx, file_move, file_copy, file_write, folder_create, open_in_session_tab, run_python] triggers=["organize this folder", "clean up my files", "sort these documents", "rename my files", "folder structure suggestions", "tidy up this directory"]

1. [Agent] Recall the user's file organization preferences from memory. [Decide] Are preferences found?
   • Yes -> apply as defaults for this run.
   • No -> [Ask user] "I don't have your organization preferences saved. Would you like to set them up now (recommended for future runs) or just tell me what you want for this one-time run?"
     • Set up -> execute <Workflow - Setup Preferences>, then return here.
     • One-time -> collect minimal preferences inline (depth, collision, naming) and proceed without saving.
2. [Agent] Validate {{folder_path}} exists and is within allowed folders using folder_list. Validate: Folder exists, contains at least one file, access is permitted. If fails: [Ask user] "That folder doesn't exist or isn't in your allowed folders. Please provide a valid path."
3. [Agent] Scan folder contents with folder_list. For each file, capture: name, extension, size, last modified date. [Decide] File count > 500?
   • Yes -> use run_python with os.listdir for full listing. [Decide] File count > user's scan threshold preference?
   • Yes -> sample files for content analysis in step 4. Note the sampling in output.
   • No -> analyze all files in step 4. Validate: Complete file inventory captured. If fails: Report the error and ask user if they want to proceed with a partial listing.
4. [Think] Determine organization strategy. [Decide] Is {{organization_strategy}} set to "auto-detect"?
   • Yes -> Analyze file type distribution, naming patterns, content themes (read first 500 chars of text-based files), date clustering, existing partial organization. Select the most natural grouping axis.
   • No -> use the user's specified strategy directly. [Decide] Is {{naming_convention}} set to "other"?
   • Yes -> [Ask user] "Describe your custom naming pattern (e.g., 'YYYY-MM-DD_project_description')."
   • No -> proceed with the selected convention. Validate: A clear strategy and naming convention are determined. If fails: Default to organizing by file type with user's preferred naming convention.
5. [Agent] Generate the reorganization plan using run_python. For every file, compute:
   • Target folder (based on strategy)
   • Target filename (based on naming convention, preserving extension)
   • Action type: move, rename, move+rename, or unchanged
   • Collision check: resolve using user's collision preference. Format as a markdown table: | # | Current Path | Target Path | Action | Notes | Include summary: files to move, rename, new folders to create, unchanged, collisions resolved, skipped items. Validate: Every file accounted for. No unresolved collisions. No target paths outside allowed folders. If fails: Regenerate with a simpler structure.
6. [Ask user] Present the full reorganization plan with summary. Ask: "Do you want me to: A) Execute the full plan as shown B) Execute with modifications (tell me what to change) C) Only rename files (no moves) D) Only reorganize into folders (no renames) E) Cancel and save the plan as a reference only" Validate: User explicitly approves with A, B, C, or D. If fails (user picks E or says no): Save plan to artifacts/file-organization-plan-[date].md, open in session tab, stop.
7. [Agent] Execute the approved plan:
   1. Create new folders with folder_create.
   2. Move/rename files with file_move (one at a time).
   3. Log each result. [Decide] Did any operation fail?
   • Yes -> Stop. Report what completed and what remains. [Ask user] "Continue with remaining files or stop here?"
   • No -> proceed to step 8. Validate: All approved operations completed successfully.
8. [Agent] Generate summary report, save to artifacts/file-organization-report-[date].md. Include:
   • Results count (moved, renamed, folders created, errors)
   • Final folder structure (tree view)
   • Full changes log
   • Rollback instructions (reverse mapping) Open report in session tab. [Decide] Did the user override any preferences during this run?
   • Yes -> [Agent] Save updated preferences to memory. Validate: Report is accurate and rollback reference is complete. If fails: Output summary directly in chat.

</Workflow - Organize>