# Skill Examples

This file contains complete, working examples of well-structured skills across different domains.

## Example 1: Python Testing Skill

### Structure
```
python-testing-skill/
├── SKILL.md
└── test-templates/
    ├── pytest-basic.py
    └── pytest-advanced.py
```

### SKILL.md
```markdown
---
name: Python Testing with pytest
description: Create comprehensive Python tests using pytest with fixtures, parametrization, and mocking. Use when writing unit tests, integration tests, or setting up test infrastructure for Python projects.
---

## When to Use This Skill

Use this skill when:
- Writing unit tests for Python functions and classes
- Creating integration tests for Python applications
- Setting up pytest configuration and fixtures
- Implementing test parametrization for multiple scenarios
- Mocking external dependencies in tests

Do NOT use this skill for:
- Testing non-Python code
- End-to-end browser testing (use Playwright skill instead)
- Load testing or performance benchmarking

## Quick Start

Basic test structure:

```python
import pytest
from myapp import add_numbers

def test_add_numbers():
    result = add_numbers(2, 3)
    assert result == 5
```

Run tests:
```bash
pytest tests/ -v
```

## Core Workflows

### Workflow 1: Writing Unit Tests

1. Create a test file matching your source file: `test_module.py` for `module.py`
2. Import the code to test and pytest
3. Write test functions starting with `test_`
4. Use assert statements for validation
5. Run pytest from project root

**Example:**
```python
# test_calculator.py
import pytest
from calculator import Calculator

def test_addition():
    calc = Calculator()
    assert calc.add(2, 3) == 5
    assert calc.add(-1, 1) == 0
    assert calc.add(0, 0) == 0

def test_division_by_zero():
    calc = Calculator()
    with pytest.raises(ValueError, match="Cannot divide by zero"):
        calc.divide(10, 0)
```

### Workflow 2: Using Fixtures

1. Create fixtures for common test setup
2. Use `@pytest.fixture` decorator
3. Accept fixtures as test function parameters
4. Fixtures run automatically before tests

**Example:**
```python
import pytest
from database import Database

@pytest.fixture
def db():
    """Provide a test database instance"""
    database = Database(":memory:")
    database.setup()
    yield database
    database.teardown()

def test_create_user(db):
    user = db.create_user("alice", "alice@example.com")
    assert user.name == "alice"
    assert user.email == "alice@example.com"

def test_query_user(db):
    db.create_user("bob", "bob@example.com")
    user = db.query_user("bob")
    assert user is not None
```

### Workflow 3: Parametrized Tests

1. Use `@pytest.mark.parametrize` decorator
2. Provide parameter names and test cases
3. Test function runs once per parameter set

**Example:**
```python
import pytest
from validators import validate_email

@pytest.mark.parametrize("email,expected", [
    ("user@example.com", True),
    ("user@domain.co.uk", True),
    ("invalid@", False),
    ("@example.com", False),
    ("no-at-sign.com", False),
    ("", False),
])
def test_email_validation(email, expected):
    assert validate_email(email) == expected
```

### Workflow 4: Mocking External Dependencies

1. Import `unittest.mock` or use `pytest-mock`
2. Use `mocker.patch()` to replace dependencies
3. Configure mock return values or side effects
4. Verify mock interactions

**Example:**
```python
import pytest
from unittest.mock import Mock
from weather_app import get_weather

def test_get_weather(mocker):
    # Mock the external API call
    mock_api = mocker.patch('weather_app.weather_api.fetch')
    mock_api.return_value = {
        "temperature": 72,
        "conditions": "sunny"
    }

    result = get_weather("San Francisco")

    assert result["temperature"] == 72
    assert result["conditions"] == "sunny"
    mock_api.assert_called_once_with("San Francisco")
```

## Test Organization

### Project Structure
```
myproject/
├── src/
│   └── myapp/
│       ├── __init__.py
│       ├── core.py
│       └── utils.py
├── tests/
│   ├── __init__.py
│   ├── conftest.py          # Shared fixtures
│   ├── test_core.py
│   └── test_utils.py
└── pyproject.toml            # pytest configuration
```

### conftest.py for Shared Fixtures
```python
import pytest
from myapp import create_app

