SKILL.md

Disk Cleaner Skill - Complete Feature Guide for All Agents

🚨 IMPORTANT: Emoji Usage Policy

For Script Output (Cross-Platform Safety)

NEVER use emoji in script output - All scripts use ASCII-safe characters

Scripts use: [OK], [X], [!], [*], [i], [DIR], [FILE], [PKG], [x]

This ensures compatibility with Windows GBK and other non-UTF-8 consoles

DO NOT modify script output to add emoji - This will break cross-platform compatibility

For Agent-to-Human Communication (Recommended)

SHOULD use emoji when reporting results to humans - Makes output more readable

Use these emoji in your final reports to users:

✅ (Success) - Completed operations, successful scans

❌ (Error) - Failed operations, critical errors

⚠️ (Warning) - Warnings, issues that need attention

🔍 (Scanning) - Search/scan operations

📊 (Statistics) - Analysis results, statistics

📁 (Directory) - Directory-related information

📦 (Package) - Package/module information

🎉 (Success) - Celebratory messages for successful completion

🚨 (Critical) - Critical warnings

💡 (Tip) - Suggestions, recommendations

📋 (List) - Checklists, summaries

🔧 (Tool) - Tools, utilities

🌐 (Global) - Cross-platform, universal features

🛡️ (Safety) - Safety-related information

⚡ (Performance) - Performance improvements

📝 (Document) - Documentation

🎓 (Learning) - Educational content

📞 (Support) - Help, support information

📈 (Growth) - Improvements, gains

🎯 (Target) - Goals, objectives

🚀 (Launch) - Quick start, fast operations

🛠️ (Tools) - Tool-related features

Example:

Script output (ASCII):    [OK] Scan completed: 50,000 files in 30 seconds

Your report to human:     ✅ Scan completed successfully! Found 50,000 files in 30 seconds

📦 COMPLETE FEATURE LIST (READ THIS FIRST!)

🚨 CRITICAL: Progressive Scanning (MANDATORY for Large Disks)

✅ Quick Sample Mode: 1-second estimation of disk size and scan time

✅ Progressive Scan Mode: Get partial results in 30 seconds for large disks

✅ Smart Time Limits: Prevent users from waiting hours

✅ Real-time Feedback: Progress updates every 2 seconds

✅ Interruptible: Ctrl+C to get partial results

🔧 Intelligent Bootstrap (Auto-Detection & Import)

✅ Auto Location Detection: Searches 20+ common skill package locations

✅ Environment Variable Support: DISK_CLEANER_SKILL_PATH override

✅ Auto Module Import: Automatically imports diskcleaner modules

✅ Fallback Mechanisms: Works even if some features unavailable

✅ Cross-Platform Python Detection: Tries both 'python' and 'python3'

🌐 Universal Compatibility

✅ All AI IDEs: Cursor, Windsurf, Continue, Aider, Claude Code, etc.

✅ All Platforms: Windows, macOS, Linux (including Windows GBK console)

✅ All Installation Levels: Global, project, user level

✅ No Configuration Needed: Works out of the box

✅ Cross-Platform Encoding: All scripts use ASCII-safe output (v2.0+)

🛡️ Safety & Reliability

✅ Diagnostic Tool: check_skill.py - verifies all functionality

✅ Safe Encoding: All scripts use ASCII characters (no emoji in output)

✅ Safe Defaults: --dry-run for cleaning, smart limits for scanning

✅ Protected Paths: Never deletes system directories or executables

✅ Error Handling: Graceful degradation on errors

✅ GBK/UTF-8 Compatible: Works on Windows GBK, UTF-8, and all other encodings

⚡ Performance Optimizations (ALL INCLUDED)

✅ QuickProfiler: Fast sampling to estimate scan characteristics

✅ ConcurrentScanner: Multi-threaded I/O for 3-5x speedup

✅ os.scandir() Optimization: 3-5x faster than Path.glob

✅ IncrementalCache: Cache scan results for faster repeat scans

✅ Memory Monitoring: Auto-adapts based to available memory

✅ Early Stopping: Configurable file/time limits

✅ Enhanced Cache Detection: 26+ cache paths (was 8) - 225% improvement

🆕 v2.2+ New Features

✅ Duplicate File Detection: Find and remove duplicate files with adaptive strategies

✅ Growth Trend Analysis: Track disk usage over time, predict when disk will be full

✅ Interactive Wizard: Step-by-step guided cleanup with safety confirmations

✅ File Organization: Intelligent file archival and organization (4 strategies)

✅ Enhanced Scan Limits: 500K files (was 50K), 120s timeout (was 30s)

✅ Deep Scan Mode: --deep-scan for unlimited scanning

✅ Windows Directory Support: --include-windows for system directory scanning

📊 Available Scripts (13+ Total)

Core Analysis:

analyze_disk.py - Disk analysis with smart sampling (enhanced v2.2)

analyze_progressive.py - Progressive scanning for large disks

find_duplicates.py - Duplicate file detection (NEW v2.2)

analyze_growth.py - Growth trend analysis (NEW v2.2)

Cleaning & Organization:

clean_disk.py - Safe junk file cleaning (enhanced cache detection)
interactive_wizard.py - Interactive guided cleanup (NEW v2.2)
organize_files.py - File archival and organization (NEW v2.2)

Monitoring & Diagnostics:

monitor_disk.py - Disk usage monitoring
check_skill.py - Diagnostic tool

Developer Tools:

skill_bootstrap.py - Intelligent bootstrap module
package_skill.py - Package creation tool
scheduler.py - Automated scheduling

🚀 Multi-Agent Acceleration (CRITICAL FOR PERFORMANCE)

🎯 KEY INSIGHT: Use Sub-Agents for Parallel Processing

This is one of the MOST POWERFUL features of disk-cleaner when used by AI Agents!

