workspace-health-monitor

Performs comprehensive workspace health checks including disk usage, file counts, skill health, large files, and empty directories with actionable recommenda...

Security Scan

The skill's code, README, and runtime behavior are coherent with a workspace health checker: it only reads the filesystem, makes no network calls, and requests no credentials or installs.

Purpose & Capability

The name/description match the code and SKILL.md: functions compute disk usage, file counts, large files, empty directories, and skill health. The required capabilities (filesystem read access to a provided workspace path) are proportionate to the stated purpose.

Instruction Scope

The SKILL.md and index.js instruct the agent to recursively read the provided workspace path and report file names, sizes, and skill directory contents. This is expected, but it means the skill will enumerate any directory you point it at (including potentially sensitive files if you run it at root or on a home directory). Also note minor inconsistencies in examples: SKILL.md shows require('./skills/workspace-health-monitor') while code lives in index.js at the package root, and package.json's test script calls a .main() that is not obviously defined in the provided index.js (truncated file prevents 100% confirmation).

Install Mechanism

No install spec; the skill is instruction+code only and does not download or install external packages. This lowers the installation risk.

Credentials

The skill requests no environment variables or credentials and accesses no config paths. Its filesystem reads are limited to the workspace path supplied at runtime, which is appropriate for its function.

Persistence & Privilege

always is false and the skill does not request persistent system-wide changes. It does not modify other skills or system configuration.

Assessment

This skill appears to be what it claims: a read-only workspace health checker. Before running it: - Run it only against the intended workspace path (avoid using '/' or your entire home directory) because it will recursively enumerate filenames and sizes and could surface sensitive files. - Expect blocking synchronous filesystem I/O on large trees; run in a container or with appropriate timeouts if needed. - Be aware of small documentation mismatches: the SKILL.md example path and package.json test may not match how the module is actually exported; test locally first to confirm the exported API before using it in automation. - Because the agent can output the collected report, treat that output as potentially sensitive and avoid sending it to untrusted remote endpoints.

Performs comprehensive workspace health checks and generates actionable recommendations.

Usage

const monitor = require('./skills/workspace-health-monitor');

// Perform health check
const report = monitor.check('/path/to/workspace');

// Generate markdown report
console.log(monitor.generateReport(report));

API

check(workspacePath, options)

Performs comprehensive workspace health check.

Options:

• largeFileThresholdMB (number): Size threshold for large files. Default: 10
• includeEmptyDirs (boolean): Check for empty directories. Default: true
• includeLargeFiles (boolean): Check for large files. Default: true

Returns:

{
  healthScore: number,      // 0-100
  status: 'healthy' | 'warning' | 'critical',
  metrics: {
    timestamp: string,
    workspace: string,
    diskUsage: {
      totalSize: number,
      totalSizeMB: number,
      totalSizeFormatted: string
    },
    files: {
      total: number,
      directories: number
    },
    skills: {
      total: number,
      healthy: number,
      broken: number,
      missingIndex: string[],
      missingSkillMd: string[],
      missingPackage: string[]
    },
    largeFiles: [{ path, size, sizeFormatted }],
    emptyDirs: string[],
    fileTypes: { [extension]: count }
  },
  recommendations: [{
    severity: 'high' | 'medium' | 'low' | 'info',
    category: string,
    message: string,
    details?: string,
    action: string
  }]
}

checkSkillHealth(skillsDir)

Checks health of all skills in a directory.

findLargeFiles(workspacePath, thresholdMB)

Finds files larger than the threshold.

findEmptyDirectories(workspacePath)

Finds empty directories in the workspace.

generateReport(report)

Generates a markdown-formatted health report.

formatBytes(bytes)

Formats bytes to human-readable size.

Example Output

# Workspace Health Report

**Status:** ✅ HEALTHY (Score: 92/100)
**Timestamp:** 2026-03-27T04:30:00.000Z

## Disk Usage

- **Total Size:** 256.78 MB
- **Files:** 3,456
- **Directories:** 234

## Skills Health

- **Total Skills:** 150
- **Healthy:** 145
- **Broken:** 5
- **Missing index.js:** skill-a, skill-b, skill-c

## Large Files (>10MB)

- `logs/evolution.log` (45.23 MB)
- `data/cache.json` (23.45 MB)

## Recommendations

🔴 **skills**: 5 broken skill(s) found
  - Missing index.js: skill-a, skill-b, skill-c
  - Action: Fix or remove broken skills

🟡 **storage**: 2 large file(s) found (>10MB)
  - logs/evolution.log (45.23 MB), data/cache.json (23.45 MB)
  - Action: Consider archiving or removing large files

Health Score Calculation

The health score (0-100) is calculated based on:

• Broken skills: -30 points max for broken skill ratio
• Large files: -10 points for >10 large files
• Empty directories: -10 points for >20 empty directories
• Workspace size: -10 points for >1GB total size

Status Levels

• Healthy (80-100): Workspace is in good condition
• Warning (60-79): Some issues need attention
• Critical (0-59): Immediate action required