Skill: donovanpankratz-del/workspace-organization (version 1.0.0)

--- 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:** ```bash cd ~/.openclaw/workspace/skills clawhub install workspace-organization # Or: download from ClawHub and extract ``` 2. **Initialize workspace (optional, if starting fresh):** ```bash cd ~/.openclaw/workspace/skills/workspace-organization ./setup.sh ``` 3. **Run first audit:** ```bash cd ~/.openclaw/workspace/skills/workspace-organization ./maintenance-audit.sh ``` 4. **Schedule automated audits (recommended):** ```bash 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 ```bash 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:** ```bash # 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`: ```bash # Change from 10MB to 50MB find "$WS" -type f -size +50M 2>/dev/null ``` ### Exclude Directories Add to script: ```bash 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: ```bash # 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)

path: README.md
content: # Workspace Organization - Installation & Setup

Automated maintenance and organization standards for OpenClaw workspaces.

## Quick Install

```bash
# Via ClawHub (when published)
clawhub install workspace-organization

# Or manual install
cd ~/.openclaw/workspace/skills
# Download from ClawHub or extract package
```

## First-Time Setup

1. **Initialize workspace structure (optional, if starting fresh):**
```bash
cd ~/.openclaw/workspace/skills/workspace-organization
./setup.sh
```

This creates:
```
workspace/
├── projects/       # writing/, code/
├── notes/          # daily-reviews/, decisions/, cost-tracking.md
├── memory/         # owner/, sessions/
├── skills/         # Custom skills
├── subagents/      # Permanent specialists + _archived/
├── docs/           # Documentation
└── scripts/        # Utility scripts
```

2. **Run first audit:**
```bash
./maintenance-audit.sh
```

3. **Schedule automated audits (recommended):**
```bash
openclaw cron add \
  --name "Weekly Workspace Audit" \
  --schedule "0 4 * * 0" \
  --task "Run workspace maintenance audit: bash skills/workspace-organization/maintenance-audit.sh. Log findings to notes/maintenance-log.md"
```

## Usage

### Manual Audit

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

### Agent-Driven

Ask your agent:
```
"Run workspace maintenance audit"
"Check workspace health"
"What's taking up disk space?"
```

### Example Output

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

1. Checking for broken symlinks...
✓ No broken symlinks

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

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

4. Checking for malformed file/directory names...
⚠️  Found malformed names:
/home/user/.openclaw/workspace/my project/file.md
   Recommendation: Rename to 'my-project/file.md'

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

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

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

