Five-level safety model: L1🟢Regenerable cache (delete directly) / L2🟡System junk (delete directly) / L3🟠Application cache (recoverable area) / L4🔴Deep findings (recoverable area, item-by-item confirmation) / L5⚫Expert area (report only).
Iron rules (must not be violated)
- The Agent running this Skill never directly deletes any file. Deletion only goes through
engine/execute.ps1。 - Each item in L4 deep findings must first be confirmed item-by-item by the user on the report page.
- Paths rejected by execute.ps1 (protection list hit) must not be deleted by any other means to bypass this.
- For sedimentation rules discovered through exploration, user consent must be obtained first before calling learn-rule.
How to speak to the user
Use short, specific Chinese, with numbers carrying units. During scanning, explain the locations being checked and the progress; when showing results, distinguish the discovered capacity from the estimated release amount of selected items. Before submitting, remind the user to check the paths, handling methods, and items requiring administrator rights. During dry runs, clearly state that no actual deletion occurred; after actual completion, explain handling, skips, and recovery methods based on the execution report.
For the user, you may use "放心清理" "系统垃圾" "可恢复区" "逐项确认" "仅供参考" to explain the five levels, while retaining the level identifiers to correspond with the report. Do not guarantee that every item can be recovered, and do not describe the estimated release amount as already released. Selecting a cross-disk item will include all paths of that item, which must be explained before confirmation.
Path conventions
In this document, code-relative paths (engine/, tools/, rules/) are all based on this skill's root directory
(the directory where SKILL.md is located). Resolve to absolute paths before executing commands, for example:
$sk = "<本技能根目录的绝对路径>", then write all commands as powershell ... -File "$sk\engine\scan.ps1".
User data is placed in $env:LOCALAPPDATA\win-clean, not written into the Skill installation directory, to avoid overwriting logs and learned rules during updates. Each run creates an independent session directory:
$data = Join-Path $env:LOCALAPPDATA 'win-clean'; $run = Join-Path (Join-Path $data 'runs') ([guid]::NewGuid().ToString('N')); New-Item -ItemType Directory -Path $run -Force | Out-Null。
$run stays in the same session and is used for this scan, selection, and execution.
Phase ① Start: Overview and profile
Get-PSDrive -PSProvider FileSystem | Select Name,Used,Free
After showing the space overview of each drive, start scanning directly, without requiring the user to first choose a profile or drive. When the user explicitly mentions a drive letter, scan only the specified drive; otherwise scan all fixed drives. Use the standard profile by default (quick scan + known residual verification); when the user explicitly requests quick or deep, respectively run only the quick scan or add the Phase ②B exploration. The user only needs to select cleanup content in the report.
Phase ② Scan
A. Quick scan (mandatory for all profiles):
powershell -NoProfile -ExecutionPolicy Bypass -File "$sk\engine\scan.ps1" -LearnedFile "$data\rules\learned.json" -OutFile "$run\scan-result.json" -ProgressFile "$run\scan-progress.json"
When the user specifies a drive letter, append -Drives "C,D"at the end of the command (replace with the actual drive letter); if -Drives is not passed, scan all fixed drives.
Run the scan in the background, and during this period read the progress file every few seconds and announce progress to the user ("正在扫描 npm-cache (5/24)…"), and announce the total discovered amount when complete.
B. Agent exploration (deep profile only) — hunt like an expert for targets outside the rule library:
- Use PowerShell to read-only tally the first-level directories of the target drive, and find unknown large consumers by size; do not traverse heavy reparse points.
- For a large directory, perform an additional read-only inspection of at most two levels to identify: remnants of uninstalled applications (cross-check against the installed list), old installer/update remnants (
*-updater、pending、installer.exe), abnormal log directories, duplicate toolchains (multiple version directories of the same software) - Determine the nature: remnant → L4; regenerable cache → L1; system-level → L5 report
- For each finding, announce to the user: "Found X (size, path, basis for judgment, recommended level)"
- After the user agrees, persist it:
powershell -NoProfile -ExecutionPolicy Bypass -File "$sk\tools\learn-rule.ps1" -RulesDir "$sk\rules" -LearnedFile "$data\rules\learned.json" -Id <kebab-id> -Level <1-5> -Name "<名>" -Paths "<绝对路径>" -Type <cache|temp|leftover|installer|log|dump|system> -Desc "<判断依据>"
After persisting, rerun the quick scan; the new rules will enter the report.
Stage ③ Report and selection
powershell -NoProfile -ExecutionPolicy Bypass -File "$sk\engine\serve.ps1" -ScanFile "$run\scan-result.json" -SelectionsOut "$run\selections.json" -HistoryIndex "$data\history\index.json"
Start it using a background task method supported by the current Agent, and wait for "$run\serve-info.json" to appear, then read the URL,
and have the user open it in a browser and make selections. Poll for "$run\selections.json" to appear (up to 15 minutes).
If submission times out → read the pid from serve-info.json and Stop-Process -Id <pid>, then ask the user whether to cancel or fall back to static mode.
Fallback: if the service cannot start → -Static -OutHtml "$run\report.html", and at the "Submit cleanup" area on the page the user
copies the command back to the terminal to execute. After the user executes the copied command, copy $env:TEMP\win-clean-selection.json
as "$run\selections.json" and then proceed to Stage ④.
Stage ④ Execution
$d = Join-Path $run "execution"
powershell -NoProfile -ExecutionPolicy Bypass -File "$sk\engine\execute.ps1" -ScanFile "$run\scan-result.json" -SelectionsFile "$run\selections.json" -HistoryDir $d
Before execution, first use -DryRun to perform a dry run and show the results to the user; items requiring administrator privileges will be skipped, and do not claim that the page has generated an administrator command. Isolating to the same disk usually does not free disk space immediately.
Stage ⑤ Final report
powershell -NoProfile -ExecutionPolicy Bypass -File "$sk\engine\report-gen.ps1" -ScanFile "$run\scan-result.json" -ExecSummaryFile (Join-Path $d 'exec-summary.json') -SessionDir $d -HistoryRoot "$data\history"
Stage ⑤ uses this session's $run and $d; when continuing across sessions, the corresponding session directory must be explicitly located.
Open <$d>/final-report.htmlin a browser, and announce to the user the amount freed, before/after comparison, recovery script location,
skipped/administrator-required items, and cumulative results. The recoverable area is located within this execution directory; the tool checks and cleans isolated content older than 30 days only when the same execution directory is used again, and periodic removal is not guaranteed.
Parameter quick reference
scan.ps1: -RulesDir -LearnedFile -OutFile -OnlyIds -Drives -ProgressFile ｜ serve.ps1: -ScanFile -SelectionsOut -HistoryIndex -Static -OutHtml execute.ps1: -ScanFile -SelectionsFile -HistoryDir -DryRun ｜ report-gen.ps1: -ScanFile -ExecSummaryFile -SessionDir -HistoryRoot learn-rule.ps1: -RulesDir -LearnedFile -Id -Level -Name -Paths -Type -Desc -AutoSelect