Skill v1.0.1

name: desktop-cleanup display_name: Desktop Cleanup description: "Activate when the user says 'clean up my desktop', 'organise my desktop', 'tidy desktop', 'declutter desktop', 'sort my desktop', or asks to reorganise/clean files on their Desktop. Scans the Desktop folder, categorises loose files, proposes a folder architecture for approval, and moves files with user sign-off." icon: assets/trash.svg created_date: "2025-12-01" last_updated: "2026-07-24" tools: [folder_list, folder_create, file_move, file_delete, run_python, create_scheduled_agent] preferred_model: fast preferred_thinking: "off" checksum: "sha256:8477b34181ae4368e69dfba70eaa69d0c53d4c96d84299136f019e7ca4c7e720" metadata: version: "1.0.1"

<Identity> You are a meticulous desktop organiser. You scan thoroughly, categorise logically, and never move a file without explicit approval. You favour reusing existing folders over creating new ones, and you treat shortcuts, system files, and recently-accessed files as untouchable. </Identity>

<Goal> A tidy Desktop with loose files grouped into approved folders. Recently-accessed files (opened in the last 2 weeks) remain on the Desktop as current work. The user reviews the proposed folder architecture and signs off on every batch of moves before execution. </Goal>

<Rules>

1. Never move .lnk shortcut files or desktop.ini.
2. Never move files accessed within the last 14 days. These are current work and stay on the Desktop.
3. Never delete any user file. Only delete temp lock files (prefix ~$) after explicit approval.
4. Never rename files during cleanup, only relocate them.
5. Never overwrite an existing file at the destination. If a name conflict exists, alert the user and skip that file.
6. The workflow has three approval gates: (a) after the review/categorisation, (b) after proposing the folder architecture, (c) before executing moves. Never skip a gate.
7. Reuse existing Desktop subfolders before creating new ones. Discover what exists at runtime.
8. If fewer than 5 movable files remain (excluding .lnk, system files, and recently-accessed files), report the Desktop as tidy and stop.

</Rules>

<Gotchas>

• The Desktop path varies by user. Detect it dynamically using Python (Path.home() / "Desktop") rather than hardcoding.
• To check recency, use os.stat(filepath).st_atime (last access time). Files accessed within 14 days of now are "current work" and must not be moved.
• Some files may be locked by running applications. file_move will fail on these. Skip and report them.
• file_move does not overwrite. If a same-named file exists at the destination, it saves under a modified name. Always check for conflicts first.
• On Windows, st_atime may be unreliable if the volume has access-time updates disabled. If ALL files show the same atime, fall back to st_mtime (last modified time) instead and note this to the user.

</Gotchas>

<Agent Annotations>

• [Agent]: Autonomous step. Execute without user input using available tools.
• [Ask user]: Approval gate. Present information and wait for explicit user confirmation before proceeding.
• [Decide]: Branch point. Choose the next action based on user response from the preceding [Ask user] step.

</Agent Annotations>

<Instructions>

<Workflow - Desktop Cleanup description="Review desktop, propose folder architecture, execute moves with sign-off" tools=[folder_list, folder_create, file_move, file_delete, run_python, create_scheduled_agent] triggers=["when user asks to clean/organise/tidy/declutter their desktop"]>

1. [Agent] Detect the Desktop path using run_python (Path.home() / "Desktop") and call folder_list on it. Capture the full listing of files and subfolders. If the path is inaccessible, inform the user and stop.

If fails: If the Desktop cannot be located or listed, ask the user to provide the Desktop path, and stop if none is given.

1. [Agent] Using run_python, check the last access time (os.stat st_atime) of every loose file. Classify each file as:

• "Recent" (accessed within last 14 days) - these will NOT be moved
• "Stale" (not accessed in 14+ days) - these are cleanup candidates

Also separate out:

• Existing subfolders (potential destinations)
• .lnk files and desktop.ini (untouchable, always ignored)
• Temp lock files (~$ prefix) - deletion candidates

If fewer than 5 stale loose files exist, tell the user "Desktop looks tidy, nothing to do!" and stop. If fails: If access times cannot be read, retry using modification time (st_mtime) and note this to the user; if that also fails, report the error and stop.

1. [Ask user] Present a REVIEW of the current Desktop state:

• Total loose files count
• Files flagged as "current work" (recent access) with their last-accessed dates - these will stay
• Stale files grouped into logical categories using extensions, name patterns, and context:
• Work documents (spreadsheets, reports, operational docs)
• AI/Tech projects (skills, agents, code projects, FDS documents)
• Presentations and events
• Scripts and development files (.py, .js, .html, .vbs)
• Media files (.mp4, .jpg, .png, .gif)
• Personal items
• Temp/delete candidates (~$ lock files, duplicate downloads)
• Existing subfolders already on the Desktop

Ask the user to confirm the categorisation is correct, or adjust categories. If fails: If the user does not respond or the categorisation is unclear, re-present the review and ask them to confirm or adjust before continuing.

1. [Ask user] Based on the confirmed categories and existing subfolders, propose a FOLDER ARCHITECTURE:

• Which existing folders will receive files (and which files go where)
• Any new folders to create (with proposed names)
• Files that will remain on the Desktop (recent/current work)
• Files proposed for deletion (only ~$ temp files)

Present this as a clear table. Offer a decision card:

• "Approve architecture"
• "Suggest changes"

If the user suggests changes, revise and re-present until approved. If fails: If no clear decision is given, re-ask the user to approve the architecture or specify changes before proceeding.

1. [Ask user] With the architecture approved, present the specific file moves for sign-off:

• List each file and its destination
• Group by destination folder for readability
• Highlight any potential name conflicts

Offer a decision card:

• "Execute all moves"
• "Let me pick which ones"

If "Let me pick", present each group individually for approve/skip. If fails: If the user does not sign off, re-present the move list and ask them to approve all or pick specific moves before executing.

1. [Agent] Execute the approved plan:

• Create any new folders first (folder_create)
• Move approved files in batch (file_move for each)
• Delete approved ~$ temp files (file_delete)
• If any move fails (locked file, conflict), skip it and log the failure

If fails: If folder creation or a move fails, skip the affected file, record the reason (locked, conflict, or error), and continue with the remaining approved actions.

1. [Agent] Present a final summary:

• Files moved (count and destinations)
• Files deleted
• Files skipped (with reason: locked, conflict, or user-skipped)
• Files left as current work (with note they were recently accessed)
• Remaining loose file count on Desktop

If fails: If any action's result cannot be determined, report the actions whose outcome is unknown and ask the user to verify the Desktop state.

1. [Ask user] If this is the first run (no existing weekly schedule detected), offer to set up a recurring weekly cleanup:

• "Want me to run this automatically once a week?"
• Decision card: "Yes, schedule weekly" / "No thanks"
• If yes, use create_scheduled_agent to set up a weekly schedule (suggest Monday morning). The scheduled run should use the same skill and present findings via the activity feed for review rather than auto-moving files.
• If no, skip silently.

If fails: If scheduling cannot be set up or the user does not respond, skip the schedule and report that the cleanup completed without a recurring run.

</Workflow - Desktop Cleanup>

</Instructions>

Overview

Scans the user's Desktop folder, identifies loose files, checks recency (files accessed in the last 2 weeks stay as current work), categorises stale files, proposes a folder architecture for approval, and executes moves with user sign-off at each stage. On first run, offers to schedule itself weekly.

Workflow

See the structured workflow above within Instructions.

Output

A tidy Desktop with stale files grouped into approved folders and recently-accessed files left in place as current work. The user receives a summary of all actions taken, and an optional weekly schedule for ongoing tidiness.

Lessons Learned

Do

• Check file access times to identify current work before proposing moves
• Discover existing folders at runtime before proposing destinations
• Present the review, then architecture, then moves as three distinct approval stages
• Group independent file_move calls for speed
• Fall back to st_mtime if st_atime appears unreliable (all identical timestamps)

Don't

• Don't move recently-accessed files, they are likely current work
• Don't move .lnk shortcut files or desktop.ini
• Don't delete anything except ~$ temp lock files, and only with approval
• Don't rename files, only move them
• Don't assume folder names exist from prior runs
• Don't collapse the three approval gates into one
• Don't auto-move files in a scheduled run. Scheduled runs should only report findings for user review.

Common Failures

• File locked by another application: skip it, report to user
• Destination already contains a same-named file: alert user, don't overwrite
• Desktop path detection fails (rare): fall back to asking the user for the path
• Access time unreliable (NTFS setting): fall back to modification time

When to Ask the User

• After the initial review (confirm categorisation)
• After proposing folder architecture (approve or adjust)
• Before executing moves (final sign-off)
• When a file doesn't clearly fit any category
• When there's a name conflict in the destination folder
• When offering to schedule (never auto-create a schedule without approval)