good-self-contained-skill skill

---
name: example-framework-skill
description: Example of a properly self-contained skill following all best practices
category: framework
toolchain: python
tags: [self-contained, example, template, best-practice]
version: 1.0.0
author: claude-mpm-skills
updated: 2025-11-30
progressive_disclosure:
  entry_point:
    summary: "Example of a properly self-contained skill following all best practices"
    when_to_use: "When working with example-framework-skill or related functionality."
    quick_start: "1. Review the core concepts below. 2. Apply patterns to your use case. 3. Follow best practices for implementation."
---
# Example Framework Skill

A complete example demonstrating proper self-containment patterns for Claude Code skills.

**When to Use**: Building applications with Example Framework - includes setup, patterns, testing, and deployment.

---

## Overview

This skill demonstrates the **correct approach** to self-contained skill development:

✅ **Self-Contained**: All essential content inlined - works standalone
✅ **No Dependencies**: No relative paths to other skills
✅ **Complete Examples**: Working code, not fragments
✅ **Graceful Degradation**: Notes optional enhancements without requiring them
✅ **Flat Deployment Ready**: Works in any directory structure

---

## Quick Start

### Installation

```bash
# Install framework
pip install example-framework

# Create new project
example-framework init my-project
cd my-project

# Install dependencies
pip install -r requirements.txt

# Run development server
example-framework dev
```

### Minimal Example (Self-Contained)

```python
"""
Minimal Example Framework application.
Self-contained - no external skill dependencies.
"""
from example_framework import App, route

app = App()

@route("/")
def home():
    """Homepage route."""
    return {"message": "Hello, World!"}

@route("/users/{user_id}")
def get_user(user_id: int):
    """Get user by ID."""
    return {
        "id": user_id,
        "username": f"user_{user_id}"
    }

if __name__ == "__main__":
    # Development server
    app.run(host="0.0.0.0", port=8000, debug=True)
```

**Run it:**
```bash
python app.py
# Visit: http://localhost:8000
```

---

## Core Patterns

### 1. Application Setup (Self-Contained)

**Complete setup pattern** - no external dependencies:

```python
from example_framework import App, Config
from example_framework.middleware import CORSMiddleware, LoggingMiddleware

# Configuration
config = Config(
    DEBUG=True,
    SECRET_KEY="your-secret-key-here",
    DATABASE_URL="sqlite:///./app.db"
)

# Application instance
app = App(config=config)

# Middleware
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"]
)

app.add_middleware(LoggingMiddleware)

# Health check endpoint
@app.route("/health")
def health_check():
    """Health check endpoint."""
    return {"status": "healthy"}
```

### 2. Database Integration (Self-Contained)

**Essential database pattern** - inlined for self-containment:

```python
from example_framework import Database
from contextlib import contextmanager

# Database configuration
db = Database("sqlite:///./app.db")

@contextmanager
def get_db_session():
    """
    Database session context manager.

    Usage:
        with get_db_session() as session:
            users = session.query(User).all()
    """
    session = db.create_session()
    try:
        yield session
        session.commit()
    except Exception:
        session.rollback()
        raise
    finally:
        session.close()

# Model example
class User(db.Model):
    __tablename__ = "users"

    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80), unique=True, nullable=False)
    email = db.Column(db.String(120), unique=True, nullable=False)

    def to_dict(self):
        """Convert to dictionary."""
        return {
            "id": self.id,
            "username": self.username,
            "email": self.email
        }

# CRUD operations
@app.route("/users", methods=["POST"])
def create_user(data):
    """Create new user."""
    with get_db_session() as session:
        user = User(
            username=data["username"],
            email=data["email"]
        )
        session.add(user)
        return user.to_dict(), 201

@app.route("/users/{user_id}")
def get_user(user_id: int):
    """Get user by ID."""
    with get_db_session() as session:
        user = session.query(User).filter_by(id=user_id).first()
        if not user:
            return {"error": "User not found"}, 404
        return user.to_dict()
```