#### Why Use Multiple Agents?

Single-threaded scanning:

Agent scans → [Dir1] → [Dir2] → [Dir3] → ... (sequential, slow)

Multi-Agent parallel scanning:

Main Agent

  ├─ Sub-Agent-1 scans → [Dir1, Dir2, Dir3] (parallel)

  ├─ Sub-Agent-2 scans → [Dir4, Dir5, Dir6] (parallel)

  └─ Sub-Agent-3 scans → [Dir7, Dir8, Dir9] (parallel)

Result: 3-10x faster! ⚡

#### When to Use Multi-Agent Mode?

✅ ALWAYS use when:

Scanning multiple top-level directories (e.g., C:, D:, E:)

Cleaning multiple user profiles

Processing large file sets (>100K files)

Time-critical operations

❌ Don't use when:

Single small directory (<10K files)

Quick analysis (<30 seconds)

Simple cleanup tasks

#### How to Implement Multi-Agent Scanning

Option 1: Use Agent Tool (Recommended for Claude Code)

# Agent code that spawns sub-agents

from anthropic import Anthropic

def parallel_scan_directories(directories_list):

    """

    Scan multiple directories in parallel using sub-agents

    """

    # Split directories among sub-agents (3-5 agents optimal)

    chunks = split_list(directories_list, n_chunks=3)

    # Launch sub-agents in parallel

    agents = []

    for i, chunk in enumerate(chunks):

        agent = Anthropic().agent.create(

            name=f"scanner-{i}",

            instructions=f"""

            Scan these directories: {chunk}

            Use disk-cleaner with: --file-limit 50000 --time-limit 60

            Return results in JSON format

            """,

            model="claude-sonnet-4-20250514"  # Fast model

        )

        agents.append(agent)

    # Wait for all agents and collect results

    results = [agent.wait() for agent in agents]

    return merge_results(results)

Option 2: Parallel Subprocess (Platform Independent)

import subprocess

from concurrent.futures import ThreadPoolExecutor, as_completed

def parallel_scan_subprocess(directories_list):

    """

    Scan multiple directories using parallel subprocess calls

    Works with ALL AI IDEs that support subprocess

    """

    def scan_directory(directory):

        """Scan a single directory"""

        cmd = [

            'python',

            'skills/disk-cleaner/scripts/analyze_disk.py',

            '--path', str(directory),

            '--file-limit', '50000',

            '--json'

        ]

        result = subprocess.run(cmd, capture_output=True, text=True)

        return json.loads(result.stdout)

    # Use 3-5 parallel workers

    with ThreadPoolExecutor(max_workers=4) as executor:

        futures = {

            executor.submit(scan_directory, d): d

            for d in directories_list

        }

        results = {}

        for future in as_completed(futures):

            directory = futures[future]

            try:

                results[directory] = future.result()

            except Exception as e:

                results[directory] = {"error": str(e)}

    return results

# Usage: Scan C:\, D:\, E:\ in parallel

directories = ['C:\\', 'D:\\', 'E:\\']

results = parallel_scan_subprocess(directories)

Option 3: Multi-Platform Agent Team (Advanced)

For Agent-capable systems (Claude Code, Cursor with Agent support):

# Create agent team for massive parallelism

def create_agent_team_scan(top_level_paths):

    """

    Create a team of sub-agents, each handling a portion of the work

    """

    team_config = {

        "name": "disk-cleaner-team",

        "members": [

            {

                "name": "scanner-1",

                "task": f"Scan {top_level_paths[0]} using progressive mode",

                "tool_use": "subprocess"

            },

            {

                "name": "scanner-2",

                "task": f"Scan {top_level_paths[1]} using progressive mode",

                "tool_use": "subprocess"

            },

            {

                "name": "scanner-3",

                "task": f"Scan {top_level_paths[2]} using progressive mode",

                "tool_use": "subprocess"

            }

        ],

        "coordination": "parallel",  # All run at once

        "aggregation": "merge_results"  # Combine results at end

    }

    return launch_agent_team(team_config)

#### Performance Comparison

Scenario

Single Agent

3 Sub-Agents

Speedup

3 disks (1TB each)

~15 minutes

~5 minutes

10 user profiles

~20 minutes

~4 minutes

1M files

~30 minutes

~6 minutes

Cache cleanup (26 locations)

~8 minutes

~2 minutes

#### Recommended Agent Count

Small job (<50K files): 1 agent (not worth overhead)

Medium job (50K-500K files): 2-3 agents

Large job (500K-2M files): 3-5 agents

Massive job (>2M files): 5-8 agents

Sweet spot: 3-4 agents (best balance of speed vs overhead)

#### Best Practices

Divide work logically: By disk, by user profile, by directory type

Use consistent parameters: All agents use same scan limits

Merge results carefully: Deduplicate, sort, format

Handle failures gracefully: If one agent fails, continue others

Monitor progress: Track which agents completed

⚠️ IMPORTANT: Not all AI IDEs support sub-agents. Fall back to parallel subprocess if unavailable.

📚 Documentation (Essential Files Only)

SKILL.md - This complete guide (READ THIS FIRST)

README.md - Project overview and quick start

README_zh.md - Chinese documentation

CHANGELOG.md - Version history and changes

AGENT_QUICK_REF.txt - One-page reference for agents

INSTALL.md - Detailed installation guide

NO_PYTHON_GUIDE.md - Help for users without Python

references/temp_locations.md - Platform-specific cache locations

🎯 AGENT CHECKLIST (Must Follow)

For ANY Disk Analysis Request:

[ ] STEP 1: Check Python availability

[ ] STEP 2: Find skill package (auto-detects 20+ locations)

[ ] STEP 3: Run diagnostics: python scripts/check_skill.py