@pytest.fixture(scope="session")
def app():
    """Create application for testing"""
    app = create_app(testing=True)
    return app

@pytest.fixture
def client(app):
    """Test client for making requests"""
    return app.test_client()
```

## Configuration

### pyproject.toml
```toml
[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
python_functions = ["test_*"]
addopts = [
    "-v",
    "--strict-markers",
    "--cov=myapp",
    "--cov-report=term-missing",
]
markers = [
    "slow: marks tests as slow",
    "integration: marks tests as integration tests",
]
```

## Coverage Goals

Aim for:
- 80%+ code coverage for business logic
- 100% coverage for critical paths (auth, payments, data integrity)
- Edge cases and error conditions tested
- Integration tests for key workflows

Check coverage:
```bash
pytest --cov=myapp --cov-report=html
open htmlcov/index.html
```

## Common Pitfalls

### Issue: Tests Pass Locally but Fail in CI
**Solution:**
- Use fixtures to avoid state pollution between tests
- Don't rely on file system state or specific paths
- Mock time-dependent functionality
- Set explicit random seeds for reproducibility

### Issue: Slow Test Suite
**Solution:**
- Use `@pytest.mark.slow` for slow tests, run separately
- Mock external API calls instead of making real requests
- Use in-memory databases for tests
- Run fast unit tests before slow integration tests

### Issue: Fixtures Not Running
**Solution:**
- Ensure fixture name matches parameter name exactly
- Check fixture scope (function/class/module/session)
- Verify conftest.py is in correct location

## Advanced Techniques

### Async Testing
```python
import pytest

@pytest.mark.asyncio
async def test_async_function():
    result = await async_fetch_data()
    assert result["status"] == "success"
```

### Testing Exceptions with Context
```python
def test_invalid_input():
    with pytest.raises(ValueError) as exc_info:
        process_data(invalid_input)
    assert "expected format" in str(exc_info.value)
```

### Temporary File Testing
```python
def test_file_processing(tmp_path):
    # tmp_path is a pytest fixture providing a temporary directory
    test_file = tmp_path / "test.txt"
    test_file.write_text("test content")

    result = process_file(test_file)
    assert result.success
```
```

---

## Example 2: API Integration Skill

### SKILL.md
```markdown
---
name: REST API Integration
description: Design and implement RESTful API integrations with proper error handling, authentication, and rate limiting. Use when building API clients or integrating third-party services.
---

## When to Use This Skill

Use this skill when:
- Integrating third-party REST APIs into your application
- Building API client libraries
- Implementing API authentication flows (OAuth, JWT, API keys)
- Handling rate limiting and retries
- Creating robust error handling for API calls

Do NOT use this skill for:
- GraphQL APIs (different query paradigm)
- gRPC or WebSocket connections
- Building API servers (use framework-specific skills)

## Quick Start

Basic API client structure:

```python
import requests

class APIClient:
    def __init__(self, base_url, api_key):
        self.base_url = base_url
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        })

    def get(self, endpoint):
        response = self.session.get(f"{self.base_url}{endpoint}")
        response.raise_for_status()
        return response.json()
```

## Core Workflows

### Workflow 1: Implementing Authentication

**API Key Authentication:**
```python
class APIKeyClient:
    def __init__(self, api_key):
        self.headers = {"X-API-Key": api_key}

    def request(self, method, url, **kwargs):
        kwargs.setdefault('headers', {}).update(self.headers)
        return requests.request(method, url, **kwargs)
```

**OAuth 2.0 Flow:**
```python
from requests_oauthlib import OAuth2Session

class OAuthClient:
    def __init__(self, client_id, client_secret, redirect_uri):
        self.client_id = client_id
        self.client_secret = client_secret
        self.redirect_uri = redirect_uri
        self.session = None

    def get_authorization_url(self, authorization_base_url):
        oauth = OAuth2Session(self.client_id, redirect_uri=self.redirect_uri)
        authorization_url, state = oauth.authorization_url(authorization_base_url)
        return authorization_url, state

    def fetch_token(self, token_url, authorization_response):
        oauth = OAuth2Session(self.client_id, redirect_uri=self.redirect_uri)
        token = oauth.fetch_token(
            token_url,
            authorization_response=authorization_response,
            client_secret=self.client_secret
        )
        self.session = oauth
        return token
