disk-cleaner — скилл для Claude Code: чистит диск из чата

---
name: disk-cleaner
description: "Cross-platform disk space management toolkit with intelligent optimization. REQUIREMENTS: Python 3.7+. UNIVERSAL COMPATIBILITY: Works with ALL AI IDEs (Cursor, Windsurf, Continue, Aider, Claude Code, etc.). PLATFORM-INDEPENDENT: Works at any location - global, project, or user level. SELF-CONTAINED: No pip install needed, includes intelligent bootstrap. KEY FEATURES: (1) PROGRESSIVE SCANNING: Quick sample (1s) + Progressive mode for large disks, (2) INTELLIGENT BOOTSTRAP: Auto-detection of skill location and auto-import of modules, (3) CROSS-PLATFORM ENCODING: Safe emoji/Unicode handling on all platforms, (4) DIAGNOSTIC TOOLS: check_skill.py for quick verification, (5) OPTIMIZED SCANNING: 3-5x faster with os.scandir(), concurrent scanning, intelligent sampling. AGENT WORKFLOW: (1) Check Python, (2) Find skill package (20+ locations auto-detected), (3) Run diagnostics, (4) Use progressive scanning for large disks. The skill package includes all optimization modules - no features are lost!"
---

# 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:**
1. **analyze_disk.py** - Disk analysis with smart sampling (enhanced v2.2)
2. **analyze_progressive.py** - Progressive scanning for large disks
3. **find_duplicates.py** - Duplicate file detection (NEW v2.2)
4. **analyze_growth.py** - Growth trend analysis (NEW v2.2)

**Cleaning & Organization:**
5. **clean_disk.py** - Safe junk file cleaning (enhanced cache detection)
6. **interactive_wizard.py** - Interactive guided cleanup (NEW v2.2)
7. **organize_files.py** - File archival and organization (NEW v2.2)

**Monitoring & Diagnostics:**
8. **monitor_disk.py** - Disk usage monitoring
9. **check_skill.py** - Diagnostic tool

**Developer Tools:**
10. **skill_bootstrap.py** - Intelligent bootstrap module
11. **package_skill.py** - Package creation tool
12. **scheduler.py** - Automated scheduling

### macOS QQ media cleanup

Use `scripts/qq_cleanup_macos.zsh` when QQ pictures or emojis consume excessive
space on macOS and chat records must remain intact.

1. Audit QQ storage without changing files:

   ```zsh
   scripts/qq_cleanup_macos.zsh audit
   ```

2. Preview pictures and emojis older than 90 days:

   ```zsh
   scripts/qq_cleanup_macos.zsh clean --older-than-days 90 --categories Pic,Emoji
   ```

3. Report the preview and obtain explicit approval. Quit QQ, then repeat the
   approved command with `--execute`.

Never select `nt_db`, account roots, preferences, voice messages, videos, or
received files. The script accepts only `Pic` and `Emoji`, defaults to preview,
and refuses execution while QQ is running. Warn that removed local media might
no longer be available in old conversations.

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

```python
# 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)**

```python
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):

```python
# 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 | **3x** |
| 10 user profiles | ~20 minutes | ~4 minutes | **5x** |
| 1M files | ~30 minutes | ~6 minutes | **5x** |
| Cache cleanup (26 locations) | ~8 minutes | ~2 minutes | **4x** |

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

1. **Divide work logically**: By disk, by user profile, by directory type
2. **Use consistent parameters**: All agents use same scan limits
3. **Merge results carefully**: Deduplicate, sort, format
4. **Handle failures gracefully**: If one agent fails, continue others
5. **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
```python
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

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

**Output**:
```json
{
  "sample_file_count": 7591,
  "sample_size_gb": 17.62,
  "files_per_second": 7501.0,
  "estimated_time_seconds": 2.0
}
```

**Agent Decision Logic**:
```python
# 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

```bash
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**:
```python
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

```bash
# 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 < 30 Seconds
```
✅ Disk analysis will take approximately 2 seconds
Starting full scan...
```

#### When Quick Sample Shows 30-120 Seconds
```
⚠️ Disk analysis will take approximately 3 minutes
Using time-limited scan for faster results...
```

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

```python
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` | 1s | 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

1. **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

2. **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

3. **Smart Stopping**
   - Stops automatically when time/file limit reached
   - Graceful handling of interruption
   - Partial results are still useful

### 🎯 BEST PRACTICE FOR AGENTS

1. **ALWAYS** run `--sample` first
2. **ALWAYS** check estimated_time before choosing mode
3. **ALWAYS** inform user about expected scan time
4. **ALWAYS** use progressive mode for large disks (>2 minutes)
5. **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

```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

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

### STEP 3: Verify Skill Package

```python
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...