[ ] STEP 4: Run quick sample: --sample (MANDATORY - do this FIRST)

[ ] STEP 5: Choose scan mode based on estimate

[ ] STEP 6: Inform user of expected time

[ ] STEP 7: Execute scan with appropriate limits

[ ] STEP 8: Show results and offer next steps

For ANY Clean Request:

[ ] STEP 1-3: Same as above

[ ] STEP 4: ALWAYS use --dry-run first (MANDATORY)

[ ] STEP 5: Show preview results

[ ] STEP 6: Ask user confirmation before --force

[ ] STEP 7: Execute actual cleaning if confirmed

⚡ PROGRESSIVE SCANNING (CRITICAL FOR LARGE DISKS)

🚨 CRITICAL INFORMATION (Read First)

Universal Compatibility

✅ Works with ALL AI IDEs: Cursor, Windsurf, Continue, Aider, Claude Code, etc.

✅ Platform Independent: Windows, macOS, Linux

✅ Installation Agnostic: Works at global, project, or user level

✅ Self-Contained: No external dependencies, just Python 3.7+

The Only Requirement

import subprocess

result = subprocess.run(['python', '--version'], capture_output=True, text=True)

# If this succeeds, you can use this skill

⚡ PROGRESSIVE SCANNING (CRITICAL FOR LARGE DISKS)

🚨 AGENT MUST USE FOR LARGE DISKS (>100GB)

Problem: Full disk scan on large disks (500GB+) can take HOURS. Users will lose patience.

Solution: Use progressive scanning - get results in seconds, not hours!

📋 Three Scanning Modes

#### Mode 1: Quick Sample (⚡ FASTEST - 1 Second)

When to use: Get instant estimate of directory size and scan time

python scripts/analyze_disk.py --sample

# OR

python scripts/analyze_progressive.py --sample

Output:

{

  "sample_file_count": 7591,

  "sample_size_gb": 17.62,

  "files_per_second": 7501.0,

  "estimated_time_seconds": 2.0

}

Agent Decision Logic:

# ALWAYS run quick sample first for unknown disk sizes

result = subprocess.run(

    ['python', 'scripts/analyze_disk.py', '--sample', '--json'],

    capture_output=True,

    text=True,

    timeout=10,

    cwd=skill_path

)

import json

sample = json.loads(result.stdout)

estimated_time = sample.get('estimated_time_seconds', 0)

# Choose next action based on estimate

if estimated_time < 30:

    mode = 'full'  # Full scan is fine

elif estimated_time < 120:

    mode = 'time_limited'  # Use time limit

else:

    mode = 'progressive'  # MUST use progressive mode

#### Mode 2: Progressive Scan (🎯 RECOMMENDED FOR LARGE DISKS)

When to use: Get partial results in 30 seconds for large disks

python scripts/analyze_progressive.py --max-seconds 30

Features:

✅ Real-time progress updates every 2 seconds

✅ Shows partial results as they're discovered

✅ Can interrupt with Ctrl+C and keep results

✅ Smart file count limit (50,000 by default)

Agent Usage:

def analyze_large_disk_safely(path, max_seconds=30):

    """Safely analyze large disk with time limit"""

    result = subprocess.run(

        ['python', 'scripts/analyze_progressive.py',

         '--max-seconds', str(max_seconds),

         '--path', str(path)],

        capture_output=True,

        text=True,

        timeout=max_seconds + 10,

        cwd=skill_path

    )

    return result.stdout

#### Mode 3: Limited Scan (📊 FAST RESULTS)

When to use: Get results quickly with file/time limits

# Limit by file count (fast)

python scripts/analyze_disk.py --file-limit 10000

# Limit by time (safe)

python scripts/analyze_disk.py --time-limit 30

# Both limits (very fast)

python scripts/analyze_disk.py --file-limit 10000 --time-limit 30

🎯 AGENT DECISION TREE (CRITICAL - FOLLOW THIS)

USER REQUEST: "Analyze my disk"

    ↓

┌─────────────────────────────────────────┐

│ STEP 1: Quick Sample (MANDATORY)          │

│ python scripts/analyze_disk.py --sample │

└─────────────────────────────────────────┘

    ↓

    Get estimated_time from sample

    ↓

    ├─ estimated_time < 30 seconds

    │   ↓

    │   ✅ Use FULL SCAN

    │   python scripts/analyze_disk.py

    │

    ├─ estimated_time 30-120 seconds

    │   ↓

    │   ⚠️ Use TIME LIMIT

    │   python scripts/analyze_disk.py --time-limit 60

    │   Tell user: "This will take ~X minutes"

    │

    └─ estimated_time > 120 seconds

        ↓

        🚨 MUST USE PROGRESSIVE MODE

        python scripts/analyze_progressive.py --max-seconds 30

        Tell user: "Large disk detected - using progressive scan (30 seconds)"

📝 Required Response Templates

#### When Quick Sample Shows 120 Seconds

🚨 Large disk detected! Full scan would take approximately 5 minutes

Using progressive scan mode to get results in 30 seconds...

(This gives you partial results quickly - you can always do a full scan later)

💡 COPY-PASTE CODE (USE THIS)

import subprocess

import json

from pathlib import Path

