# SKILLS.md - Finding and Using Skills in Project Starlight

## 🎯 Overview

This guide describes how to find, access, and utilize skills within the Starlight ecosystem. Skills are modular capabilities that extend the functionality of steganography detection and analysis tools.

## 🔍 Skill Discovery Methods

### Method 1: Built-in Skill Listing
```python
# List available skills using the skill tool
def list_available_skills():
    """Get current skill inventory."""
    try:
        # Access skill system
        available_skills = skill("list")
        return {
            "skills_found": True,
            "skill_count": len(available_skills),
            "skills": available_skills
        }
    except Exception as e:
        return {"skills_found": False, "error": str(e)}
```

### Method 2: File System Search
```python
# Search for skill definitions in the codebase
def find_skill_files():
    """Locate skill definition files."""
    import glob
    
    # Common skill file patterns
    skill_patterns = [
        "**/skills/*.py",
        "**/skill_*.py", 
        "**/*_skill.py",
        "**/skills/**/*.md"
    ]
    
    found_skills = []
    for pattern in skill_patterns:
        files = glob.glob(pattern, recursive=True)
        found_skills.extend(files)
    
    return {
        "skill_files_found": len(found_skills),
        "skill_files": found_skills
    }
```

### Method 3: Registry Lookup
```python
# Check skill registry or manifest
def query_skill_registry():
    """Query skill registry for available capabilities."""
    try:
        # Look for skill registry file
        with open("skill_registry.json", "r") as f:
            registry = json.load(f)
        
        return {
            "registry_found": True,
            "available_skills": registry.get("skills", []),
            "categories": registry.get("categories", [])
        }
    except FileNotFoundError:
        return {"registry_found": False, "message": "No skill registry found"}
```

## 🛠️ Skill Usage Patterns

### Basic Skill Loading
```python
def load_skill(skill_name: str):
    """Load a specific skill by name."""
    try:
        skill_module = skill(name=skill_name)
        return {
            "skill_loaded": True,
            "skill_name": skill_name,
            "capabilities": getattr(skill_module, 'capabilities', [])
        }
    except Exception as e:
        return {"skill_loaded": False, "error": str(e)}
```

### Skill Execution
```python
def execute_skill(skill_name: str, parameters: dict):
    """Execute a skill with given parameters."""
    try:
        # Load skill
        skill_module = skill(name=skill_name)
        
        # Execute with parameters
        result = skill_module.execute(parameters)
        
        return {
            "skill_executed": True,
            "skill_name": skill_name,
            "result": result,
            "execution_time": datetime.datetime.now().isoformat()
        }
    except Exception as e:
        return {"skill_executed": False, "error": str(e)}
```

## 📁 Skill Organization Structure

### Standard Skill Layout
```
skills/
├── detection/
│   ├── lsb_detector.py
│   ├── dct_analyzer.py
│   └── alpha_channel_skill.py
├── analysis/
│   ├── pattern_recognition.py
│   └── statistical_analysis.py
├── preprocessing/
│   ├── image_normalizer.py
│   └── data_cleaner.py
└── registry.json
```

### Skill Metadata Format
```python
# Each skill should include metadata
skill_metadata = {
    "name": "lsb_detector",
    "version": "1.0.0",
    "category": "detection",
    "description": "Detects LSB steganography in images",
    "dependencies": ["PIL", "numpy"],
    "parameters": {
        "image_path": {"type": "string", "required": True},
        "threshold": {"type": "float", "default": 0.05}
    },
    "capabilities": ["lsb_detection", "accuracy_reporting"]
}
```

## 🔧 Integration Examples

