Flask

Flask Python Web AI Skill Guide

Overview & Engine Architecture

Flask is a WSGI microframework with explicit application factories, blueprints for modular routes, and a request/app context stack. Agents prefer factory + blueprint layout over a single global app, keep config in environment-backed objects, and run production traffic behind gunicorn/uwsgi - not the built-in server.

WSGI server (gunicorn)
        |
   create_app()
   +----+----+----+
   | blueprints    |
   | extensions    |
   | errorhandlers |
   +---------------+

When to use this skill

• Building small-to-medium Python HTTP APIs or server-rendered apps
• Structuring multi-module Flask projects
• Adding auth, DB, or migrations via extensions
• Writing route tests with the Flask test client

Operational directives

1. Use create_app() so tests and CLI can construct fresh apps.
2. Register blueprints with URL prefixes; avoid circular imports via late imports or extension init.
3. Load secrets from env (SECRET_KEY, DB URLs) - never hardcode.
4. Prefer JSON error handlers with correct status codes for APIs.
5. Use the production WSGI server in deploy; app.run() is local-only.

App factory sketch

from flask import Flask, Blueprint, jsonify, request

api = Blueprint("api", __name__)

@api.get("/health")
def health():
    return jsonify(ok=True)

@api.post("/items")
def create_item():
    body = request.get_json(silent=True) or {}
    sku = body.get("sku")
    if not isinstance(sku, str) or not sku:
        return jsonify(error="sku required"), 400
    return jsonify(id=1, sku=sku), 201

def create_app() -> Flask:
    app = Flask(__name__)
    app.config.from_mapping(SECRET_KEY="dev-only-change-me")
    app.register_blueprint(api, url_prefix="/api")
    return app

Commands

flask --app "app:create_app" run --debug
gunicorn "app:create_app()"
pytest -q

Testing sketch

from app import create_app

def test_health():
    app = create_app()
    client = app.test_client()
    r = client.get("/api/health")
    assert r.status_code == 200
    assert r.get_json()["ok"] is True

Best practices

• Separate config classes (Development, Production, Testing).
• Use Flask-SQLAlchemy / Alembic or a thin DB layer - keep models out of route modules when possible.
• Enable CSRF protection for cookie-session form posts.
• Log exceptions once in a central handler; avoid duplicate noise.

Limitations

• Async views exist in newer Flask but most extensions remain sync-first.
• Large async-native APIs may fit FastAPI better.
• Application context mistakes surface as "Working outside of application context" - fix factory/CLI wiring.

Related skills

• @fastapi - async-first alternative for OpenAPI-heavy APIs
• @python-packaging - project layout, tooling, publishing
• @docker - containerizing gunicorn workers