def smart_disk_analysis(disk_path, python_cmd='python'):

    """

    SMART disk analysis - automatically chooses best method

    THIS IS THE RECOMMENDED WAY for all agents

    """

    # Find skill package

    skill_path = find_skill_package()  # Use your find function

    if not skill_path:

        return False, "Skill package not found"

    # STEP 1: Quick sample (MANDATORY - do this first!)

    print("🔍 Quick sampling disk...")

    sample_result = subprocess.run(

        [python_cmd, 'scripts/analyze_disk.py', '--sample',

         '--path', str(disk_path), '--json'],

        capture_output=True,

        text=True,

        timeout=10,

        cwd=str(skill_path)

    )

    if sample_result.returncode != 0:

        return False, "Sample failed"

    try:

        sample = json.loads(sample_result.stdout)

        estimated_time = sample.get('estimated_time_seconds', 0)

    except:

        estimated_time = 0

    print(f"   Estimated scan time: {estimated_time:.0f} seconds")

    # STEP 2: Choose scanning method based on estimate

    if estimated_time < 30:

        # Small disk - full scan

        print("✅ Using full scan (small disk)")

        result = subprocess.run(

            [python_cmd, 'scripts/analyze_disk.py',

             '--path', str(disk_path)],

            capture_output=True,

            text=True,

            timeout=60,

            cwd=str(skill_path)

        )

    elif estimated_time < 120:

        # Medium disk - time limited

        minutes = estimated_time / 60

        print(f"⚠️  Using time-limited scan (~{minutes:.1f} minutes)")

        result = subprocess.run(

            [python_cmd, 'scripts/analyze_disk.py',

             '--path', str(disk_path),

             '--time-limit', '60'],  # 1 minute max

            capture_output=True,

            text=True,

            timeout=70,

            cwd=str(skill_path)

        )

    else:

        # Large disk - PROGRESSIVE MODE (MANDATORY)

        print(f"🚨 Large disk detected! Using progressive scan (30 seconds)")

        result = subprocess.run(

            [python_cmd, 'scripts/analyze_progressive.py',

             '--path', str(disk_path),

             '--max-seconds', '30',

             '--json'],

            capture_output=True,

            text=True,

            timeout=40,

            cwd=str(skill_path)

        )

    if result.returncode != 0:

        return False, result.stderr

    print(result.stdout)

    return True, result.stdout

# USAGE - Just call this function:

success, output = smart_disk_analysis("C:\\")

success, output = smart_disk_analysis("/home/user")

success, output = smart_disk_analysis("D:\\Projects")

⚠️ COMMON MISTAKES TO AVOID

❌ DON'T: Always run full scan without checking disk size first

✅ DO: Always run --sample first to estimate

❌ DON'T: Let users wait hours for large disk scan

✅ DO: Use --max-seconds 30 for large disks

❌ DON'T: Ignore estimated time from sample

✅ DO: Use estimate to choose appropriate scan mode

❌ DON'T: Run analyze_disk.py on 1TB disk without limits

✅ DO: Use analyze_progressive.py with --max-seconds

📊 Command Reference Card

Situation

Command

Time

Result

Unknown size

--sample

Estimate + recommendation

< 30 seconds

analyze_disk.py

<30s

Full results

30-120 seconds

--time-limit 60

60s

Most results

120 seconds

analyze_progressive.py --max-seconds 30

30s

Partial results

Very large disk

analyze_progressive.py --max-seconds 60

60s

More results

🔍 How Progressive Scan Works

Quick Sample (1 second)

Scans as many files as possible in 1 second

Calculates scan rate (files/second)

Estimates total scan time

Gives immediate feedback

Progressive Scan (N seconds)

Scans continuously for N seconds

Shows progress every 2 seconds

Collects results as it goes

Returns whatever it found when time is up

User can interrupt and keep partial results

Smart Stopping

Stops automatically when time/file limit reached

Graceful handling of interruption

Partial results are still useful

🎯 BEST PRACTICE FOR AGENTS

ALWAYS run --sample first

ALWAYS check estimated_time before choosing mode

ALWAYS inform user about expected scan time

ALWAYS use progressive mode for large disks (>2 minutes)

NEVER let users wait more than 2 minutes without feedback

🎯 UNIVERSAL AGENT WORKFLOW

This workflow works on ANY platform, in ANY AI IDE, at ANY location.

STEP 1: Verify Python

import subprocess

import sys

def verify_python():

    """Check if Python 3.7+ is available - PLATFORM AGNOSTIC"""

    try:

        # Try 'python' first (Windows, some Unix)

        result = subprocess.run(

            ['python', '--version'],

            capture_output=True,

            text=True,

            timeout=5

        )

        if result.returncode == 0:

            return True, result.stderr.strip() or result.stdout.strip()

    except FileNotFoundError:

        pass

    try:

        # Try 'python3' (macOS, Linux)

        result = subprocess.run(

            ['python3', '--version'],

            capture_output=True,

            text=True,

            timeout=5

        )

        if result.returncode == 0:

            return True, result.stderr.strip() or result.stdout.strip()

    except FileNotFoundError:

        pass

    return False, "Python not found"

# EXECUTE

python_available, version_info = verify_python()

if not python_available:

    print("❌ Python 3.7+ required but not found")

    print("Install from: https://www.python.org/downloads/")

    print("See: NO_PYTHON_GUIDE.md for platform-specific instructions")

    sys.exit(1)

print(f"✅ Python available: {version_info}")

STEP 2: Locate Skill Package

from pathlib import Path

import os

