---
name: Mac Disk Cleanup
slug: mac-disk-cleanup
category: Automation
description: "Diagnoses and cleans macOS disk space, focusing on opaque 'System Data' and developer tool residues like Xcode caches, Docker VM disks, and orphan containers. Use when disk is full, System Data is large, or after uninstalling apps to remove leftovers."
github: "https://github.com/himynameisben/macos-disk-cleanup"
language: Shell
stars: 31
forks: 0
install: "npx degit https://github.com/himynameisben/macos-disk-cleanup ~/.claude/skills/macos-disk-cleanup"
installs_to: ~/.claude/skills/macos-disk-cleanup
source_path: SKILL.md
collection_size: 1
category_size: 1523
added: 2026-08-11T07:21:54.033Z
last_synced: 2026-08-11T07:21:54.033Z
canonical_url: "https://dirskills.com/skills/mac-disk-cleanup"
---

# Mac Disk Cleanup

Diagnoses and cleans macOS disk space, focusing on opaque 'System Data' and developer tool residues like Xcode caches, Docker VM disks, and orphan containers. Use when disk is full, System Data is large, or after uninstalling apps to remove leftovers.

**Install:**

```bash
npx degit https://github.com/himynameisben/macos-disk-cleanup ~/.claude/skills/macos-disk-cleanup
```

## README

# 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**

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

**Codex**

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

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

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

```bash
./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** | 自動重建、不含使用者資料 | 合併成一個選項提案，確認後刪 |
| **CONFIRM** | 可重新下載但代價高（GB 級），或改變 app 行為 | 列出大小與後果，問過再刪 |
| **DANGER** | 含使用者資料（文件、聊天記錄、憑證、書籤） | **先列出實際內容**，逐項確認 |

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

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

## 幾個陷阱預覽

完整清單在 [`references/gotchas.md`](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](LICENSE)。