```

### Workflow 2: Error Handling and Retries

```python
import time
from requests.adapters import HTTPAdapter
from requests.packages.urllib3.util.retry import Retry

class RobustAPIClient:
    def __init__(self, base_url, api_key, max_retries=3):
        self.base_url = base_url
        self.session = requests.Session()

        # Configure retry strategy
        retry_strategy = Retry(
            total=max_retries,
            backoff_factor=1,
            status_forcelist=[429, 500, 502, 503, 504],
            allowed_methods=["GET", "POST", "PUT", "DELETE"]
        )
        adapter = HTTPAdapter(max_retries=retry_strategy)
        self.session.mount("http://", adapter)
        self.session.mount("https://", adapter)

        self.session.headers.update({
            "Authorization": f"Bearer {api_key}"
        })

    def request(self, method, endpoint, **kwargs):
        url = f"{self.base_url}{endpoint}"
        try:
            response = self.session.request(method, url, **kwargs)
            response.raise_for_status()
            return response.json()
        except requests.exceptions.HTTPError as e:
            if e.response.status_code == 401:
                raise AuthenticationError("Invalid or expired API key")
            elif e.response.status_code == 404:
                raise NotFoundError(f"Resource not found: {endpoint}")
            elif e.response.status_code == 429:
                raise RateLimitError("Rate limit exceeded")
            else:
                raise APIError(f"API request failed: {e}")
        except requests.exceptions.RequestException as e:
            raise APIError(f"Network error: {e}")

class APIError(Exception): pass
class AuthenticationError(APIError): pass
class NotFoundError(APIError): pass
class RateLimitError(APIError): pass
```

### Workflow 3: Rate Limiting

```python
import time
from threading import Lock

class RateLimiter:
    def __init__(self, calls_per_second):
        self.calls_per_second = calls_per_second
        self.min_interval = 1.0 / calls_per_second
        self.last_call = 0
        self.lock = Lock()

    def __call__(self, func):
        def wrapper(*args, **kwargs):
            with self.lock:
                elapsed = time.time() - self.last_call
                if elapsed < self.min_interval:
                    time.sleep(self.min_interval - elapsed)
                self.last_call = time.time()
            return func(*args, **kwargs)
        return wrapper

class RateLimitedClient:
    def __init__(self, base_url, api_key, rate_limit=10):
        self.client = APIClient(base_url, api_key)
        self.limiter = RateLimiter(rate_limit)

    @property
    def get(self):
        return self.limiter(self.client.get)

    @property
    def post(self):
        return self.limiter(self.client.post)
```

### Workflow 4: Pagination Handling

```python
class PaginatedAPIClient(APIClient):
    def get_all_pages(self, endpoint, params=None):
        """Fetch all pages of results"""
        results = []
        page = 1
        params = params or {}

        while True:
            params['page'] = page
            response = self.get(endpoint, params=params)

            # Adjust based on API response structure
            items = response.get('items', [])
            results.extend(items)

            # Check if more pages exist
            if not response.get('has_more', False):
                break

            page += 1

        return results

    def get_all_cursor(self, endpoint, params=None):
        """Fetch all results using cursor-based pagination"""
        results = []
        cursor = None
        params = params or {}

        while True:
            if cursor:
                params['cursor'] = cursor

            response = self.get(endpoint, params=params)
            items = response.get('data', [])
            results.extend(items)

            cursor = response.get('next_cursor')
            if not cursor:
                break

        return results
```

## Common Patterns

### Request Caching
```python
from functools import lru_cache
import hashlib
import json

