🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
πŸ¦€ ClawHub

Workspace Organization - Automated Health Checks

by @donovanpankratz-del

Automated workspace health checks and entropy prevention for OpenClaw. Detects broken symlinks, empty dirs, large files, malformed names. Maintenance audit s...

Versionv1.0.0
Downloads601
Installs1
TERMINAL
clawhub install workspace-organization

πŸ“– About This Skill


name: workspace-organization version: 1.0.0 description: Automated workspace health checks and entropy prevention for OpenClaw. Detects broken symlinks, empty dirs, large files, malformed names. Maintenance audit script with cron support. Keeps deployments clean and structured. homepage: https://clawhub.com changelog: Initial release - Maintenance audit, setup script, organization standards metadata: openclaw: emoji: "πŸ“" requires: bins: ["bash", "find", "du"] os: - linux - darwin

Workspace Organization

Standards and automated maintenance for clean OpenClaw deployments.

Files Included

  • SKILL.md β€” Agent instructions
  • README.md β€” Setup guide
  • maintenance-audit.sh β€” Run to audit workspace health
  • setup.sh β€” Run once to initialize standard structure
  • Note: Scripts auto-detect your workspace. Pass a path as argument to override: ./maintenance-audit.sh /custom/path

    Problem Solved

    Workspaces degrade over time:

  • Broken symlinks from moved files
  • Empty directories from deleted projects
  • Large files eating disk space
  • Malformed names breaking scripts
  • No visibility into workspace health
  • This skill provides automated audits + cleanup guidance to prevent entropy.

    When to Use

  • New workspace setup β€” Initialize standard directory structure
  • Periodic maintenance β€” Weekly/monthly health checks (cron recommended)
  • Pre-deployment cleanup β€” Remove cruft before backups
  • Debugging workspace issues β€” Find broken symlinks, malformed names
  • Disk space review β€” Identify large files and bloat
  • What It Provides

    1. maintenance-audit.sh

    Automated health check script that detects:
  • βœ… Broken symlinks
  • βœ… Empty directories (excluding node_modules, .git)
  • βœ… Large files (>10MB)
  • βœ… Malformed file/directory names (spaces, special chars)
  • βœ… Disk usage by top-level directory
  • βœ… File/directory counts
  • βœ… Recent changes (last 24 hours)
  • 2. setup.sh

    Initializes standard workspace structure:
    ~/.openclaw/workspace/
    β”œβ”€β”€ projects/           # Active work
    β”‚   β”œβ”€β”€ writing/        # Writing projects
    β”‚   └── code/           # Code projects
    β”œβ”€β”€ notes/              # Organized notes
    β”‚   β”œβ”€β”€ daily-reviews/
    β”‚   β”œβ”€β”€ decisions/
    β”‚   └── cost-tracking.md
    β”œβ”€β”€ memory/             # Long-term memory
    β”‚   β”œβ”€β”€ owner/          # Cross-channel user memory
    β”‚   └── sessions/       # Per-session isolated memory
    β”œβ”€β”€ skills/             # Custom skills
    β”œβ”€β”€ subagents/          # Permanent specialists
    β”‚   └── _archived/      # Old/deprecated subagents
    β”œβ”€β”€ docs/               # Documentation
    └── scripts/            # Utility scripts
    

    3. Organization Standards (docs/)

    Best practices for:
  • File naming conventions (kebab-case, no spaces)
  • Directory structure guidelines
  • Cleanup policies (what to keep/delete)
  • Git integration patterns
  • Setup

    1. Install skill:

    cd ~/.openclaw/workspace/skills
    clawhub install workspace-organization
    

    Or: download from ClawHub and extract

    2. Initialize workspace (optional, if starting fresh):

    cd ~/.openclaw/workspace/skills/workspace-organization
    ./setup.sh
    

    3. Run first audit:

    cd ~/.openclaw/workspace/skills/workspace-organization
    ./maintenance-audit.sh
    

    4. Schedule automated audits (recommended):

    openclaw cron add \
      --name "Weekly Workspace Audit" \
      --schedule "0 4 * * 0" \
      --task "Run workspace maintenance audit: bash skills/workspace-organization/maintenance-audit.sh. Log results to notes/maintenance-log.md"
    

    Usage

    Manual Audit

    cd ~/.openclaw/workspace/skills/workspace-organization
    ./maintenance-audit.sh
    

    Example output:

    === Workspace Maintenance Audit ===
    Date: 2026-02-21 16:00
    Path: /home/user/.openclaw/workspace

    1. Checking for broken symlinks... ⚠️ Found broken symlinks: /home/user/.openclaw/workspace/old-project/link-to-deleted

    2. Checking for empty directories... ℹ️ Found empty directories: /home/user/.openclaw/workspace/projects/abandoned

    3. Checking for large files (>10MB)... ℹ️ Found large files: 24M /home/user/.openclaw/workspace/logs/debug.log

    4. Checking for malformed file/directory names... ⚠️ Found malformed names: /home/user/.openclaw/workspace/projects/my project/file.md

    5. Disk usage by top-level directory: 150M skills 80M notes 50M projects 30M memory

    6. File counts: Total files: 1,234 Total directories: 156 Skills: 18 Subagents: 3

    7. Recently modified files (last 24 hours): /home/user/.openclaw/workspace/notes/cost-tracking.md /home/user/.openclaw/workspace/memory/owner/decisions.md

    === Audit Complete ===

    Agent-Driven Audit

    Ask your agent:

    "Run workspace maintenance audit"
    "Check workspace health"
    "Audit my workspace"
    

    Agent will execute script and present findings with cleanup recommendations.

    Common Issues Caught

    1. Broken Symlinks

    Causes:
  • Moved/renamed files
  • Deleted dependencies
  • Incorrect relative paths
  • Fix: Remove symlink or update target

    2. Empty Directories

    Causes:
  • Deleted projects
  • Failed installations
  • Incomplete migrations
  • Fix: Remove unless intentionally placeholder

    3. Large Files

    Common culprits:
  • Uncompressed logs (debug.log, error.log)
  • Binary artifacts (.zip, .tar.gz)
  • Downloaded datasets
  • Video/media files
  • Fix: Compress, move to external storage, or delete

    4. Malformed Names

    Problems caused by:
  • Spaces in filenames β†’ breaks scripts
  • Special characters β†’ shell escaping issues
  • Braces/brackets β†’ glob conflicts
  • Fix: Rename using kebab-case or snake_case

    Example:

    # Bad
    my project/file (copy).md

    Good

    my-project/file-copy.md

    Workspace Health Score

    After running maintenance-audit.sh, your workspace gets a score:

    | Score | Status | Meaning | |-------|--------|---------| | 90-100 | 🟒 Healthy | Minor issues or none | | 70-89 | 🟑 Fair | Some cleanup needed | | 50-69 | 🟠 Degraded | Multiple issues accumulating | | <50 | πŸ”΄ Critical | Immediate cleanup required |

    Score is calculated based on: broken symlinks (-10 each), empty dirs (-2 each), files >100MB (-5 each), malformed names (-3 each).

    Automation Strategy

    | Frequency | Action | Reason | |-----------|--------|--------| | Daily | None | Too aggressive, creates noise | | Weekly | Audit only, log results | Catch issues early | | Monthly | Audit + present to user | Review & approve cleanup | | On-demand | Before backups/deployments | Reduce backup size |

    Companion Skills

  • system-resource-monitor β€” Disk usage alerts complement workspace health
  • cost-governor β€” Track subagent costs alongside workspace hygiene
  • Integration with Other Skills

  • openclaw-backup: Audit before backup to reduce size
  • cost-governor: Track disk usage for storage costs
  • drift-guard: Organizational entropy as drift indicator
  • Customization

    Adjust Large File Threshold

    Edit maintenance-audit.sh:

    # Change from 10MB to 50MB
    find "$WS" -type f -size +50M 2>/dev/null
    

    Exclude Directories

    Add to script:

    find "$WS" -type d -empty 2>/dev/null \
      | grep -v "node_modules" \
      | grep -v ".git" \
      | grep -v "your-custom-dir"
    

    Add Custom Checks

    Extend script with:

  • Git repo status checks
  • Dependency vulnerability scans
  • License compliance audits
  • Philosophy

  • Prevent entropy β€” Structure degrades without maintenance
  • Automate detection β€” Scripts catch what humans miss
  • User-approved cleanup β€” Never auto-delete without permission
  • Standards over rigidity β€” Guidelines, not laws
  • Troubleshooting

    "Script fails on macOS"

  • Install GNU findutils: brew install findutils
  • Use gfind instead of find
  • "Too many empty directories flagged"

  • Exclude more dirs in script (e.g., .cache, .venv)
  • "Large files are necessary"

  • Document in notes/workspace-notes.md why they're kept
  • Consider moving to external storage (S3, NAS)
  • Advanced: Multi-Workspace Support

    If managing multiple OpenClaw instances:

    # Audit all workspaces
    for ws in ~/.openclaw-*; do
      WS="$ws/workspace" ./maintenance-audit.sh
    done
    


    Author: OpenClaw Community License: MIT Requires: Bash, GNU coreutils (find, du, sort)

    ⚑ When to Use

    TriggerAction
    - **Periodic maintenance** β€” Weekly/monthly health checks (cron recommended)
    - **Pre-deployment cleanup** β€” Remove cruft before backups
    - **Debugging workspace issues** β€” Find broken symlinks, malformed names
    - **Disk space review** β€” Identify large files and bloat

    πŸ’‘ Examples

    Manual Audit

    cd ~/.openclaw/workspace/skills/workspace-organization
    ./maintenance-audit.sh
    

    Example output:

    === Workspace Maintenance Audit ===
    Date: 2026-02-21 16:00
    Path: /home/user/.openclaw/workspace

    1. Checking for broken symlinks... ⚠️ Found broken symlinks: /home/user/.openclaw/workspace/old-project/link-to-deleted

    2. Checking for empty directories... ℹ️ Found empty directories: /home/user/.openclaw/workspace/projects/abandoned

    3. Checking for large files (>10MB)... ℹ️ Found large files: 24M /home/user/.openclaw/workspace/logs/debug.log

    4. Checking for malformed file/directory names... ⚠️ Found malformed names: /home/user/.openclaw/workspace/projects/my project/file.md

    5. Disk usage by top-level directory: 150M skills 80M notes 50M projects 30M memory

    6. File counts: Total files: 1,234 Total directories: 156 Skills: 18 Subagents: 3

    7. Recently modified files (last 24 hours): /home/user/.openclaw/workspace/notes/cost-tracking.md /home/user/.openclaw/workspace/memory/owner/decisions.md

    === Audit Complete ===

    Agent-Driven Audit

    Ask your agent:

    "Run workspace maintenance audit"
    "Check workspace health"
    "Audit my workspace"
    

    Agent will execute script and present findings with cleanup recommendations.

    βš™οΈ Configuration

    1. Install skill:

    cd ~/.openclaw/workspace/skills
    clawhub install workspace-organization
    

    Or: download from ClawHub and extract

    2. Initialize workspace (optional, if starting fresh):

    cd ~/.openclaw/workspace/skills/workspace-organization
    ./setup.sh
    

    3. Run first audit:

    cd ~/.openclaw/workspace/skills/workspace-organization
    ./maintenance-audit.sh
    

    4. Schedule automated audits (recommended):

    openclaw cron add \
      --name "Weekly Workspace Audit" \
      --schedule "0 4 * * 0" \
      --task "Run workspace maintenance audit: bash skills/workspace-organization/maintenance-audit.sh. Log results to notes/maintenance-log.md"
    

    πŸ“‹ Tips & Best Practices

    "Script fails on macOS"

  • Install GNU findutils: brew install findutils
  • Use gfind instead of find
  • "Too many empty directories flagged"

  • Exclude more dirs in script (e.g., .cache, .venv)
  • "Large files are necessary"

  • Document in notes/workspace-notes.md why they're kept
  • Consider moving to external storage (S3, NAS)