### 3. Testing Pattern (Self-Contained)

**Essential testing patterns** - inlined from testing best practices:

```python
"""
Test suite for Example Framework application.
Self-contained testing patterns - no external skill dependencies.
"""
import pytest
from example_framework.testing import TestClient

# Test client fixture
@pytest.fixture
def client():
    """Create test client."""
    return TestClient(app)

# Database fixture
@pytest.fixture
def db_session():
    """Create test database session."""
    db.create_all()
    session = db.create_session()
    yield session
    session.close()
    db.drop_all()

# Test examples
def test_home_route(client):
    """Test homepage returns correct response."""
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"message": "Hello, World!"}

def test_create_user(client, db_session):
    """Test user creation."""
    response = client.post("/users", json={
        "username": "testuser",
        "email": "[email protected]"
    })
    assert response.status_code == 201
    data = response.json()
    assert data["username"] == "testuser"
    assert data["email"] == "[email protected]"

def test_get_user(client, db_session):
    """Test get user by ID."""
    # Create user
    user = User(username="testuser", email="[email protected]")
    db_session.add(user)
    db_session.commit()

    # Get user
    response = client.get(f"/users/{user.id}")
    assert response.status_code == 200
    assert response.json()["username"] == "testuser"

def test_user_not_found(client):
    """Test 404 for nonexistent user."""
    response = client.get("/users/999")
    assert response.status_code == 404
```

**Run tests:**
```bash
pytest tests/
```

---

## Error Handling

### Standard Error Handler Pattern (Self-Contained)

```python
from example_framework import HTTPException

@app.error_handler(404)
def not_found_handler(error):
    """Handle 404 errors."""
    return {
        "error": "Not Found",
        "message": str(error)
    }, 404

@app.error_handler(500)
def server_error_handler(error):
    """Handle 500 errors."""
    return {
        "error": "Internal Server Error",
        "message": "An unexpected error occurred"
    }, 500

@app.error_handler(HTTPException)
def http_exception_handler(error):
    """Handle HTTP exceptions."""
    return {
        "error": error.name,
        "message": error.description
    }, error.status_code

# Custom validation error
class ValidationError(Exception):
    """Validation error."""
    pass

@app.error_handler(ValidationError)
def validation_error_handler(error):
    """Handle validation errors."""
    return {
        "error": "Validation Error",
        "message": str(error)
    }, 400
```

---

## Best Practices

### 1. Configuration Management

```python
# environment-based configuration
import os
from example_framework import Config

class DevelopmentConfig(Config):
    DEBUG = True
    DATABASE_URL = "sqlite:///./dev.db"

class ProductionConfig(Config):
    DEBUG = False
    DATABASE_URL = os.getenv("DATABASE_URL")
    SECRET_KEY = os.getenv("SECRET_KEY")

# Load config based on environment
env = os.getenv("ENV", "development")
config = DevelopmentConfig() if env == "development" else ProductionConfig()

app = App(config=config)
```

### 2. Dependency Injection

```python
# Dependency injection pattern
from example_framework import Depends

def get_current_user(token: str = Depends("Authorization")):
    """Get current user from token."""
    # Token validation logic
    user_id = validate_token(token)
    return User.query.get(user_id)

@app.route("/profile")
def get_profile(user: User = Depends(get_current_user)):
    """Get current user profile."""
    return user.to_dict()
```

### 3. Request Validation

```python
from example_framework import validate_request

# Request schema
user_schema = {
    "username": {"type": "string", "minLength": 3, "maxLength": 80},
    "email": {"type": "string", "format": "email"},
    "age": {"type": "integer", "minimum": 0}
}

@app.route("/users", methods=["POST"])
@validate_request(user_schema)
def create_user(data):
    """Create user with validated data."""
    # Data is already validated
    user = User(**data)
    db.session.add(user)
    db.session.commit()
    return user.to_dict(), 201
```

---

## Deployment

### Production Deployment (Self-Contained)