class CachedAPIClient(APIClient):
    def __init__(self, base_url, api_key, cache_ttl=300):
        super().__init__(base_url, api_key)
        self.cache = {}
        self.cache_ttl = cache_ttl

    def _cache_key(self, method, endpoint, params):
        key_data = f"{method}:{endpoint}:{json.dumps(params, sort_keys=True)}"
        return hashlib.md5(key_data.encode()).hexdigest()

    def get_cached(self, endpoint, params=None):
        cache_key = self._cache_key("GET", endpoint, params or {})

        if cache_key in self.cache:
            cached_data, cached_time = self.cache[cache_key]
            if time.time() - cached_time < self.cache_ttl:
                return cached_data

        data = self.get(endpoint, params=params)
        self.cache[cache_key] = (data, time.time())
        return data
```

### Webhook Signature Verification
```python
import hmac
import hashlib

class WebhookValidator:
    def __init__(self, secret):
        self.secret = secret.encode()

    def verify_signature(self, payload, signature_header):
        """Verify webhook signature"""
        expected_signature = hmac.new(
            self.secret,
            payload.encode(),
            hashlib.sha256
        ).hexdigest()

        return hmac.compare_digest(expected_signature, signature_header)
```

## Testing API Integrations

### Using responses Library
```python
import responses
import requests

@responses.activate
def test_api_get():
    # Mock the API response
    responses.add(
        responses.GET,
        'https://api.example.com/users/123',
        json={'id': 123, 'name': 'Alice'},
        status=200
    )

    client = APIClient('https://api.example.com', 'test-key')
    user = client.get('/users/123')

    assert user['name'] == 'Alice'

@responses.activate
def test_api_error_handling():
    responses.add(
        responses.GET,
        'https://api.example.com/users/999',
        json={'error': 'Not found'},
        status=404
    )

    client = RobustAPIClient('https://api.example.com', 'test-key')

    with pytest.raises(NotFoundError):
        client.request('GET', '/users/999')
```

## Common Pitfalls

### Issue: Leaking API Keys
**Solution:** Never hardcode keys. Use environment variables or secret management:
```python
import os

api_key = os.environ.get('API_KEY')
if not api_key:
    raise ValueError("API_KEY environment variable not set")
```

### Issue: Not Handling Rate Limits
**Solution:** Implement exponential backoff and respect rate limit headers:
```python
def handle_rate_limit(response):
    if response.status_code == 429:
        retry_after = int(response.headers.get('Retry-After', 60))
        time.sleep(retry_after)
        # Retry request
```

### Issue: Timeout Issues
**Solution:** Always set timeouts:
```python
response = self.session.get(url, timeout=(3.0, 10.0))  # (connect, read)
```
```

---

## Example 3: Documentation Skill

### SKILL.md
```markdown
---
name: Technical Documentation Writer
description: Create clear, comprehensive technical documentation including API docs, README files, user guides, and code comments. Use when documenting code, APIs, or writing user-facing technical content.
---

## When to Use This Skill

Use this skill when:
- Writing README.md files for repositories
- Documenting APIs (REST, GraphQL, SDKs)
- Creating user guides and tutorials
- Writing inline code documentation
- Building developer onboarding materials

Do NOT use this skill for:
- Marketing copy or sales content
- Academic papers or research documentation
- Legal or compliance documentation

## Core Principles

1. **Write for your audience**: Junior developers need more context than senior engineers
2. **Show, don't just tell**: Include code examples for every concept
3. **Start with "why"**: Explain the purpose before the implementation
4. **Maintain consistency**: Use the same terminology throughout
5. **Keep it current**: Documentation that's out of date is worse than no documentation

## README.md Template

```markdown
# Project Name

Brief (1-2 sentence) description of what this project does.

## Features

- Key feature 1
- Key feature 2
- Key feature 3

## Installation

\```bash
npm install project-name
\```

## Quick Start

\```javascript
const Project = require('project-name');

const instance = new Project({
  apiKey: 'your-api-key'
});

const result = await instance.doSomething();
console.log(result);
\```

## Documentation

Full documentation available at [link]

## Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| apiKey | string | required | Your API key |
| timeout | number | 5000 | Request timeout in ms |

## Examples

### Example 1: Basic Usage
[Code example with explanation]

### Example 2: Advanced Pattern
[Code example with explanation]

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md)

## License

[License type] - see [LICENSE](LICENSE)
```