def find_skill_package():

    """

    Find disk-cleaner skill package - LOCATION INDEPENDENT

    Searches in order of priority:

    1. Current working directory

    2. Project-level: ./skills/, ./.skills/, ./agent-skills/

    3. User-level: ~/.skills/, ~/.agent-skills/, ~/skill-packages/

    4. Common AI IDE locations

    5. Parent directories

    """

    # Get python command (python or python3)

    python_cmd = 'python' if os.name == 'nt' else 'python3'

    # Search locations - PLATFORM &#x26; IDE AGNOSTIC

    search_locations = []

    # 1. Current directory

    cwd = Path.cwd()

    search_locations.extend([

        cwd / 'disk-cleaner',

        cwd / 'skills' / 'disk-cleaner',

        cwd / '.skills' / 'disk-cleaner',

        cwd / 'agent-skills' / 'disk-cleaner',

        cwd / '.agent-skills' / 'disk-cleaner',

    ])

    # 2. Parent directories (project root)

    for parent in [cwd, *cwd.parents]:

        search_locations.extend([

            parent / 'skills' / 'disk-cleaner',

            parent / '.skills' / 'disk-cleaner',

            parent / 'agent-skills' / 'disk-cleaner',

        ])

        # Limit search depth

        if len(parent.parts) <= 3:

            break

    # 3. User home directory

    home = Path.home()

    search_locations.extend([

        home / 'skills' / 'disk-cleaner',

        home / '.skills' / 'disk-cleaner',

        home / 'agent-skills' / 'disk-cleaner',

        home / '.agent-skills' / 'disk-cleaner',

        home / 'skill-packages' / 'disk-cleaner',

    ])

    # 4. Platform-specific user directories

    if os.name == 'nt':  # Windows

        appdata = os.environ.get('APPDATA', '')

        if appdata:

            search_locations.append(Path(appdata) / 'skills' / 'disk-cleaner')

        localappdata = os.environ.get('LOCALAPPDATA', '')

        if localappdata:

            search_locations.append(Path(localappdata) / 'skills' / 'disk-cleaner')

    else:  # Unix-like (macOS, Linux)

        search_locations.extend([

            home / '.local' / 'share' / 'skills' / 'disk-cleaner',

            home / '.config' / 'skills' / 'disk-cleaner',

            Path('/usr/local/share/skills/disk-cleaner'),

        ])

    # 5. AI IDE specific directories (IDE-AGNOSTIC)

    # Note: These are examples - actual locations vary

    ide_specific = [

        # Cursor

        home / '.cursor' / 'skills' / 'disk-cleaner',

        home / '.cursor' / 'user' / 'skills' / 'disk-cleaner',

        # Windsurf

        home / '.windsurf' / 'skills' / 'disk-cleaner',

        # Continue

        home / '.continue' / 'skills' / 'disk-cleaner',

        # Generic

        home / '.ai-ide' / 'skills' / 'disk-cleaner',

    ]

    search_locations.extend(ide_specific)

    # 6. sys.path entries (Python module style)

    for path_entry in sys.path:

        if path_entry and path_entry not in ['', '.']:

            test_path = Path(path_entry) / 'disk-cleaner'

            search_locations.append(test_path)

    # Remove duplicates and non-existent

    search_locations = list(set(search_locations))

    # Search for valid skill package

    for location in search_locations:

        if not location:

            continue

        try:

            # Check for key indicator files

            if (location / 'scripts' / 'analyze_disk.py').exists():

                return location, f"Found at: {location}"

            if (location / 'SKILL.md').exists():

                return location, f"Found at: {location}"

        except PermissionError:

            continue

        except Exception:

            continue

    # Not found - provide helpful message

    print("❌ Skill package not found")

    print("\nSearched locations:")

    for loc in search_locations[:10]:  # Show first 10

        print(f"  - {loc}")

    print("\nSolutions:")

    print("1. Extract skill package to one of the locations above")

    print("2. Or set environment variable: DISK_CLEANER_SKILL_PATH")

    print("3. Or provide explicit path when calling functions")

    return None, "Not found"

# EXECUTE

skill_path, message = find_skill_package()

if not skill_path:

    print(message)

    sys.exit(1)

print(f"✅ {message}")

STEP 3: Verify Skill Package

def verify_skill_package(skill_path, python_cmd='python'):

    """Verify skill package integrity - LOCATION INDEPENDENT"""

    check_script = skill_path / 'scripts' / 'check_skill.py'

    if not check_script.exists():

        print(f"❌ Check script not found: {check_script}")

        return False

    try:

        result = subprocess.run(

            [python_cmd, str(check_script)],

            capture_output=True,

            text=True,

            timeout=30,

            cwd=str(skill_path)

        )

        # Show verification output

        if result.stdout:

            print(result.stdout)

        if result.returncode == 0:

            print("✅ Skill package verified successfully")

            return True

        else:

            print("❌ Skill package verification failed")

            if result.stderr:

                print(result.stderr)

            return False

    except subprocess.TimeoutExpired:

        print("❌ Verification timed out")

        return False

    except Exception as e:

        print(f"❌ Verification error: {e}")

        return False

# Determine python command

python_cmd = 'python' if os.name == 'nt' else 'python3'

# EXECUTE

if not verify_skill_package(skill_path, python_cmd):

    sys.exit(1)

STEP 4: Execute Operation

def execute_operation(skill_path, operation, python_cmd='python', **kwargs):

    """

    Execute disk cleaner operation - PLATFORM &#x26; IDE AGNOSTIC

    Args:

        skill_path: Path to skill package

        operation: 'analyze', 'clean', 'monitor'

        python_cmd: 'python' or 'python3'

        **kwargs: Operation-specific arguments

    """

    operation_map = {

        'analyze': 'analyze_disk.py',

        'clean': 'clean_disk.py',

        'monitor': 'monitor_disk.py',

    }

    if operation not in operation_map:

        print(f"❌ Unknown operation: {operation}")

        print(f"Valid operations: {list(operation_map.keys())}")

        return False, None

    script = skill_path / 'scripts' / operation_map[operation]

    cmd = [python_cmd, str(script)]

    # Add operation-specific arguments

    if operation == 'analyze':

        if kwargs.get('path'):

            cmd.extend(['--path', str(kwargs['path'])])

        if kwargs.get('top'):

            cmd.extend(['--top', str(kwargs['top'])])

        if kwargs.get('json'):

            cmd.append('--json')

    elif operation == 'clean':

        # ALWAYS use dry-run for safety

        if not kwargs.get('force'):

            cmd.append('--dry-run')

        else:

            cmd.append('--force')

        if kwargs.get('temp'):

            cmd.append('--temp')

        if kwargs.get('cache'):

            cmd.append('--cache')

        if kwargs.get('logs'):

            cmd.append('--logs')

    elif operation == 'monitor':

        if kwargs.get('watch'):

            cmd.append('--watch')

        if kwargs.get('json'):

            cmd.append('--json')

    try:

        print(f"🔧 Executing: {' '.join(cmd)}")

        result = subprocess.run(

            cmd,

            capture_output=True,

            text=True,

            timeout=kwargs.get('timeout', 300),

            cwd=str(skill_path)

        )

        # Show output

        if result.stdout:

            print(result.stdout)

        if result.returncode != 0:

            if result.stderr:

                print(f"❌ Error: {result.stderr}")

            return False, None

        return True, result.stdout

    except subprocess.TimeoutExpired:

        print("⚠️ Operation timed out")

        return False, None

    except Exception as e:

        print(f"❌ Execution error: {e}")

        return False, None

