Get the FREE Ultimate OpenClaw Setup Guide →

workspace-cleanup-audit

npx machina-cli add skill gaelic-ghost/productivity-skills/workspace-cleanup-audit --openclaw
Files (1)
SKILL.md
3.3 KB

Workspace Cleanup Audit

Overview

Run a read-only scan over repositories in ~/Workspace and report cleanup chores ranked by severity. Never delete, move, or modify files.

Workflow

  1. Load active customization config:
    • Prefer <skill_root>/config/customization.yaml.
    • Fall back to <skill_root>/config/customization.template.yaml.
  2. Run scripts/scan_workspace_cleanup.py.
  3. Review top-ranked findings first.
  4. Report findings with severity, repo, directory, category, size, and reason.
  5. Suggest cleanup actions as text only.

Commands

Use the default workspace scan:

uv run --with pyyaml python scripts/scan_workspace_cleanup.py

Scan a custom workspace root:

uv run --with pyyaml python scripts/scan_workspace_cleanup.py --workspace ~/Workspace

Return machine-readable output:

uv run --with pyyaml python scripts/scan_workspace_cleanup.py --json

Tune noise floor and stale threshold:

uv run --with pyyaml python scripts/scan_workspace_cleanup.py --min-mb 100 --stale-days 90

Configuration precedence:

  1. CLI flags
  2. config/customization.yaml
  3. config/customization.template.yaml
  4. Script hardcoded defaults

Customization Workflow

When a user asks to customize this skill, use this deterministic flow:

  1. Read active config from config/customization.yaml; if missing, use config/customization.template.yaml.
  2. Confirm desired behavior for:
    • workspace root
    • thresholds (minMb, staleDays, maxFindings)
    • severity cutoffs
    • directory/file override rules
  3. Propose 2-4 option bundles with one recommended default.
  4. Create or update config/customization.yaml from template and set:
    • schemaVersion: 1
    • isCustomized: true
    • profile: <selected-profile>
  5. Validate with a scan run and report changed keys plus behavior deltas.

Customization Reference

  • Detailed knobs and examples: references/customization.md
  • YAML schema and allowed values: references/config-schema.md

Output Contract

Each finding includes:

  • severity
  • repo
  • directory
  • category
  • size_human
  • score
  • why_flagged
  • suggested_cleanup

The report also includes:

  • Top findings sorted by severity then size
  • Repo summary ranked by total flagged size

Read-Only Rules

  • Never run destructive commands.
  • Never remove artifacts automatically.
  • Never write into scanned repositories.
  • Provide recommendations only.

Automation Templates

Use $workspace-cleanup-audit inside automation prompts so Codex consistently loads this skill behavior.

For ready-to-fill Codex App and Codex CLI (codex exec) templates, including placeholders, safety defaults, and output handling, use:

  • references/automation-prompts.md

References

  • Pattern and threshold notes: references/patterns.md
  • Automation prompt templates: references/automation-prompts.md
  • Customization guide: references/customization.md
  • Customization schema: references/config-schema.md

Source

git clone https://github.com/gaelic-ghost/productivity-skills/blob/main/workspace-cleanup-audit/SKILL.mdView on GitHub

Overview

Workspace Cleanup Audit runs a read-only scan over repositories under ~/Workspace to surface cleanup chores ranked by severity. It never deletes, moves, or modifies files; it reports findings with severity, repo, directory, category, size, and reason, and suggests text-only cleanup actions.

How This Skill Works

It loads the active customization config, executes scripts/scan_workspace_cleanup.py against the target workspace, and outputs findings ranked from highest to lowest severity. Each finding includes fields like severity, repo, directory, category, size_human, score, why_flagged, and suggested_cleanup; results can be reviewed in human-readable or JSON form.

When to Use It

  • During a quarterly workspace hygiene review to surface cleanup opportunities
  • When you suspect buildup of build artifacts or caches in repos under ~/Workspace
  • To identify unusually large transient files taking up space in multiple repos
  • When preparing cleanup guidelines for developers working in ~/Workspace
  • To obtain an omnicious top-severity report before cleanup planning

Quick Start

  1. Step 1: Load active config from config/customization.yaml or template.yaml
  2. Step 2: Run the default scan: uv run --with pyyaml python scripts/scan_workspace_cleanup.py
  3. Step 3: Review findings (use --json for machine-readable results) and document recommended cleanups in text form

Best Practices

  • Run in read-only mode and review all findings before acting
  • Tune thresholds (minMb, staleDays) and severity cutoffs to match team norms
  • Review top-ranked findings first to maximize impact with minimal changes
  • Keep customization.yaml updated via the provided workflow and validate with a test scan
  • Provide text-based cleanup recommendations rather than executing any file operations

Example Use Cases

  • Example: repo-beta has a 2.1 GB node_modules cache flagged in dir src/, severity high, reason: buildup of cache artifacts
  • Example: repo-alpha shows a 1.4 GB build output directory in dist/, severity critical, reason: stale binary artifacts
  • Example: repo-gamma reports multiple transient large files (tmp-logs, cache) totaling 780 MB in various dirs
  • Example: A team-wide scan highlights several directories with stale artifacts older than 90 days and total 3.2 GB
  • Example: The top finding across all repos is a large local package cache exceeding 1 GB in directory apps/frontend/

Frequently Asked Questions

Add this skill to your agents
Sponsor this space

Reach thousands of developers ↗