### Steganography Detection Pipeline
```python
def create_detection_pipeline():
    """Build a pipeline using multiple skills."""
    
    # Load required skills
    skills = {
        "preprocessor": load_skill("image_normalizer"),
        "detector": load_skill("lsb_detector"), 
        "analyzer": load_skill("statistical_analysis")
    }
    
    def process_image(image_path: str):
        """Process image through skill pipeline."""
        results = {}
        
        # Step 1: Preprocessing
        if skills["preprocessor"]["skill_loaded"]:
            processed = execute_skill("image_normalizer", 
                                    {"image_path": image_path})
            results["preprocessing"] = processed
        
        # Step 2: Detection
        if skills["detector"]["skill_loaded"]:
            detection = execute_skill("lsb_detector", 
                                    {"image_path": image_path})
            results["detection"] = detection
        
        # Step 3: Analysis
        if skills["analyzer"]["skill_loaded"]:
            analysis = execute_skill("statistical_analysis", 
                                   {"detection_result": detection})
            results["analysis"] = analysis
        
        return results
    
    return {"pipeline_created": True, "process_function": process_image}
```

### Dynamic Skill Discovery
```python
def discover_and_catalog_skills():
    """Automatically discover and catalog all available skills."""
    import os
    
    catalog = {
        "discovered_at": datetime.datetime.now().isoformat(),
        "skills": [],
        "categories": set()
    }
    
    # Search common skill directories
    skill_dirs = ["skills", "modules", "capabilities"]
    
    for directory in skill_dirs:
        if os.path.exists(directory):
            for root, dirs, files in os.walk(directory):
                for file in files:
                    if file.endswith('.py') and 'skill' in file.lower():
                        skill_info = {
                            "name": file[:-3],  # Remove .py extension
                            "path": os.path.join(root, file),
                            "category": os.path.basename(root)
                        }
                        catalog["skills"].append(skill_info)
                        catalog["categories"].add(os.path.basename(root))
    
    catalog["categories"] = list(catalog["categories"])
    return catalog
```

## 📊 Skill Performance Monitoring

```python
def monitor_skill_performance(skill_name: str, execution_count: int = 10):
    """Monitor skill performance over multiple executions."""
    import time
    
    performance_data = []
    
    for i in range(execution_count):
        start_time = time.time()
        result = execute_skill(skill_name, {"test": True})
        end_time = time.time()
        
        performance_data.append({
            "execution": i + 1,
            "duration_ms": (end_time - start_time) * 1000,
            "success": result["skill_executed"],
            "timestamp": datetime.datetime.now().isoformat()
        })
    
    return {
        "skill_name": skill_name,
        "performance_data": performance_data,
        "avg_duration_ms": sum(d["duration_ms"] for d in performance_data) / len(performance_data),
        "success_rate": sum(1 for d in performance_data if d["success"]) / len(performance_data)
    }
```

## 🚀 Quick Start Commands

```bash
# List all available skills
python3 -c "
import sys
sys.path.append('.')
from skills import list_available_skills
print(list_available_skills())
"

# Execute a specific skill
python3 -c "
import sys
sys.path.append('.')
from skills import execute_skill
result = execute_skill('lsb_detector', {'image_path': 'test.png'})
print(result)
"

# Discover new skills
python3 -c "
import sys
sys.path.append('.')
from skills import discover_and_catalog_skills
catalog = discover_and_catalog_skills()
print(f'Found {len(catalog[\"skills\"])} skills')
"
```

## 📋 Checklist for Skill Implementation

- [ ] Skill has clear name and version
- [ ] Metadata includes dependencies and parameters
- [ ] Error handling is implemented
- [ ] Performance metrics are tracked
- [ ] Skill is registered in skill registry
- [ ] Documentation includes usage examples
- [ ] Integration tests are provided

## 🔗 Related Documentation

- `AGENTS.md` - General agent guidelines and constraints
- `scanner.py` - Main steganography detection tool
- `trainer.py` - Model training capabilities
- Dataset contributions in `datasets/` directory

---

*This SKILLS.md provides a comprehensive guide for finding and utilizing skills within Project Starlight's steganography detection ecosystem.*