Workspace Organization - Automated Health Checks

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

Security Scan

The skill's requirements, instructions, and included scripts are consistent with an on-disk workspace auditing/organization tool and do not request unrelated credentials or install remote code.

Purpose & Capability

Name/description (workspace health checks) matches what the package does: shell scripts that scan the workspace for broken symlinks, empty dirs, large files, malformed names, disk usage and optional git status. Required binaries (bash, find, du) are appropriate and proportional.

Instruction Scope

Runtime instructions are limited to running the provided scripts and scheduling cron jobs. The scripts operate locally (file system scans, du, find, optional git status). Minor note: the scripts read an optional OPENCLAW_WORKSPACE env var to locate the workspace, but the skill metadata lists no required env vars — this is optional behavior, not a security red flag.

Install Mechanism

No install spec; the skill is instruction- and script-based only (no downloaded or extracted remote code). This is the lowest-risk install model.

Credentials

The skill requests no credentials or config paths and only needs filesystem access to the workspace. The scripts optionally consult OPENCLAW_WORKSPACE and check for a local .git repo — both are reasonable for their purpose.

Persistence & Privilege

always:false (not force-installed). The skill can be invoked by the agent (normal). It does not request persistent elevated privileges or modify other skills/configs.

Assessment

This skill is a local filesystem auditing tool: it will read and list files, directories, sizes, recent changes, and run git status if a repo exists. It does not contact external services or request secrets. Before installing or scheduling automated runs: (1) review the two scripts locally (they are short and readable) and run them once manually to inspect output, (2) back up any irreplaceable files if you plan to act on cleanup recommendations, (3) be aware the tool will report full paths and sizes (avoid running on directories that contain sensitive data you don't want listed), and (4) if you prefer a different workspace location, either pass a path to the scripts or set OPENCLAW_WORKSPACE. The only minor inconsistency: the scripts make optional use of OPENCLAW_WORKSPACE even though no env vars are declared in the registry metadata — this is benign but worth noting.

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)