# EXECUTE

success, output = execute_operation(

    skill_path,

    operation='analyze',

    python_cmd=python_cmd,

    path='C:\\Users' if os.name == 'nt' else '/home',

    json=True

)

if success:

    print("✅ Operation completed successfully")

📋 QUICK REFERENCE (All IDEs)

⚠️ CRITICAL: Use Progressive Scanning for Large Disks!

BEFORE ANY DISK ANALYSIS:

Run --sample first to estimate scan time

If > 2 minutes estimated, use progressive mode

NEVER let users wait more than 2 minutes without feedback

Quick Reference:

# STEP 1: ALWAYS DO THIS FIRST (1 second)

python scripts/analyze_disk.py --sample

# STEP 2: Choose based on estimate

# < 30s: python scripts/analyze_disk.py

# 30-120s: python scripts/analyze_disk.py --time-limit 60

# > 120s: python scripts/analyze_progressive.py --max-seconds 30

User Intent → Operation Mapping

User Says

Operation

Command Template

"analyze disk"

analyze

python scripts/analyze_disk.py

"check disk space"

analyze

python scripts/analyze_disk.py --top 50

"quick scan"

analyze

python scripts/analyze_disk.py --sample

"large disk analysis"

analyze

python scripts/analyze_progressive.py --max-seconds 30

"clean temp files"

clean

python scripts/clean_disk.py --temp --dry-run

"preview cleanup"

clean

python scripts/clean_disk.py --dry-run

"monitor disk"

monitor

python scripts/monitor_disk.py

"disk usage"

monitor

python scripts/monitor_disk.py --json

Progressive Scanning (For Large Disks)

Problem: Full disk scan can take hours on large disks (1TB+)

Solution: Use progressive scanning with time/file limits

# Quick sample (1 second) - Get instant estimate

subprocess.run(['python', 'scripts/analyze_disk.py', '--sample'])

# Progressive scan (30 seconds) - Get partial results quickly

subprocess.run(['python', 'scripts/analyze_progressive.py',

                 '--max-seconds', '30'])

# Limited file count (fast)

subprocess.run(['python', 'scripts/analyze_disk.py',

                 '--file-limit', '10000'])

# Full scan with time limit

subprocess.run(['python', 'scripts/analyze_disk.py',

                 '--time-limit', '120'])

Recommended workflow for large disks:

First, run --sample to get estimate (1 second)

If estimate is too long, use --max-seconds or --file-limit

Or use analyze_progressive.py for real-time feedback

Cross-Platform Python Commands

Platform

Python Command

Check Command

Windows

python

python --version

macOS

python3

python3 --version

Linux

python3

python3 --version

Universal Command Template

# Works on ALL platforms

import os

import subprocess

python_cmd = 'python' if os.name == 'nt' else 'python3'

result = subprocess.run([python_cmd, '--version'], capture_output=True, text=True)

🌐 Multi-IDE Compatibility

This skill package works with ALL AI IDEs that support:

Supported AI IDEs

✅ Cursor - Works as project or user-level skill

✅ Windsurf - Works at any location

✅ Continue - Works as global or project skill

✅ Aider - Works as agent tool

✅ Claude Code - Works as skill

✅ Any AI IDE - Works via subprocess

Installation by IDE Type

#### Project-Level Installation

your-project/

├── skills/

│   └── disk-cleaner/    ← Extract here

├── src/

└── README.md

#### User-Level Installation

~/.skills/disk-cleaner/      ← Unix-like

~/agent-skills/disk-cleaner/ ← Alternative

C:\Users\You\skills\disk-cleaner\ ← Windows

#### Global Installation

/usr/local/share/skills/disk-cleaner/  ← Linux (system-wide)

C:\ProgramData\skills\disk-cleaner\   ← Windows (system-wide)

🔧 IDE-Specific Notes

Cursor

# Cursor automatically searches for skills in:

# - .cursor/skills/

# - project/skills/

# - ~/.skills/

# No special configuration needed

Windsurf

# Windsurf supports skills at:

# - .windsurf/skills/

# - project/skills/

# Skill works via subprocess, no special setup

Continue

# Continue configuration (if needed):

# {

#   "skills": ["./skills/disk-cleaner"]

# }

# But auto-detection works in most cases

Aider

# Use as a tool via subprocess:

# !python skills/disk-cleaner/scripts/analyze_disk.py

Generic/Other IDEs

# The skill includes intelligent auto-detection

# Just extract and use - no configuration needed

🎯 Complete Copy-Paste Template

"""

Universal Disk Cleaner Skill Usage

Works with ALL AI IDEs, on ALL platforms, at ANY location

"""

import subprocess

import sys

import os

from pathlib import Path

