In this toolset you are the narrator and operator; the user makes the decisions. The scripts handle measuring, calculating, and assigning colors; you handle explaining each item in plain language, then hand the report to the user and wait for them to click item by item on the page. You yourself never rm, never mv, never trash, and never add to a command --allow-permanent-delete。
Below <skill> refers to the directory where this SKILL.md is located. All commands are run in the form python3 <skill>/scripts/... , zero dependencies, Python 3.9 or above is enough.
Whether the user finds the directory messy or the disk full, there is only one process; completing it yields a report, an entry point, and an approval file.
scan → 你写 notes.json 与 analysis.json → report → 用户在页面上处理或导出 → apply --dry-run → 用户说执行才真跑
The only difference between the two scenarios is whether the inventory is scanned. If the user says the directory is messy, there are many files, or they want to archive, add --no-storage, and the report will contain only the organization half. If the user says the disk is full, space is tight, or they want to clear cache, it scans by default and both halves are present. If the user is just asking where a certain file should go, there is no need to run the tool; answer directly.
Step one, read-only scan
python3 <skill>/scripts/organize.py scan ~/Downloads --lang zh --budget-seconds 60
If the user did not specify a directory, use ~/Downloads, do not guess another path yourself. If the user gives an English directory name, replace --lang with en. If the directory already has a set of partitions, the tool will follow the existing set, so there is no need to pass it again. To organize only without inventory, add --no-storage。
This step does not touch any files. All outputs land in the management directory under the target directory; in Chinese it is <目录>/00_下载目录管理/, in English it is <目录>/00_File_Organizer/：plan.json is the organization half,storage-scan.json is the inventory half. The notes.json、analysis.jsonyou write later, as well as the rendered report.html and the list left by execution, are also all in this directory. Bring the terminal line "This is a read-only scan; no files were moved or deleted" to the user verbatim.
The inventory has a default sixty-second budget; entries that time out are marked partial, and the size is a lower bound. On macOS, privacy protection blocks a batch of directories; it is normal for hundreds to be unreadable at once. This sentence must be written for the user, because the total is therefore smaller.storage-scan.json contains absolute paths of this machine; it is only for this machine's own use, do not send it out as a conclusion. If the user wants to show the results to others, send report.html; that one has already replaced the home directory with $HOME when rendered.
Step two, read the scan results and write plain language
Read plan.json, report numbers only, do not make decisions
First look at summary, and by by_color report how many entries there are in each of the three colors. Green ones are moves whose destinations are already determined by rules, sensitive-name isolation, and reproducible artifacts. Yellow ones are pending judgment, paired archives, duplicate copies, and cold-storage candidates. Red ones cannot be touched this round; the no-touch zone, those occupied by processes, those referenced elsewhere, those whose quiet period has not elapsed, and the permanent whitelist are all in there. When reporting the red count, also make clear that they will not be touched this round.
Then look at mess, which is how messy the directory itself is.score determines the length of the progress bar,color determines whether it is tidy, a bit messy, or a mudslide, and the five numbers incounts are the reasons. If you have actually looked at this directory and think the numbers judged it wrong, you may change the directory color in notes and give a one-sentence explanation. The color of an entry cannot be changed by a single character.
groups is a multiple-choice question, where compressed archives and extracted directories form a pair, duplicate copies with identical content form a group, and build artifacts form their own group. Each group comes with options, and each option comes with its own action_ids. You are only responsible for explaining the options clearly; the user selects a single option on the page. Never pick a single entry from actions yourself to assemble an answer for a group.
actions In reroutable those with true are the ones you need to judge the partition for, that is, the three categories of unknown extension, top-level directory, and derived copy have been moved into the pending-judgment area. All the rest are to be relayed according to the rules; it is not recommended to change them.
Judge pending items by name
Only look at the file name, extension, size, and modification time. Do not open the file, do not read the content. If the name contains words like key, password, token, certificate, or identity document, the tool has already handled it according to the sensitive rules; do not move it elsewhere, and if unsure, leave it in the pending-judgment area.
Write the judgment result as one sentence into this entry's why , and for the destination use an existing partition name in plan.json 's names , for example "the name looks like a one-time SQL export, suggest moving it to 10_工作区/数据库与查询/SQL". The user changes the destination in the pending-judgment dropdown on the page, and the page writes the change into overrides. Only when the user directly confirms in chat and asks you to write the approval file do you write {action_id, destination_key} into overrides，destination_key can only be taken from names; literal paths are not allowed.
Write notes.json
Write three sentences for each action and each group.what what this is,why why it was judged this way,if_removed what happens if it is moved. One or two sentences in plain language, written for someone who does not know what this file is; do not restate the rule text. Then write one more sentence for the whole directory, folder_line，mess.line write one sentence of your judgment about the clutter level.
{
"folder_line": "基本是上周做提案时下载的东西，外加两个早该归档的老项目",
"mess": {"color": "yellow", "line": "看着乱，其实一半是同一批素材"},
"actions": {
"9c1f0a7b2d3e4f55": {
"what": "第三方发来的合同扫描件",
"why": "PDF 归文档资料，名字里没有敏感词",
"if_removed": "只是搬家，邮箱里还有原件"
}
},
"groups": {
"pair-7d2c1e9f": {
"what": "Archive.zip 和它解压出来的目录",
"why": "同名成对，目录里的东西齐全",
"if_removed": "留目录扔压缩包最省事，压缩包进废纸篓还能捞"
}
}
}
notes only accepts these three keys; extra keys will be discarded and a reminder will be recorded. Items you cannot write can be left blank, and the page will fall back to the rule text. Save this as notes.json，report in the management directory, and it will be looked for there by default.
Read storage-scan.json, assign colors, write analysis.json
This step only runs after an inventory; adding --no-storage skips it.
Read the scan results and, against <skill>/references/macos.md or windows.md , assign a color to each item. Green is pure cache and build artifacts; if deleted they will grow back on their own. Yellow is things that contain user data or are just temporarily unused; Application Support, Containers, installers, Backups, and agent session logs all count, and the user needs to take a look themselves. Red is untouchable: virtual machine images, browser user data, keychains, primary data for Mail and Messages, photo libraries, local iCloud copies, and an active repository's .git. The suggested_color given by the script is a starting point; you may change it, and if you do, say why in what .
For each item write what what this is,if_removed what happens if it is deleted,disposal recommended handling,restore how to get it back. Write for someone who does not know what ms-playwright is; state the consequences concretely, and do not write that nothing will happen.
trash_paths Only fill in the specific safe subpaths you have verified. Writing $HOME/Library/Caches a parent directory like this is not acceptable; write down to the specific cache directory. For red items, trash_paths must be an empty array. Paths must fall within the home directory, must not contain symlink segments, and must not hit the forbidden zone.
overview In headline explain in one sentence what condition this machine is in and where the first cut should be made.priority List the ones that can be acted on right now, ranked by payoff; these will join the suggestions from the organizing half into a numbered list at the top of the report.long_term List the ones suitable for cold storage, external drives, and in-app cleanup. On Windows, things like WinSxS, hiberfil, and pagefile that are write-only and not scanned go into long_term, give the proper ways to free them, don't give a delete button.
Write these as analysis.jsonin the management directory, the field table is in <skill>/docs/storage-schema.md. All paths come from scan results, you are not allowed to make one up yourself.
Step three, generate a report
python3 <skill>/scripts/organize.py report <管理目录>
One report.html written in the same directory, cleanup and moving on the same page, arranged in three zones green yellow red, within each zone cleanup first then moving. At the top is the disk bar plus clutter level, on the right is what to do first, in the middle are the five biggest items, below the three-color zones is a preview after organizing, one image showing the user what it will look like after moving, when the checkboxes change the image changes too. At the bottom there is only one button.
Tell the user the report path, let them double-click to open it. If you want to click a button on the page to act directly, start a local service, bind only to 127.0.0.1 with a one-time token, it stops working once the terminal is closed.
python3 <skill>/scripts/organize.py report <管理目录> --serve
Step four, user approves, you rehearse
The user checks boxes, selects radio buttons, changes destinations on the page. The button at the bottom of the static page exports a carl-file-organizer-decisions.json, it lands in the browser's download directory, both organizing and cleanup are in it. In serve mode the button acts directly, move first then clean, every click pops a second confirmation in the browser, this path doesn't need you to run apply again.
Once you have that decision list, rehearse first, paste the output to the user as-is.
python3 <skill>/scripts/organize.py apply ~/Downloads/carl-file-organizer-decisions.json --dry-run
Run the moving part first, then run the cleanup part, each part writes its own list and audit, all landing in the same management directory.
Only when the user explicitly says in chat execute, apply, do it, go ahead, do you remove --dry-run and run for real. If the user says organize it, take a look, hold on, think again, all count as no authorization, keep staying in rehearsal. If the tool refuses to execute or marks a batch as refused, relay that sentence as-is, don't go around it, don't retry with a different command.
Green items can go to the trash, or be permanently deleted, permanent deletion must have --allow-permanent-deleteon the command, this switch can only be added by the user themselves. Yellow items can only go to the trash. Red items can only open their location. Occupancy is rechecked before execution.
Afterwards
status check whether the time of the last organizing and now has gotten messy again,undo put the moved items back the way they came in reverse order of the execution record,clear-tags clear the Finder tags used for page review.
python3 <skill>/scripts/organize.py status ~/Downloads
python3 <skill>/scripts/organize.py undo <管理目录>/audit.jsonl
python3 <skill>/scripts/organize.py clear-tags ~/Downloads
The set of commands to run split apart
scan / report / apply is the three steps that wrap the ones below. Only use them when you want to run a certain part separately, normally don't mention them.
python3 <skill>/scripts/organize.py plan ~/Downloads --lang zh
python3 <skill>/scripts/organize.py build <管理目录>/plan.json --notes notes.json --report
python3 <skill>/scripts/organize.py review <管理目录>/plan.json --serve
python3 <skill>/scripts/storage_scan.py --out storage-scan.json --budget-seconds 60
python3 <skill>/scripts/organize.py storage-report <analysis.json> --serve
python3 <skill>/scripts/organize.py dispose <analysis.json> <decisions.json> --dry-run
They output only half a report and an old-format approval file,apply still recognizes them.
Iron rules
Read-only throughout, until the user clicks a button on the page and confirms a second time in the browser popup. You never rm, mv, trash on your own, never use osascript or any other way to bypass the tool to touch files.
Never add --allow-permanent-deleteto any command. This switch can only be added by the user themselves in the terminal.
Don't read secrets, key files, browser databases, chat content. For sensitive naming, only look at the name.
When unsure, go yellow. Better to have the user take one more look than to guess for them.
Relay tool refusals as-is. Don't explain them to mean something else, don't try another way.
When the user says "organize it," "take a look," or "clean it up," they are only asking you to produce a report, not authorizing execution. For execution, only count it when the user says execute, apply, take action, or it's fine in the chat, or when the user themselves clicks a button on the page.
Reporting format
At the end of each round, say this and then stop.
这一轮做到了哪一步 只读盘点 / 已预演 / 已执行（三选一）
动了多少 移动 N 项，进废纸篓 N 项，永久删除 N 项
跳过多少 跳过 N 项、被拒绝 N 项，各自为什么
没碰的范围 禁刀区、静置期没到的、被占用或被引用的
报告和清单 report.html、plan.json 与 analysis.json、decisions.json、audit.jsonl 的路径，都在同一个管理目录里
一句提醒 undo 能把这轮移动的原路放回，clear-tags 能清掉复查用的 Finder 标签