=== Audit Complete ===
```

## What Gets Checked

| Check | What It Finds | Action |
|-------|---------------|--------|
| **Broken symlinks** | Dead links from moved/deleted files | Remove or update target |
| **Empty directories** | Leftover from deleted projects | Remove unless placeholder |
| **Large files** | >10MB files eating disk space | Compress, archive, or delete |
| **Malformed names** | Spaces, special chars in filenames | Rename to kebab-case |
| **Disk usage** | Space used by top-level dirs | Archive or cleanup |
| **Recent changes** | Files modified in last 24h | Review for unexpected edits |
| **Git status** | Unstaged/untracked files (if .git exists) | Commit or ignore |

## Automation Schedule

| Frequency | Action | Reason |
|-----------|--------|--------|
| **Daily** | None | Too noisy |
| **Weekly** | Audit + log | Catch issues early |
| **Monthly** | Audit + review with user | Approve cleanup |
| **On-demand** | Before backups | Reduce backup size |

## Customization

### Change Large File Threshold

Edit `maintenance-audit.sh`:
```bash
# From 10MB to 50MB
find "$WS" -type f -size +50M
```

### Exclude More Directories

Add to empty directory check:
```bash
| grep -v "your-custom-dir"
```

### Add Custom Checks

Example: Check for old log files
```bash
echo "9. Checking for old log files (>30 days)..."
find "$WS" -name "*.log" -mtime +30 2>/dev/null
```

## Integration

**Works with:**
- **openclaw-backup:** Audit before backup to reduce size
- **cost-governor:** Track disk usage for storage costs
- **drift-guard:** Organizational entropy as behavioral drift indicator

## Troubleshooting

**"Script fails on macOS"**
```bash
brew install findutils
# Use gfind instead of find
```

**"Too many empty directories"**
- Exclude more in script (e.g., `.cache`, `.venv`)

**"Large files are intentional"**
- Document why in `notes/workspace-notes.md`
- Consider external storage (S3, NAS)

## Organization Standards

### File Naming
- ✅ Use kebab-case: `my-project-file.md`
- ✅ Use snake_case: `my_script.py`
- ❌ Avoid spaces: `my project.md`
- ❌ Avoid special chars: `file(copy).md`

### Directory Structure
- Keep related files together
- Use top-level dirs for major categories
- Archive old work to `_archived/`
- Use README.md in each major dir

### Cleanup Policy
**Keep:**
- Active projects
- Recent notes (<3 months)
- Custom skills in use

**Archive:**
- Completed projects
- Old research
- Deprecated skills

**Delete:**
- Broken symlinks
- Empty directories (unless placeholder)
- Logs older than 30 days
- Temp files (`*.tmp`, `*.cache`)

## Contributing

Submit improvements to detection logic or additional checks. Open PRs welcome.

## License

MIT - Free to use, modify, distribute.

## Credits

Created by the OpenClaw community. Keep your workspace clean.


path: maintenance-audit.sh
content: #!/bin/bash
# Workspace Maintenance Audit
# Detects broken symlinks, empty dirs, large files, malformed names
# Usage: ./maintenance-audit.sh [workspace_path]
# Example: ./maintenance-audit.sh ~/.openclaw/workspace

set -e

# Auto-detect workspace or use provided path
if [ -n "$1" ]; then
    WS="$1"
elif [ -n "$OPENCLAW_WORKSPACE" ]; then
    WS="$OPENCLAW_WORKSPACE"
elif [ -d "${HOME}/.openclaw/workspace" ]; then
    WS="${HOME}/.openclaw/workspace"
else
    echo "Error: Could not detect workspace. Usage: ./maintenance-audit.sh [workspace_path]"
    exit 1
fi

if [ ! -d "$WS" ]; then
    echo "Error: Workspace not found: $WS"
    exit 1
fi

echo "=== Workspace Maintenance Audit ==="
echo "Date: $(date '+%Y-%m-%d %H:%M')"
echo "Path: $WS"
echo ""

# 1. Broken symlinks
echo "1. Checking for broken symlinks..."
BROKEN=$(find "$WS" -xtype l 2>/dev/null || true)
if [ -n "$BROKEN" ]; then
    echo "⚠️  Found broken symlinks:"
    echo "$BROKEN"
else
    echo "✓ No broken symlinks"
fi
echo ""

# 2. Empty directories (excluding .git, node_modules, __pycache__)
echo "2. Checking for empty directories..."
EMPTY=$(find "$WS" -type d -empty 2>/dev/null \
    | grep -v "node_modules" \
    | grep -v "\.git" \
    | grep -v "__pycache__" \
    | grep -v "\.venv" \
    || true)
if [ -n "$EMPTY" ]; then
    echo "ℹ️  Found empty directories:"
    echo "$EMPTY"
else
    echo "✓ No empty directories"
fi
echo ""

# 3. Large files (>10MB)
echo "3. Checking for large files (>10MB)..."
LARGE=$(find "$WS" -type f -size +10M 2>/dev/null || true)
if [ -n "$LARGE" ]; then
    echo "ℹ️  Found large files:"
    echo "$LARGE" | while read -r file; do
        du -h "$file" 2>/dev/null
    done
else
    echo "✓ No large files"
fi
echo ""

# 4. Malformed names (spaces, braces, special chars)
echo "4. Checking for malformed file/directory names..."
MALFORMED=$(find "$WS" \( -name "* *" -o -name "*{*" -o -name "*}*" -o -name "*(*" -o -name "*)*" \) 2>/dev/null || true)
if [ -n "$MALFORMED" ]; then
    echo "⚠️  Found malformed names (spaces/special chars):"
    echo "$MALFORMED"
    echo ""
    echo "   Recommendation: Rename to kebab-case or snake_case"
    echo "   Example: 'my project' → 'my-project'"
else
    echo "✓ No malformed names"
fi
echo ""

# 5. Disk usage summary
echo "5. Disk usage by top-level directory:"
if [ -n "$(ls -A "$WS" 2>/dev/null)" ]; then
    du -sh "$WS"/* 2>/dev/null | sort -h || echo "  (Could not calculate disk usage)"
else
    echo "  (Empty workspace)"
fi
echo ""

# 6. File count summary
echo "6. File counts:"
TOTAL_FILES=$(find "$WS" -type f 2>/dev/null | wc -l)
TOTAL_DIRS=$(find "$WS" -type d 2>/dev/null | wc -l)
SKILLS=$(ls "$WS"/skills 2>/dev/null | wc -l)
SUBAGENTS=$(ls "$WS"/subagents 2>/dev/null | wc -l)

echo "  Total files: $TOTAL_FILES"
echo "  Total directories: $TOTAL_DIRS"
echo "  Skills: $SKILLS"
echo "  Subagents: $SUBAGENTS"
echo ""

# 7. Recent changes (last 24 hours)
echo "7. Recently modified files (last 24 hours):"
RECENT=$(find "$WS" -type f -mtime -1 2>/dev/null | head -10)
if [ -n "$RECENT" ]; then
    echo "$RECENT"
else
    echo "  (No recent changes)"
fi
echo ""

# 8. Git status summary (if .git exists)
if [ -d "$WS/.git" ]; then
    echo "8. Git status:"
    cd "$WS"
    UNSTAGED=$(git status --short 2>/dev/null | grep "^.M\|^.D\|^.A" | wc -l)
    UNTRACKED=$(git status --short 2>/dev/null | grep "^??" | wc -l)
    echo "  Unstaged changes: $UNSTAGED"
    echo "  Untracked files: $UNTRACKED"
    echo ""
fi

echo "=== Audit Complete ==="
echo ""
echo "Review findings and run cleanup if needed."
echo "See docs/organization-standards.md for best practices."


path: setup.sh
content: #!/bin/bash
# Workspace Organization Setup
# Initializes standard OpenClaw workspace structure
# Usage: ./setup.sh [workspace_path]
# Example: ./setup.sh ~/.openclaw/workspace

set -e

# Auto-detect workspace or use provided path
if [ -n "$1" ]; then
    WS="$1"
elif [ -n "$OPENCLAW_WORKSPACE" ]; then
    WS="$OPENCLAW_WORKSPACE"
elif [ -d "${HOME}/.openclaw/workspace" ]; then
    WS="${HOME}/.openclaw/workspace"
else
    echo "Error: Could not detect workspace. Usage: ./setup.sh [workspace_path]"
    exit 1
fi

echo "Setting up OpenClaw workspace structure at: $WS"
echo ""

# Create standard directories
mkdir -p "$WS/projects/writing"
mkdir -p "$WS/projects/code"
mkdir -p "$WS/notes/daily-reviews"
mkdir -p "$WS/notes/decisions"
mkdir -p "$WS/memory/owner"
mkdir -p "$WS/memory/sessions"
mkdir -p "$WS/skills"
mkdir -p "$WS/subagents/_archived"
mkdir -p "$WS/docs"
mkdir -p "$WS/scripts"

# Create placeholder files
cat > "$WS/notes/cost-tracking.md" << 'EOF'
# Cost Tracking Log

## Multipliers
- Creative: 7.5x
- Research: 3x
- Technical: 2x
- Simple: 1.5x

| Date | Task | Model | Est. | Actual | Ratio | Notes |
|------|------|-------|------|--------|-------|-------|
EOF

cat > "$WS/notes/README.md" << 'EOF'
# Notes Directory

Organized notes and tracking files.

- `daily-reviews/` — Daily review logs
- `decisions/` — Important decisions made
- `cost-tracking.md` — Subagent cost tracking
EOF

cat > "$WS/docs/README.md" << 'EOF'
# Documentation

Project documentation, guides, and references.
EOF

cat > "$WS/scripts/README.md" << 'EOF'
# Scripts

Utility scripts for workspace maintenance and automation.
EOF

echo "✓ Directory structure created"
echo "✓ Placeholder files added"
echo ""
echo "Workspace structure:"
echo "  projects/     - Active work (writing, code)"
echo "  notes/        - Organized notes and tracking"
echo "  memory/       - Long-term memory storage"
echo "  skills/       - Custom skills"
echo "  subagents/    - Permanent specialists"
echo "  docs/         - Documentation"
echo "  scripts/      - Utility scripts"
echo ""
echo "Run ./maintenance-audit.sh for health check."


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)