def use_disk_cleaner(operation='analyze', **kwargs):

    """

    Use disk cleaner skill - UNIVERSAL FUNCTION

    Works on:

    - All platforms (Windows, macOS, Linux)

    - All AI IDEs (Cursor, Windsurf, Continue, etc.)

    - All installation levels (global, project, user)

    Args:

        operation: 'analyze', 'clean', 'monitor'

        **kwargs: Operation-specific arguments

    Returns:

        (success: bool, output: str)

    """

    # 1. Determine Python command

    python_cmd = 'python' if os.name == 'nt' else 'python3'

    # 2. Verify Python

    try:

        result = subprocess.run(

            [python_cmd, '--version'],

            capture_output=True,

            text=True,

            timeout=5

        )

        if result.returncode != 0:

            print("❌ Python not found")

            return False, "Python 3.7+ required"

    except Exception as e:

        print(f"❌ Python check failed: {e}")

        return False, str(e)

    # 3. Find skill package (intelligent search)

    def find_skill():

        search_paths = [

            # Current directory

            Path.cwd() / 'disk-cleaner',

            Path.cwd() / 'skills' / 'disk-cleaner',

            Path.cwd() / '.skills' / 'disk-cleaner',

            # Project root

            *[(p / 'skills' / 'disk-cleaner') for p in [Path.cwd(), *Path.cwd().parents][:3]],

            # User home

            Path.home() / 'skills' / 'disk-cleaner',

            Path.home() / '.skills' / 'disk-cleaner',

        ]

        for path in search_paths:

            if (path / 'scripts' / 'analyze_disk.py').exists():

                return path

        return None

    skill_path = find_skill()

    if not skill_path:

        print("❌ Skill package not found")

        print("Extract to: skills/disk-cleaner/ or ~/.skills/disk-cleaner/")

        return False, "Skill package not found"

    # 4. Execute operation

    scripts = {

        'analyze': 'analyze_disk.py',

        'clean': 'clean_disk.py',

        'monitor': 'monitor_disk.py',

    }

    if operation not in scripts:

        return False, f"Unknown operation: {operation}"

    script = skill_path / 'scripts' / scripts[operation]

    cmd = [python_cmd, str(script)]

    # Add arguments

    if operation == 'analyze':

        if kwargs.get('path'):

            cmd.extend(['--path', str(kwargs['path'])])

    elif operation == 'clean':

        cmd.append('--dry-run')  # Always safe

    elif operation == 'monitor':

        if kwargs.get('json'):

            cmd.append('--json')

    # Run

    try:

        result = subprocess.run(

            cmd,

            capture_output=True,

            text=True,

            timeout=300,

            cwd=str(skill_path)

        )

        return result.returncode == 0, result.stdout

    except Exception as e:

        return False, str(e)

# USAGE EXAMPLES:

# success, output = use_disk_cleaner('analyze', path='.')

# success, output = use_disk_cleaner('clean')

# success, output = use_disk_cleaner('monitor', json=True)

if __name__ == "__main__":

    # Quick test

    success, output = use_disk_cleaner('analyze')

    print(output)

⚡ PROGRESSIVE SCANNING CHECKLIST (CRITICAL)

Agent MUST Follow This for All Disk Analysis Requests:

[ ] Did you run --sample FIRST to estimate scan time?

[ ] Did you inform user about expected scan time?

[ ] Did you choose appropriate mode based on estimate?

[ ] Did you use progressive mode for >2 minute estimates?

[ ] Did you provide feedback during long scans?

Required Behavior by Disk Size:

Small Disk (< 30 seconds estimated):

✅ Run full scan

✅ No special handling needed

Medium Disk (30-120 seconds estimated):

✅ Use --time-limit

✅ Inform user of expected time

⚠️ Consider progressive mode if user seems impatient

Large Disk (> 120 seconds estimated):

🚨 MUST USE PROGRESSIVE MODE

🚨 MUST Inform user about time limit

✅ Explain partial results

✅ Offer full scan as option

REQUIRED Code Pattern:

# THIS IS THE REQUIRED PATTERN for all disk analysis:

def safe_disk_analysis(disk_path):

    # Step 1: ALWAYS sample first

    sample = subprocess.run(

        ['python', 'scripts/analyze_disk.py', '--sample', '--json'],

        capture_output=True,

        text=True,

        cwd=skill_path

    )

    import json

    data = json.loads(sample.stdout)

    estimate = data.get('estimated_time_seconds', 0)

    # Step 2: Inform user

    if estimate > 120:

        print(f"Large disk detected! Estimated: {estimate/60:.1f} minutes")

        print("Using progressive scan (30 seconds) for quick results...")

    # Step 3: Choose mode

    if estimate < 30:

        # Full scan

        return subprocess.run(['python', 'scripts/analyze_disk.py'])

    elif estimate < 120:

        # Time limited

        return subprocess.run(['python', 'scripts/analyze_disk.py', '--time-limit', '60'])

    else:

        # Progressive (MANDATORY for large disks)

        return subprocess.run(['python', 'scripts/analyze_progressive.py', '--max-seconds', '30'])

🚨 Error Handling (Universal)

Error: Python not found

# SOLUTION - Platform-independent guidance

import platform

system = platform.system()

if system == "Windows":

    print("Install from: https://www.python.org/downloads/")

    print("Check 'Add Python to PATH' during installation")

elif system == "Darwin":  # macOS

    print("Install: brew install python@3.11")

    print("Or: https://www.python.org/downloads/macos/")

else:  # Linux

    print("Install: sudo apt install python3  # Debian/Ubuntu")

    print("Or: sudo dnf install python3      # Fedora")

Error: Skill not found

# SOLUTION - Show all searched locations

print("Skill package not found.")

print("Extract to ONE of these locations:")

print("  - ./skills/disk-cleaner/")

print("  - ./disk-cleaner/")

print("  - ~/.skills/disk-cleaner/")

print("  - project/skills/disk-cleaner/")