```python
"""
Production deployment configuration.
Self-contained - all necessary patterns included.
"""

# 1. Use production server (e.g., gunicorn)
# requirements.txt:
# gunicorn>=20.1.0

# 2. Production configuration
import os

class ProductionConfig:
    DEBUG = False
    TESTING = False
    SECRET_KEY = os.getenv("SECRET_KEY")
    DATABASE_URL = os.getenv("DATABASE_URL")
    ALLOWED_HOSTS = os.getenv("ALLOWED_HOSTS", "").split(",")

app = App(config=ProductionConfig())

# 3. Run with gunicorn
# gunicorn -w 4 -b 0.0.0.0:8000 app:app

# 4. Environment variables (.env)
# SECRET_KEY=your-production-secret-key
# DATABASE_URL=postgresql://user:pass@localhost/dbname
# ALLOWED_HOSTS=example.com,www.example.com
```

---

## Complementary Skills

When using this skill, consider these related skills (if deployed):

- **pytest-patterns**: Advanced testing patterns and fixtures
  - *Use case*: Comprehensive test suites with parametrization
  - *Integration*: Enhance basic testing patterns shown above
  - *Status*: Optional - basic testing patterns included in this skill

- **database-orm-patterns**: Advanced ORM patterns and optimization
  - *Use case*: Complex queries, relationships, performance tuning
  - *Integration*: Builds on basic database pattern shown above
  - *Status*: Optional - basic CRUD patterns included in this skill

- **api-security**: Authentication, authorization, security best practices
  - *Use case*: Production-ready security implementation
  - *Integration*: Adds security layer to routes
  - *Status*: Recommended for production - basic examples shown above

- **deployment-patterns**: Docker, CI/CD, monitoring, scaling
  - *Use case*: Production deployment and operations
  - *Integration*: Deployment strategies and tooling
  - *Status*: Optional - basic deployment shown above

**Note**: All complementary skills are independently deployable. This skill is fully functional without them.

---

## Common Pitfalls

### ❌ Don't: Relative Imports
```python
# DON'T DO THIS
from ..other_skill.patterns import setup
```

### ✅ Do: Self-Contained Patterns
```python
# Include pattern directly
def setup():
    """Setup pattern (self-contained)."""
    # Implementation here
    pass
```

### ❌ Don't: External Skill Dependencies
```python
# DON'T DO THIS
# This requires pytest-patterns skill
from skills.pytest_patterns import fixture_factory
```

### ✅ Do: Inline Essential Patterns
```python
# Include essential pattern
def fixture_factory(name, default=None):
    """Fixture factory pattern (inlined)."""
    @pytest.fixture
    def _fixture():
        return default
    _fixture.__name__ = name
    return _fixture
```

---

## Progressive Disclosure

For more advanced topics, see the `references/` directory:

- **[references/advanced-patterns.md](references/advanced-patterns.md)**: Advanced framework patterns
- **[references/performance.md](references/performance.md)**: Performance optimization
- **[references/api-reference.md](references/api-reference.md)**: Complete API documentation

**Note**: Main SKILL.md is self-sufficient. References provide optional deep dives.

---

## Resources

**Official Documentation**:
- Example Framework Docs: https://example-framework.readthedocs.io
- API Reference: https://example-framework.readthedocs.io/api
- Community: https://github.com/example-framework/community

**Related Technologies**:
- Python: https://docs.python.org
- SQLite: https://www.sqlite.org
- Pytest: https://docs.pytest.org

---

## Summary

This skill demonstrates **self-contained skill development**:

✅ **Complete**: All essential patterns included inline
✅ **Independent**: Works without other skills
✅ **Tested**: Verified in isolation
✅ **Deployable**: Works in flat directory structure
✅ **Graceful**: Notes optional enhancements without requiring them

**Use this as a template** for creating new skills.

---

**Version**: 1.0.0
**Last Updated**: 2025-11-30
**Self-Containment**: ✅ Fully Compliant