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

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

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! ⚡

# 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)

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)

# 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)

[ ] 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

[ ] 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

import subprocess
result = subprocess.run(['python', '--version'], capture_output=True, text=True)
# If this succeeds, you can use this skill

python scripts/analyze_disk.py --sample
# OR
python scripts/analyze_progressive.py --sample

{
  "sample_file_count": 7591,
  "sample_size_gb": 17.62,
  "files_per_second": 7501.0,
  "estimated_time_seconds": 2.0
}

# 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

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

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

# 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

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)"

✅ Disk analysis will take approximately 2 seconds
Starting full scan...

⚠️ Disk analysis will take approximately 3 minutes
Using time-limited scan for faster results...

🚨 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)

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")

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}")

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 & 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}")

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)

def execute_operation(skill_path, operation, python_cmd='python', **kwargs):
    """
    Execute disk cleaner operation - PLATFORM & 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")

# 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

# 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'])

# 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)

your-project/
├── skills/
│   └── disk-cleaner/    ← Extract here
├── src/
└── README.md

~/.skills/disk-cleaner/      ← Unix-like
~/agent-skills/disk-cleaner/ ← Alternative
C:\Users\You\skills\disk-cleaner\ ← Windows

/usr/local/share/skills/disk-cleaner/  ← Linux (system-wide)
C:\ProgramData\skills\disk-cleaner\   ← Windows (system-wide)

# Cursor automatically searches for skills in:
# - .cursor/skills/
# - project/skills/
# - ~/.skills/

# No special configuration needed

# Windsurf supports skills at:
# - .windsurf/skills/
# - project/skills/

# Skill works via subprocess, no special setup

# Continue configuration (if needed):
# {
#   "skills": ["./skills/disk-cleaner"]
# }
# But auto-detection works in most cases

# Use as a tool via subprocess:
# !python skills/disk-cleaner/scripts/analyze_disk.py

# The skill includes intelligent auto-detection
# Just extract and use - no configuration needed

"""
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)

[ ] 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?

# 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'])

# 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")

# 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")

# 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")

# 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

python skills/disk-cleaner/scripts/check_skill.py
# Or
python3 skills/disk-cleaner/scripts/check_skill.py

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