# DirStat_Skill

> Use when auditing disk usage on Windows or Linux and suggesting what a human should review to reclaim space without changing files automatically, especially for caches, model files, trash, and partial downloads.

- Skill: `jagones84/dirstat-skill` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jagones84/dirstat-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jagones84/dirstat-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: jagones84 (https://skillmd.com/u/jagones84)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jagones84/dirstat-skill

---


# DirStat_Skill

> READ-ONLY ANALYSIS ONLY
>
> This skill never changes files automatically, never schedules cleanup, and never performs cleanup actions.
> It only scans disk usage, emits compact reports, and suggests what a human should review.

## Overview

This skill turns the repository into an agent-ready workflow for read-only space recovery triage.

It audits disk usage, reads compact reports, and produces an analysis dossier with six analysis types:

- `dominant space`
- `path safety`
- `nearby references`
- `signature heuristics`
- `probable duplicates`
- `protected huge hotspots`

Attention levels remain compact:

- `review first`
- `review carefully`
- `keep protected`

## When to Use

Use this skill when:

- the user asks what is consuming disk space
- the user asks what deserves review to free disk space
- the machine has large caches, model files, partial downloads, or trash
- the user wants a safe shortlist, not blind cleanup
- the environment is Windows or Linux and the repo tools are available

Do not use this skill when:

- the user wants automatic cleanup without review
- the environment is unrelated to this repository and its workflow
- the task is generic system administration with no need for disk-space triage

## Safety Rules

- Never change files automatically.
- Never emit cleanup commands.
- Suggest human review only.
- Read compact outputs before raw exports.
- Treat partial downloads, trash, and cache as `review first`.
- Treat model assets, checkpoints, and live app inputs as `review carefully`.
- Treat Docker storage, swap, and system-owned paths as `keep protected`.
- Treat `probable duplicates` as suspicion, not proof.
- Treat `protected huge hotspots` as visibility findings, not action cues.
- If `ncdu` is missing on Linux and installation needs `sudo`, use the repo install path only; do not invent alternate flows.
- Never store credentials or passwords in the repository.

## Repository Entry Points

- `README.md`: project overview and commands
- `AGENTS.md`: repository entrypoint for agents
- local `.agent/HANDOFF.md` if present: volatile operator memory, not required for the public repository
- `python -m dirstat_skill.cli`: generic CLI
- `scripts/linux/*.sh`: Linux helper scripts only
- `scripts/windows/*.ps1`: Windows helper scripts only

## Standard Workflow

### 1. Read State First

Read:

- `README.md`
- local `.agent/HANDOFF.md` only if it exists in the current working copy

If the repo already contains recent audit results or blockers, continue from there instead of redoing the whole flow.

### 2. Choose The Right Runtime Path

- On Windows:
  - use the native CLI with explicit `--path`
- On Linux:
  - use the generic CLI with `--engine ncdu`
  - or use `scripts/linux/` helpers when they make the flow faster
- On remote or mixed-machine setups:
  - run the scan on the machine that owns the filesystem
  - move only the compact outputs elsewhere for review
  - if a Linux or DGX host already has remote shell access to a Windows host, launch the `windows-native` CLI on that Windows host instead of scanning a mounted Windows path from Linux
  - do not force Linux `ncdu` onto Windows-style paths or Windows runtime onto Linux-style paths

### 3. Windows Read-Only Audit

Run:

```bash
python -m dirstat_skill.cli audit --path C:\ --output-dir outputs\win_c_audit --config config\defaults.json
```

Override the dominant-space threshold when needed:

```bash
python -m dirstat_skill.cli audit --path C:\ --output-dir outputs\win_c_audit --config config\defaults.json --dominant-percent 0.67
```

Expected:

- a new run folder or explicit output folder
- a raw export file
- `summary.md`
- `top_dirs.csv`
- `top_files.csv`
- `candidates.json`
- `review_candidates.csv`
- `review_report.md`
- `run.log`

To scan more than one target on Windows:

```bash
python -m dirstat_skill.cli audit --path C:\ --path D:\models --output-dir outputs\win_multi_audit --config config\defaults.json
```

### 4. Linux Read-Only Audit

Run:

```bash
python3 -m dirstat_skill.cli audit --path /home --engine ncdu --output-dir outputs/linux_home_audit --config config/defaults.json
```

Override the dominant-space threshold when needed:

```bash
python3 -m dirstat_skill.cli audit --path /home --engine ncdu --output-dir outputs/linux_home_audit --config config/defaults.json --dominant-percent 0.72
```

Expected:

- a new run folder under `outputs/`
- a raw export file
- compact report files generated by the Python CLI

If `ncdu` is missing, use:

```bash
bash scripts/linux/install_ncdu.sh
```

### 5. Optional Linux Helper Workflow

Run:

```bash
bash scripts/linux/prepare_linux_scripts.sh
bash scripts/linux/run_audit.sh
```

For DGX over SSH:

```bash
ssh dgx bash /home/jagones/Repositories/DirStat_Skill/scripts/linux/prepare_linux_scripts.sh
ssh dgx /home/jagones/Repositories/DirStat_Skill/scripts/linux/run_audit.sh
```

### 5.1 Optional Windows Helper Workflow

```powershell
powershell -ExecutionPolicy Bypass -File scripts/windows/run_audit.ps1 -TargetPath C:\ -OutputDir outputs\win_c_audit
```

### 6. Read Compact Outputs

Run:

```bash
bash scripts/linux/show_latest_audit.sh
```

Read in this order:

- `review_report.md`
- `review_candidates.csv`
- `summary.md`
- `top_dirs.csv`
- `top_files.csv`
- `candidates.json`

Do **not** start from the raw export unless the compact reports are missing or clearly wrong.

### 8. Classify Findings

Use the dossier analyses first:

- `dominant space`
- `path safety`
- `nearby references`
- `signature heuristics`
- `probable duplicates`
- `protected huge hotspots`

Then use the attention levels:

- `review first`
  - incomplete downloads
  - trash contents
  - large cache blobs that are redownloadable
- `review carefully`
  - model directories under user-owned paths
  - checkpoints, safetensors, gguf, live app inputs
- `keep protected`
  - `C:\Windows`
  - `C:\Program Files`
  - `/etc`, `/usr`, `/boot`, `/var/lib`
  - anything clearly part of runtime/system storage

### 9.1 Dominant-Space Walk

The selector should:

- start from the heaviest roots or macrofolders
- keep the children that explain about the configured dominant threshold of each dominant branch
- recurse into dominant subtrees
- emit all concrete candidates found in those dominant subtrees, even when many medium files matter together

This avoids the classic failure mode where a flat top list misses dozens of 1-5 GB review-worthy files that dominate space as a group.

### 9. Produce The Final Suggestion

Return a human-review suggestion list grouped by:

- path
- size
- reason
- analysis type
- attention level
- evidence

Preferred output order:

1. review first
2. review carefully
3. keep protected

## Verified Runtime Notes

- Verified on Windows with one audit covering `C:\Windows\Temp`, `D:\`, `E:\`, and `F:\`.
- Verified on Linux ARM64 DGX with `scripts/linux/run_audit.sh`.
- Compact Linux reports now include recursive directory sizing so `top_dirs.csv` reflects real subtree weight instead of directory inode size only.

## Output Contract

The final answer should always contain:

- a short status line with whether the audit actually ran
- the latest run path
- the most actionable findings first
- anything large that should *not* be touched blindly
- the main reason for each recommendation
- an evidence summary for each emitted finding

## Common Mistakes

- reading the raw export first and wasting tokens
- suggesting cleanup of model assets only because they are large
- touching Docker or swap storage
- skipping compact outputs and jumping directly to live assets
- reporting only file names without full paths
- omitting the dependency-check rationale
- treating “large” as equal to “safe to clean”

## Quick Reference

```bash
python -m dirstat_skill.cli audit --path C:\ --output-dir outputs\win_c_audit --config config\defaults.json
python3 -m dirstat_skill.cli audit --path /home --engine ncdu --output-dir outputs/linux_home_audit --config config/defaults.json
bash scripts/linux/run_audit.sh
bash scripts/linux/show_latest_audit.sh
bash scripts/linux/find_safe_candidates.sh
```

## Current Naming

The public repository and skill identity are `DirStat_Skill`.
The Python import package is `dirstat_skill`.