Storage Analyzer

Perform a read-only storage analysis on macOS and generate an interactive HTML report. Process: Scan → Analyze and categorize → Generate webpage → Open.

Iron Rules

Read-only throughout. Only run scanning/statistics/directory listing/metadata reading (df, du, diskutil, stat, ls). Strictly prohibit any write operations such as rm, mv, rmdir, emptying the recycle bin, changing permissions, etc.
Only display deletion commands, do not execute them. The cleanup commands provided in the report are for users to run in the terminal after confirmation. Even if the user says "help me delete" in the conversation, stop to confirm first (hit global red line: must ask before deleting files), do not run the command directly.
Clearly mark estimates. Always indicate that "releasable space" is an estimated value.
Keep paths and commands in original language without translation.

Execution Process

Step 1 Scan (Read-only)

bash

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

scan.py

automatically detects the system (

sys.platform

macOS: Scans home, library, caches, containers, group_containers, app_support, applications, downloads, dev_caches, calculates sizes using
```
du
```
.
Windows: Scans user_profile, appdata_local, appdata_roaming, temp, downloads, program_files(_x86), dev_caches, calculates sizes using
```
os.scandir
```
;
```
system.disks
```
includes all drive letters.

Output JSON:

system

(system/disk information, including

disk_name

main disk name +

disks

all disks) +

groups

(subdirectory sizes of each group, sorted in descending order, filtered to exclude items below 50MB). Scanning is slow, please be patient. Directories that cannot be read are marked

denied

, and the missed volume should be listed in the report with a prompt.

Step 2 Analysis and Categorization

First, determine the system using

system.os

, and read the corresponding data layout reference: for macOS, read references/macos.md, for Windows, read references/windows.md (explains where things are stored in the system, how to identify them, and which category they belong to). Then read

/tmp/storage_scan.json

to do the following:

Select Top 5 space hogs, determine their types (system assets, application installations, application data, application caches, development caches, user files, media content, downloaded content, virtual machine images, recycle bin, others).
Identify "mysterious large directories": UUID-named Containers, unknown hidden directories. Trace which App they belong to and what they contain (e.g., a 97GB UUID Container is actually Bilibili offline video cache). If necessary, use
```
ls
```
/
```
du
```
to look one level deeper, but remain read-only.
Three-level classification = cleanup decision list, not a full inventory. Only include items that require a "should I move it" decision in the three-color categories. Regular daily applications, the operating system itself, and massive small files without cleanup decisions are not included in the three-color categories; they fall into the blue "System and Others" section of the disk bar. Judgment criteria:
- 🟢 Auto-cleanable: Pure cache, temporary files, installation package residues, clearly regenerable without affecting functionality or losing user data (development caches like pip/uv/npm/Xcode DerivedData, browser caches).
- 🟡 Manual judgment required: Contains user data or requires judgment (offline videos, documents, project code node_modules, chat records, design drafts). Provide content profiling + at least 3 disposal paths (in-app cleanup / system tools / manual review via file manager, choose the most suitable three) + risk warnings. All yellow items automatically have an "Open in Finder/File Explorer" button in service mode (jump to review and delete manually); if the item has a verified safe subpath that can be deleted without damaging the App (e.g.,
```
.Downloads
```
  directory for Bilibili offline videos, old backup directories), assign it
```
trash_paths
```
  → a "Move to Trash" button appears on the webpage (yellow items can only be moved to trash, reversible, never allow "direct deletion"). Apps hosted without safe subpaths (Chrome/WeChat) only provide an open button, no
```
trash_paths
```
  . Notes are automatically displayed below the buttons (open only for viewing not deletion, moving to trash is reversible and requires emptying to release space, etc.); if an item is in an App-internal format that is inconvenient to manually select in the file manager, add an
```
open_note
```
  field for objective explanation (will be displayed in the notes). Tone should be neutral, like product instructions: Directly describe "what structure this is, why it's not easy to delete manually, where to go for fine-grained operations", do not write from a developer's perspective like "I found/remind you/it looks like no videos".
- 🔴 Clean with caution (decision needed but not recommended to delete manually): Specific items you might want to move but are advised not to delete manually—duplicate applications, large apps you want to uninstall, core data of running apps, etc. Provide "why manual deletion is not recommended" +
```
indirect_release
```
  with specific uninstall steps (built-in uninstaller / long press in Launchpad / right-click to move to trash / AppCleaner to clear residues / reinstall via App Store, etc., must be actionable not empty words). For app items, assign
```
app_paths
```
  (array of real
```
.app
```
  absolute paths) → an "Open in File Manager (to uninstall)" button appears on the webpage, locating the App for users to uninstall formally. Red items do not have delete/uninstall buttons (apps are in system directories, may require administrator password, may have built-in uninstallers and residues, background deletion is unstable). Pure system files, APFS snapshots should not be listed separately as red cards (no cleanup decision), they belong to the blue section; system-level release techniques (restart to release swap, Time Machine snapshot strategy, automatic recovery of freeable space) are written into
```
summary.long_term
```
  long-term suggestions.

Each 🟢 item must include: estimated releasable space, processes to close before cleanup, one-click copyable cleanup commands (use safe methods like moving to trash or App's own cleanup entry, use

rm

cautiously; if using

rm

, it must be a clear cache subdirectory).

Keep size fields clean:

size

size_estimate

should be written as "~14 GB" "total ~~8.6 GB"—the "~~" already indicates an estimate, do not add "(estimated)" which is redundant and unprofessional (the template will automatically remove such redundant parentheses). The regenerable attribute is covered by the category title and button descriptions, do not include it in the size field.

Step 3 Generate Interactive Report

Write the analysis results into an analysis JSON (schema see top comments of

scripts/build_report.py

🟢 items must include
trash_paths
(array of specific deletable absolute paths, different from the human-readable

path

display field)—this is the prerequisite for the webpage delete button; if missing, the button will not appear.

By default, open the report in one-click delete mode (
server.py
), because the core value of this skill is direct cleanup via the webpage:

bash

python3 scripts/server.py /tmp/storage_analysis.json   # Automatically opens browser, Ctrl+C to stop

server.py

runs on 127.0.0.1 + random port + random token. 🟢 items have "Move to Trash" (reversible) + "Delete Immediately" (immediate release, irreversible); 🟡 items have "Open in Finder" + (if there is a safe subpath) "Move to Trash". Security model—three sets of whitelists, permissions from strict to loose:

rm

only allows green

trash_paths

;

trash

allows green + yellow

trash_paths

(yellow items can never use rm);

open

(open in file manager, non-destructive) allows all of the above + yellow real

path

. All requests are validated with realpath + must be within $HOME + token + Host validation, and the browser confirms before each click. osascript/SHFileOperationW is used to move to trash; for macOS, allow the first Finder automation authorization prompt.

Only when the user explicitly wants a shareable/savable read-only file, use static mode (no delete buttons, because pages opened via

file://

cannot access the file system):

bash

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

Troubleshooting: No delete/move to trash buttons on the webpage = either the static report is opened (switch to

server.py

), or

trash_paths

is missing for 🟢 items (add it and restart the service).

Report reading flow (fixed order): Disk overview card (capacity + progress bar + three-color capacity pills + system information, pure data) → Top5 space usage ranking → Execution suggestions → 🟢🟡🔴 collapsible three-level cards (one-click copy commands) → Long-term optimization suggestions. That is "Current Status → Diagnosis → Prescription → Operation → Prevention".

Note that

summary.overview

should be written as a one-sentence insight (directly state what the largest space usage is and how much can be released), do not repeat total/used/available numbers—those are already displayed in the large numbers of the card. The overview is rendered as an introduction in plain text at the beginning of the "Execution Suggestions" section, followed by the

summary.priority

priority list.

The disk progress bar splits "used" into segments: green (auto-cleanable) + orange (manual required) + red (identified items not recommended to move) + blue (system and others, automatically calculated as used - green - orange - red), with the remaining space as available (gray background). The green / yellow / red values in

summary.tier_stats

must start with parsable GB numbers (e.g., "~27.8 GB"), and the script extracts numbers from them to calculate segments; the blue segment and "System and Others" pill are automatically calculated by the template using the remaining amount.

Pills only render parsed pure numbers (e.g., "~5.5 GB"), do not display notes in the data, so the three values in tier_stats should be clean numbers, do not add apologetic notes like "only identified items/system not included"—system files are already in the blue section, red only includes quantifiable 🔴 items (duplicate apps, large apps to uninstall, etc.), system files/snapshots with inaccurate volume naturally fall into the blue section.

Step 4 Provide Summary in Conversation

After generating the report, provide a conclusion-first summary in the conversation: estimated total releasable space, 2-3 top priority items to clean up, and the highest-risk item. Let users check the webpage for details.

Dependencies and Prerequisites

All scripts use Python 3 standard library, zero third-party dependencies (no need for pip install).
macOS comes with python3,
```
du
```
,
```
diskutil
```
,
```
osascript
```
out of the box.
Windows does not have Python installed by default—need to install Python 3 first, and commands are often
```
python
```
or
```
py -3
```
(not
```
python3
```
). This skill uses
```
python3
```
in command examples, which will automatically switch to
```
python
```
/
```
py -3
```
on Windows.
This skill is agent-driven: After scanning data, the agent (Claude) performs classification analysis, it is not a double-click-to-run independent App.

Platform Status

macOS: Fully implemented and tested (scanning / report / one-click deletion fully verified).
Windows: Code is written (
```
scan_windows
```
in
```
scan.py
```
,
```
_trash_windows
```
in
```
server.py
```
uses
```
SHFileOperationW
```
), but not tested on real Windows. When running on Windows for the first time, verify: target directory paths,
```
os.scandir
```
size, recycle bin deletion functionality. Multi-drive support is already implemented (main disk progress bar + other disk list).

Long-term Optimization Suggestions Material (write into report summary.long_term)

Regular cleanup:
```
brew cleanup
```
, Xcode DerivedData, browser caches
Visualization tools: DaisyDisk, GrandPerspective, OmniDiskSweeper
Archive large files to external drive / iCloud / NAS; macOS "System Settings > General > Storage" optimization options

storage-analyzer

NPX Install

Tags

SKILL.md Content (Chinese)

Storage Analyzer

Iron Rules

Execution Process

Step 1 Scan (Read-only)

Step 2 Analysis and Categorization

Step 3 Generate Interactive Report

Step 4 Provide Summary in Conversation

Dependencies and Prerequisites

Platform Status

Long-term Optimization Suggestions Material (write into report summary.long_term)