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.

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 {baseDir}/scripts/linux/prepare_linux_scripts.sh
ssh dgx {baseDir}/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.