Example Framework Skill

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

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

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

python app.py
# Visit: http://localhost:8000

---

Core Patterns

1. Application Setup (Self-Contained)

Complete setup pattern - no external dependencies:

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:

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:

"""
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": "test@example.com"
    })
    assert response.status_code == 201
    data = response.json()
    assert data["username"] == "testuser"
    assert data["email"] == "test@example.com"

def test_get_user(client, db_session):
    """Test get user by ID."""
    # Create user
    user = User(username="testuser", email="test@example.com")
    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:

pytest tests/

---

Error Handling

Standard Error Handler Pattern (Self-Contained)

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

# 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

# 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

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)

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

# DON'T DO THIS
from ..other_skill.patterns import setup

✅ Do: Self-Contained Patterns

# Include pattern directly
def setup():
    """Setup pattern (self-contained)."""
    # Implementation here
    pass

❌ Don't: External Skill Dependencies

# DON'T DO THIS
# This requires pytest-patterns skill
from skills.pytest_patterns import fixture_factory

✅ Do: Inline Essential Patterns

# 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

Good Self-Contained Skill Example

This directory contains a template example of a properly self-contained skill that follows all best practices from the SKILL_SELF_CONTAINMENT_STANDARD.md.

---

What Makes This a Good Example?

✅ Self-Containment Principles

1. Complete Content: All essential patterns are inlined in SKILL.md 2. No Dependencies: Zero relative paths to other skills 3. Works Standalone: Can be deployed to any directory structure 4. Graceful Degradation: Notes optional enhancements without requiring them 5. Informational References: Mentions complementary skills by name only

---

Key Features Demonstrated

1. Essential Content Inlining

Pattern: Include 20-50 line code examples for core functionality

Example from SKILL.md:

# Complete database session pattern (30 lines)
@contextmanager
def get_db_session():
    """Database session context manager."""
    session = db.create_session()
    try:
        yield session
        session.commit()
    except Exception:
        session.rollback()
        raise
    finally:
        session.close()

Why: Users can accomplish database tasks with ONLY this skill.

---

2. No Relative Path Violations

Pattern: Never reference other skills with file paths

Example:

❌ DON'T: See [pytest patterns](../../testing/pytest/SKILL.md)
✅ DO: Consider pytest-patterns skill for advanced testing (if deployed)

Verification:

$ grep -r "\.\\./" good-self-contained-skill/
(empty - no violations)

---

3. Complementary Skills Section

Pattern: List related skills informationally

Example from SKILL.md:

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

**Note**: All complementary skills are independently deployable.

Why: Clear that other skills enhance but aren't required.

---

4. Graceful Degradation

Pattern: Basic functionality self-contained, advanced features note optional skills

Example from SKILL.md:

## Testing Pattern (Self-Contained)

**Essential testing patterns** - inlined from testing best practices:
[30-50 lines of complete testing code]

**Advanced fixtures** (if pytest-patterns skill deployed):
- Parametrized fixtures
- Fixture factories
- Scope management

*See pytest-patterns skill for comprehensive patterns.*

Why: Skill works independently, enhancements are optional.

---

5. Complete Examples

Pattern: All code examples are complete, working code (not fragments)

Example from SKILL.md:

# Complete minimal application (self-contained)
from example_framework import App, route

app = App()

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

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

Why: Users can copy-paste and run immediately.

---

6. Metadata Best Practices

metadata.json highlights:

{
  "self_contained": true,
  "requires": [],  // No skill dependencies
  "dependencies": ["external-package"],  // Only external packages
  "complementary_skills": ["other-skill"],  // Informational only
  "tags": ["self-contained"]  // Self-containment tag
}

---

Testing Self-Containment

Isolation Test

# 1. Copy to isolated directory
mkdir -p /tmp/skill-test
cp -r good-self-contained-skill /tmp/skill-test/

# 2. Verify works standalone
cd /tmp/skill-test/good-self-contained-skill
cat SKILL.md  # Complete content - no missing references

# 3. Check for violations
grep -r "\.\\./" .  # Empty output - no relative paths

Verification Commands

# All these should return empty (no violations)
grep -r "\.\\./" good-self-contained-skill/
grep -r "from skills\." good-self-contained-skill/
grep -r "import.*\.\./" good-self-contained-skill/
grep -i "requires.*skill" good-self-contained-skill/SKILL.md

---

Use as Template

When Creating New Skills

1. Copy this structure:

   cp -r examples/good-self-contained-skill your-new-skill

2. Update metadata.json:

• Change name, category, toolchain
• Keep "self_contained": true
• Keep "requires": []

3. Fill in SKILL.md:

• Follow progressive disclosure structure
• Inline essential patterns (20-50 lines each)
• Note complementary skills informationally
• Include complete examples

4. Test isolation:

   grep -r "\.\\./" your-new-skill/
   # Should be empty

5. Verify with checklist:

• Use SKILL_CREATION_PR_CHECKLIST.md

---

Structure

good-self-contained-skill/
├── SKILL.md           # Complete, self-contained documentation
├── metadata.json      # Metadata with self_contained: true
├── README.md          # This file - explains the example
└── references/        # Optional progressive disclosure
    ├── advanced-patterns.md
    ├── performance.md
    └── api-reference.md

Note: references/ is optional. Main SKILL.md is self-sufficient.

---

Key Patterns to Copy

Pattern 1: Inline Essential Content

## Core Pattern (Self-Contained)

**Essential pattern** (inlined):
[20-50 lines of complete working code]

**Advanced usage** (if advanced-skill deployed):
- Feature 1
- Feature 2

Pattern 2: Complementary Skills

## Complementary Skills

- **skill-name**: How it complements
  - *Use case*: When to combine
  - *Status*: Optional enhancement

*Note: All skills independently deployable.*

Pattern 3: Complete Examples

# Complete working example (not fragment)
# Users can copy-paste and run
from framework import App

app = App()

@app.route("/")
def home():
    return {"message": "Works!"}

if __name__ == "__main__":
    app.run()

---

Checklist for This Example

Verify this example follows all rules:

• [x] ✅ No ../ relative paths anywhere
• [x] ✅ Essential content inlined (database, testing, deployment)
• [x] ✅ Complete working examples (not fragments)
• [x] ✅ Complementary skills listed informationally
• [x] ✅ Graceful degradation implemented
• [x] ✅ Works in flat directory deployment
• [x] ✅ metadata.json has self_contained: true
• [x] ✅ No skill dependencies in requires field
• [x] ✅ Tested in isolation successfully
• [x] ✅ All grep verification commands pass

---

Compare with Bad Example

See ../bad-interdependent-skill/ for anti-patterns to avoid.

---

Resources

• [SKILL_SELF_CONTAINMENT_STANDARD.md](../../docs/SKILL_SELF_CONTAINMENT_STANDARD.md): Complete standard
• [SKILL_CREATION_PR_CHECKLIST.md](../../docs/SKILL_CREATION_PR_CHECKLIST.md): PR checklist
• [CONTRIBUTING.md](../../CONTRIBUTING.md): General guidelines

---

Use this example as your template for creating new, properly self-contained skills.