macOS 磁碟清理 Skill

給 AI coding agent 用的 skill，專門處理 macOS 上那塊 Finder 不肯告訴你內容的「系統資料 / System Data」。

適合任何 Mac 使用者，開發者受益最明顯——實測從 25 GB 清回 132 GB，其中 45 GB 來自 ~/.cache/uv、~/.npm、~/.gradle 這些完全不在 ~/Library 底下、一般清理工具掃不到的位置。

[!WARNING] 這個 skill 會刪除檔案，而執行判斷的是 AI。

AI 有可能誤判、有可能把重要資料當成快取。Skill 內建三級安全分類與確認機制來降低風險，但最後把關的人是你：

• 動手前先確認有備份（Time Machine 或任何你信得過的方案）
• 逐項讀過 AI 提出的刪除清單再確認，不要無腦按 yes
• 對任何你不認得的路徑，直接叫它先列出內容再說
• 尤其注意 Documents、Group Containers 這類位置——那裡放的通常是你唯一的副本

作者與貢獻者不對任何資料損失負責。使用前請自行評估。

為什麼該留空間，留多少

「還有 20 GB 可用」在 macOS 上不等於沒事。 系統本身就需要相當大的活動空間：

實務上的建議是開機碟至少留 100 GB，200 GB 更舒服（來源）。

至於流傳已久的「SSD 要留 10–20%」法則，說法從 5% 到 30% 都有，而且對現代 SSD 有爭議——現在的 SSD 內建 7–13% 的 over-provisioning，加上 APFS 的配置演算法，舊規則已不完全適用。但空間充裕確實有助於 wear leveling 與 SSD 壽命，這點沒有爭議。

空間不足時的實際症狀：swap 寫不下去導致系統卡死、macOS 更新裝不起來、Time Machine 備份失敗。

功能

• 唯讀掃描：一次列出 ~/Library 各層、Xcode/Simulator、套件管理器快取的實際用量排名
• 掃到別人漏掉的地方：~/.cache/uv、~/.npm、~/.gradle、~/Library/pnpm/store、~/go/pkg/mod 等家目錄底下的快取
• 稀疏檔偵測：VM 磁碟的「宣告大小 vs 實際佔用」（Docker.raw 顯示 60 G，實際可能只有 5 G）
• 孤兒 container 偵測：找出 app 已經移除、但資料還佔著幾 GB 的殘留
• 三級安全分類：每個發現都標註是「自動重建的快取」還是「使用者唯一的副本」
• 完整移除清單：解除安裝 app 後該掃的 11 個位置

安裝

這是標準的 Agent Skill（SKILL.md + YAML frontmatter），Claude Code、Codex、Cursor、Gemini CLI、GitHub Copilot 等工具都吃同一套格式，只是載入路徑不同。

Claude Code

git clone https://github.com/himynameisben/macos-disk-cleanup.git \
  ~/.claude/skills/macos-disk-cleanup

Codex

git clone https://github.com/himynameisben/macos-disk-cleanup.git \
  ~/.agents/skills/macos-disk-cleanup

其他工具請查各自的 skills 目錄位置。裝完重開即可生效。

不裝 skill、只想看自己的磁碟狀況也可以——掃描腳本是獨立的，唯讀，不刪任何東西：

./scripts/disk_scan.sh          # 標準掃描，約 40 秒
./scripts/disk_scan.sh --deep   # 追加各語言套件管理器快取

使用

裝好之後直接用自然語言問你的 agent：

• 「我的 Mac 系統資料佔了 120 GB，有辦法清掉一些嗎」
• 「~/Library/Containers 裡面那個 8 GB 的資料夾是什麼？可以刪嗎」
• 「我把 LINE 刪掉了，還有殘留檔案嗎」
• 「Docker.raw 是什麼？為什麼有 60 GB」

Agent 會先掃描、分類，把要刪的東西連同「刪掉的後果」列給你確認，才動手。

安全設計

刪除不可逆，所以每個發現都要先分級：

SAFE 等級也要經過確認，不會無聲刪除。重抓數十 GB 對計量網路或即將離線的人是實質代價，這個取捨屬於使用者。

但請記得：這些是寫給 AI 的指導原則，不是技術上的強制鎖。 AI 仍可能誤判分級。上面那段警告不是客套話。

幾個陷阱預覽

完整清單在 references/gotchas.md。這些的共同點是表象與事實相反——判斷力救不了你，只有知道事實才行。這也正是這個 skill 存在的理由：AI 很聰明，但聰明救不了錯誤的前提。

Container 裡的 symlink 會讓 du 說謊

Sandbox app 的 Data/Downloads、Desktop、Movies 都是指向真實家目錄的 symlink。du -sh Data/* 正確回報 0B，但 du -sh Data/*/* 的 glob 展開會穿過 symlink，把你的 ~/Downloads 列成「app 的資料」。輸出完全合理、零錯誤訊息，照著刪就是刪掉自己的下載資料夾。

進任何 container 之前先 ls -la Data/。

稀疏檔的 ls 不是實際用量

ls -lh Docker.raw   ->  60G   # 宣告上限
du -sh Docker.raw   ->  5.4G  # 實際佔用

Operation not permitted 是預期行為

被 .com.apple.containermanagerd.metadata.plist 擋住的 container 空殼刪不掉，即使你是擁有者、即使用 sudo。內容物其實已經清空了，剩下的是 4–32 KB 的目錄殼。這不是失敗。

simctl runtime delete 靜默且非同步

跑完沒有任何輸出，runtime list 當下還看得到那個 runtime——都是正常的。更糟的是如果用 sudo 重跑，root 看到不同的清單，會回報 No runtime disk images found，看起來像失敗，其實原本那次早就成功了。

結構

├── SKILL.md                 工作流程、三級安全分類、sudo 交接方式
├── scripts/
│   └── disk_scan.sh         唯讀掃描腳本
└── references/
    ├── locations.md         位置目錄 + 回收指令 + App 專屬知識
    └── gotchas.md           10 個會造成誤判或資料損失的陷阱

授權

MIT。不提供任何形式的保證，包含但不限於因使用本專案造成的資料損失。詳見 LICENSE。