SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsdisk-cleaner

disk-cleaner

General & other

View repository

Updated 10-16 09:52

About this skill

disk-cleaner

macOS / Windows disk cleanup expert. Combines Mole's path-validation safety model, khazix's interactive HTML report, and our own deep knowledge base.

Iron rules

  • The entire scan is read-only. Only scanning/statistics/listing directories/reading metadata may be run. Absolutely forbidden: rm, mv, rmdir, and other write operations.
  • Deletion is performed only through server.py. The cleanup commands in the report are for the user to run after confirmation, either via one-click operation on the web page or manually in the terminal. Even if the user says "help me delete" in the conversation, stop first and confirm.
  • The sandbox container path = the user's real directory. macOS ~/Library/Containers/<app>/Data/Downloads/ maps to ~/Downloads/, so deleting it means deleting user files. See references/macos.md。
  • Path safety. All paths must be wrapped in quotes, previewed with a dry-run before execution, and dangerous operations must be confirmed twice.

Execution flow

Step 1 Scan (read-only)

python3 scripts/scan.py > /tmp/storage_scan.json

scan.py Automatically detects the system (sys.platform）：

  • macOS: scans home, library, caches, containers, app_support, applications, downloads, dev_caches, as well as 20+ app-specific paths including WeChat, Feishu, QQ, DingTalk, Telegram, Teams, Discord, Chrome, Safari, VS Code, Xcode, Steam, etc. Use du to calculate size.
  • Windows: scans user_profile, appdata_local, appdata_roaming, temp, downloads, program_files, dev_caches, as well as WeChat, DingTalk, Feishu, Discord, Teams, Chrome, Edge, etc. Use os.scandir to calculate size.

Output JSON:system(system/disk information) + groups(general scan groups) + app_groups(app-specific scans) + large_files(large files >500MB). The scan is slow, wait patiently. Directories that cannot be read are marked denied。

Step 2 Analysis and classification

First look at system.os to determine the system, then read the corresponding reference: for macOS read references/macos.md, for Windows read references/windows.md. Then read /tmp/storage_scan.json for classification:

  1. Pick the Top 5 largest consumers and determine their type.
  2. Identify "mysterious large directories": Containers named with UUIDs, trace which App they belong to.
  3. Three-level classification:
    • 🟢 Can be cleaned automatically: pure caches, temporary files, regenerable. Each 🟢 item must be given trash_paths(an array of specific absolute paths that can be deleted), estimated space to be freed, processes that need to be closed, and cleanup commands.
    • 🟡 Requires manual judgment: contains user data. Provide a content profile + handling path + risk warning. When there are safe subpaths, provide trash_paths(only move to Trash, not permanent delete). For App-managed items with no safe subpaths, provide only an open button.
    • 🔴 Clean with caution: items that are best not deleted manually (duplicate applications, large applications you want to uninstall). Provide uninstall steps + app_paths. Red-light items are not given a delete button.
  4. Write size fields cleanly: just use "about 14 GB"; do not add "(estimated)".

Step 3 Generate interactive report

Write the analysis results as analysis JSON (see schema in scripts/build_report.py top comment).

By default, use server mode (server.py) to open the report：

python3 scripts/server.py /tmp/storage_analysis.json   # 自动开浏览器，Ctrl+C 停

server.py starting at 127.0.0.1 + random port + random token. Security model: three whitelists (RM_ALLOW / TRASH_ALLOW / OPEN_ALLOW) + path validation (from Mole) + audit log + Host verification. 🟢 items get "Move to Trash" + "Delete directly"; 🟡 items get "Open in Finder" + (when there is a safe subpath) "Move to Trash"; 🔴 items get "Open in Finder (go uninstall)".

Only when the user wants just a shareable read-only file, use static mode:

python3 scripts/build_report.py /tmp/storage_analysis.json ~/Desktop/storage-report.html && open ~/Desktop/storage-report.html

Troubleshooting: no delete button on the web page = either a static report is open (switch to server.py), or a 🟢 item is missing trash_paths。

Report reading flow: disk overview card → Top5 → action recommendations → 🟢🟡🔴 three-level collapsible cards → long-term optimization suggestions.

Give a summary in the Step 4 conversation

After the report is generated, give a conclusion-first summary in the conversation in one paragraph: total reclaimable estimate, the 2-3 items that should be cleaned first, and the highest-risk item. Let the user see the details on the web page.

Dependencies and runtime prerequisites

  • All scripts are Python 3 standard library, with zero third-party dependencies.
  • macOS comes with python3,du、diskutil、osascript, ready to use out of the box.
  • Windows requires installing Python 3 first; the command is usually python or py -3. The command examples in this skill are written as python3, and on Windows it automatically switches to python / py -3。
  • This skill is agent-driven: after the data is scanned, the agent (Claude) performs the tiered analysis.

Platform status

  • macOS: fully implemented (scan / report / one-click delete all verified).
  • Windows: the code is written butnot tested on real Windows。