macOS Disk Cleanup — Development skill for Claude Code

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 上不等於沒事。** 系統本身就需要相當大的活動空間：

用途	需求
System volume	約 15 GB
macOS 更新期間的 Update volume	再 15 GB 以上
Preboot + Recovery	5 GB 以內
Swap（記憶體吃緊時）	可膨脹到 20 GB 以上
APFS snapshot	最大的意外來源——時機不巧的話，光裝一次 Xcode 就可能產生 64 GB 以上的 snapshot

實務上的建議是**開機碟至少留 100 GB，200 GB 更舒服**（[來源](https://eclecticlight.co/2022/05/18/how-much-free-space-does-an-apfs-disk-need/)）。

至於流傳已久的「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](https://learn.chatgpt.com/docs/build-skills)（`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