print("\nOr set: DISK_CLEANER_SKILL_PATH=/path/to/skill")

Error: Permission denied

# SOLUTION - Platform-specific advice

if os.name == 'nt':

    print("Run as Administrator if needed")

else:

    print("Some directories may require: sudo")

    print("Or adjust: chmod +x scripts/*.py")

📝 Environment Variables (Optional)

You can optionally set these to help with auto-detection:

# Set skill package location (overrides auto-detection)

export DISK_CLEANER_SKILL_PATH=/path/to/skills/disk-cleaner

# Set Python command (overrides auto-detection)

export DISK_CLEANER_PYTHON_CMD=python3

# Enable debug output

export DISK_CLEANER_DEBUG=true

🎓 Best Practices for All Agents

ALWAYS check Python first - Don't assume it's installed

Use 'python3' on Unix - Use 'python' on Windows

Search multiple locations - Don't assume single installation path

Use subprocess with timeout - Prevent hanging

Capture both stdout and stderr - Complete error information

Prefer --dry-run for clean - Safety first

Handle all exceptions - Graceful degradation

Show helpful error messages - Guide users to solutions

🔍 Troubleshooting (Universal)

Problem: Skill works in one IDE but not another

Solution: The skill is IDE-agnostic. Check:

Python is accessible from that IDE

Skill package is in a searchable location

File permissions allow execution

Problem: Different behavior on different platforms

Solution: The skill handles platform differences. Check:

Python command (python vs python3)

Path separators (auto-handled by pathlib)

File permissions (Unix may need chmod +x)

Problem: Can't find skill package

Solution: Run diagnostic:

python skills/disk-cleaner/scripts/check_skill.py

# Or

python3 skills/disk-cleaner/scripts/check_skill.py

📦 Package Contents (Universal)

disk-cleaner/

├── SKILL.md              # This file

├── AGENT_QUICK_REF.txt   # Quick reference

├── NO_PYTHON_GUIDE.md    # Help for users without Python

├── INSTALL.md            # Installation guide

├── FIXES.md              # What's fixed in v2.0

├── scripts/              # All scripts (universal)

├── diskcleaner/          # Core modules (self-contained)

└── references/           # Platform information

✅ Universal Checklist

Before using this skill in ANY AI IDE:

Python 3.7+ installed

Skill package extracted to accessible location

Can run: python --version (or python3 --version)

Skill package location known (or let it auto-detect)

This skill package works EVERYWHERE - just Python 3.7+ required!

No IDE-specific configuration needed. No platform-specific setup. No installation level restrictions.

Just extract and use!

disk-cleaner

SKILL.md

Disk Cleaner Skill - Complete Feature Guide for All Agents

🚨 IMPORTANT: Emoji Usage Policy

For Script Output (Cross-Platform Safety)

For Agent-to-Human Communication (Recommended)

📦 COMPLETE FEATURE LIST (READ THIS FIRST!)

🚨 CRITICAL: Progressive Scanning (MANDATORY for Large Disks)

🔧 Intelligent Bootstrap (Auto-Detection &#x26; Import)

🌐 Universal Compatibility

🛡️ Safety &#x26; Reliability

⚡ Performance Optimizations (ALL INCLUDED)

🆕 v2.2+ New Features

📊 Available Scripts (13+ Total)

🚀 Multi-Agent Acceleration (CRITICAL FOR PERFORMANCE)

📚 Documentation (Essential Files Only)

🎯 AGENT CHECKLIST (Must Follow)

For ANY Disk Analysis Request:

For ANY Clean Request:

⚡ PROGRESSIVE SCANNING (CRITICAL FOR LARGE DISKS)

🚨 CRITICAL INFORMATION (Read First)

Universal Compatibility

The Only Requirement

⚡ PROGRESSIVE SCANNING (CRITICAL FOR LARGE DISKS)

🚨 AGENT MUST USE FOR LARGE DISKS (>100GB)

📋 Three Scanning Modes

🎯 AGENT DECISION TREE (CRITICAL - FOLLOW THIS)

📝 Required Response Templates

💡 COPY-PASTE CODE (USE THIS)

⚠️ COMMON MISTAKES TO AVOID

📊 Command Reference Card

🔍 How Progressive Scan Works

🎯 BEST PRACTICE FOR AGENTS

🎯 UNIVERSAL AGENT WORKFLOW

STEP 1: Verify Python

STEP 2: Locate Skill Package

STEP 3: Verify Skill Package

STEP 4: Execute Operation

📋 QUICK REFERENCE (All IDEs)

⚠️ CRITICAL: Use Progressive Scanning for Large Disks!

User Intent → Operation Mapping

User Intent → Operation Mapping

Progressive Scanning (For Large Disks)

Cross-Platform Python Commands

Universal Command Template

🌐 Multi-IDE Compatibility

Supported AI IDEs

Installation by IDE Type

🔧 IDE-Specific Notes

Cursor

Windsurf

Continue

Aider

Generic/Other IDEs

🎯 Complete Copy-Paste Template

⚡ PROGRESSIVE SCANNING CHECKLIST (CRITICAL)

Agent MUST Follow This for All Disk Analysis Requests:

Required Behavior by Disk Size:

REQUIRED Code Pattern:

🚨 Error Handling (Universal)

Error: Python not found

Error: Skill not found

Error: Permission denied

📝 Environment Variables (Optional)

🎓 Best Practices for All Agents

🔍 Troubleshooting (Universal)

Problem: Skill works in one IDE but not another

Problem: Different behavior on different platforms

Problem: Can't find skill package

📦 Package Contents (Universal)

✅ Universal Checklist

Let your agent run on any real-world website

Related skills

Stop writing automation&scrapers

🔧 Intelligent Bootstrap (Auto-Detection & Import)

🛡️ Safety & Reliability