## API Documentation Template

```markdown
## endpoint_name

Brief description of what this endpoint does.

### HTTP Request

\```
POST /api/v1/resource
\```

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| name | string | Yes | Resource name |
| type | string | No | Resource type (default: "standard") |
| metadata | object | No | Additional metadata |

### Request Example

\```json
{
  "name": "example-resource",
  "type": "premium",
  "metadata": {
    "created_by": "user123"
  }
}
\```

### Response

\```json
{
  "id": "res_abc123",
  "name": "example-resource",
  "type": "premium",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}
\```

### Errors

| Status Code | Error Code | Description |
|-------------|------------|-------------|
| 400 | invalid_name | Name contains invalid characters |
| 401 | unauthorized | Invalid or missing API key |
| 409 | duplicate | Resource with this name already exists |

### Example Usage

\```python
import requests

response = requests.post(
    'https://api.example.com/api/v1/resource',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'name': 'example-resource',
        'type': 'premium'
    }
)

resource = response.json()
print(f"Created resource: {resource['id']}")
\```
```

## Code Comment Guidelines

### Function Documentation

**Python (docstring):**
```python
def calculate_discount(price: float, discount_percent: float, min_price: float = 0) -> float:
    """
    Calculate discounted price with minimum price floor.

    Args:
        price: Original price before discount
        discount_percent: Discount percentage (0-100)
        min_price: Minimum price floor (default: 0)

    Returns:
        Final price after applying discount, never below min_price

    Raises:
        ValueError: If discount_percent is not between 0 and 100
        ValueError: If price or min_price is negative

    Examples:
        >>> calculate_discount(100, 20)
        80.0
        >>> calculate_discount(100, 20, min_price=85)
        85.0
    """
    if not 0 <= discount_percent <= 100:
        raise ValueError("Discount percent must be between 0 and 100")
    if price < 0 or min_price < 0:
        raise ValueError("Prices cannot be negative")

    discounted = price * (1 - discount_percent / 100)
    return max(discounted, min_price)
```

**JavaScript (JSDoc):**
```javascript
/**
 * Fetch user data from the API with caching
 *
 * @param {string} userId - The unique user identifier
 * @param {Object} options - Configuration options
 * @param {boolean} [options.skipCache=false] - Whether to bypass cache
 * @param {number} [options.timeout=5000] - Request timeout in ms
 * @returns {Promise<User>} The user object
 * @throws {NotFoundError} If user doesn't exist
 * @throws {APIError} If the API request fails
 *
 * @example
 * const user = await fetchUser('user123');
 * console.log(user.name);
 *
 * @example
 * // Skip cache for fresh data
 * const user = await fetchUser('user123', { skipCache: true });
 */
async function fetchUser(userId, options = {}) {
  // Implementation
}
```

### Inline Comments

**Good inline comments explain "why", not "what":**

```python
# Good: Explains reasoning
# Use a Set for O(1) lookup time since we'll be checking membership frequently
seen_ids = set()

# Bad: Just repeats what the code says
# Create a set called seen_ids
seen_ids = set()
```

```python
# Good: Explains non-obvious behavior
# Delay between requests to avoid hitting rate limit (10 req/sec)
time.sleep(0.1)

# Bad: States the obvious
# Sleep for 0.1 seconds
time.sleep(0.1)
```

## Common Pitfalls

### Issue: Documentation Out of Sync with Code
**Solution:**
- Keep docs close to code (docstrings, inline comments)
- Auto-generate API docs from code when possible
- Include doc updates in pull request checklist
- Set up CI checks for documentation completeness

### Issue: Too Much or Too Little Detail
**Solution:**
- README: High-level overview + quick start
- API Docs: Complete reference for every parameter
- Tutorials: Step-by-step with context
- Code Comments: Why, not what

### Issue: Examples Don't Run
**Solution:**
- Test all code examples as part of CI
- Use tools like doctest (Python) or jsdoc-to-markdown
- Include a "examples" directory with runnable code
- Version examples alongside code releases
```