Skip to main content
skill CX Codex

python-backend · yonatangross — Claude Code skill: what it does, how to install

python-backend — a skill for Claude Code and Codex providing async Python patterns when editing *.py or package files. Enforces conventions for FastAPI, SQLAlchemy 2.0, and asyncio.

MIT 250 installs ★ 305 updated 2026-11-14

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add yonatangross/orchestkit --skill python-backend -a claude-code
Open on GitHub

What python-backend does

The skill provides 12 production rules spanning asyncio, FastAPI, SQLAlchemy 2.0, and connection pooling. It swaps out gather() for structured concurrency via TaskGroup, enforces re-raising CancelledError, and routes blocking synchronous calls through asyncio.to_thread().

Database interactions use request-scoped AsyncSession instances with expire_on_commit=False and lazy="raise" across relationships to avoid accidental N+1 queries. It also includes pool sizing guidance based on concurrent requests and average query volume per transaction.

Targets include FastAPI version 0.142.2 or newer and SQLAlchemy version 2.1.1 or newer. API contract design and RFC 9457 problem detail bodies are excluded, as those belong to the separate api-design skill.

What it helps with

  • refactor legacy gather() calls to asyncio.TaskGroup
  • wire scoped AsyncSession dependency injection into FastAPI routes
  • prevent hidden N+1 queries using lazy="raise" and selectinload
  • size database connection pools with proper concurrency ratios

Example prompts for the agent

  • Create a FastAPI endpoint fetching records with an injected AsyncSession
  • Implement concurrent URL fetching using TaskGroup with a strict timeout
  • Set up FastAPI lifespan management for an asyncpg database pool

How to install python-backend

1Skills CLI (Vercel)

npx skills add yonatangross/orchestkit --skill python-backend -a claude-code

2Manually: put the files in place

~/.claude/skills/python-backend/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/python-backend/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about python-backend

How to install python-backend in Claude Code?

Run npx skills add yonatangross/orchestkit --skill python-backend -a claude-code. The file is placed in ~/.claude/skills/python-backend/SKILL.md.

What does python-backend do?

It instructs coding agents on async Python standards, covering structured concurrency, FastAPI dependencies, and SQLAlchemy 2.0 sessions.

What library versions does python-backend require?

It targets fastapi >=0.142.2, sqlalchemy >=2.1.1, and requires Claude Code version 2.1.277 or higher.

Source text

SKILL.md · MIT
---
name: python-backend
license: MIT
compatibility: "Claude Code 2.1.277+."
description: "Async Python: asyncio TaskGroup, FastAPI dependencies and middleware, SQLAlchemy 2.0 async sessions, pool tuning. Not for the API contract (use api-design)."
user-invocable: false
disable-model-invocation: false
targets:
  - library: fastapi
    version: ">=0.142.2"
  - library: sqlalchemy
    version: ">=2.1.1"
metadata:
  owner-agent: "backend-system-architect"
  category: document-asset-creation
  version: "2.0.0"
  author: "OrchestKit"
  complexity: "medium"
  tags: "python, asyncio, fastapi, sqlalchemy, connection-pooling, async, postgresql"
allowed-tools: "Read Glob Grep WebFetch WebSearch"
path_patterns: ["*.py", "**/requirements*.txt", "**/pyproject.toml", "**/Pipfile"]
---

<!-- directive-density: intentional (teaches asyncio/SQLAlchemy anti-patterns; NEVER markers describe real event-loop/race-condition bugs, not aspirational guidance) -->

# Python Backend

Patterns for building production Python backends with asyncio, FastAPI, SQLAlchemy 2.0, and connection pooling. Each category has individual rule files in `rules/` loaded on-demand.

## Quick Reference

| Category | Rules | Impact | When to Use |
|----------|-------|--------|-------------|
| [Asyncio](#asyncio) | 3 | HIGH | TaskGroup, structured concurrency, cancellation handling |
| [FastAPI](#fastapi) | 3 | HIGH | Dependencies, middleware, background tasks |
| [SQLAlchemy](#sqlalchemy) | 3 | HIGH | Async sessions, relationships, migrations |
| [Pooling](#pooling) | 3 | MEDIUM | Database pools, HTTP sessions, tuning |

**Total: 12 rules across 4 categories.** House decisions rescued from thinned files live in `references/ork-delta.md`; vendor material is linked, not restated (see [Upstream coverage](#upstream-coverage-do-not-restate)).

## Quick Start

```python
# FastAPI + SQLAlchemy async session
async def get_db() -> AsyncGenerator[AsyncSession, None]:
    async with async_session_factory() as session:
        try:
            yield session
            await session.commit()
        except Exception:
            await session.rollback()
            raise

# Reusable dependency alias (FastAPI's recommended Annotated form)
SessionDep = Annotated[AsyncSession, Depends(get_db)]

@router.get("/users/{user_id}")
async def get_user(user_id: UUID, db: SessionDep):
    result = await db.execute(select(User).where(User.id == user_id))
    return result.scalar_one_or_none()
```

```python
# Asyncio TaskGroup with timeout
async def fetch_all(urls: list[str]) -> list[dict]:
    async with asyncio.timeout(30):
        async with asyncio.TaskGroup() as tg:
            tasks = [tg.create_task(fetch_url(url)) for url in urls]
    return [t.result() for t in tasks]
```

## Asyncio

Modern Python asyncio patterns using structured concurrency, TaskGroup, and Python 3.11+ features.

### Key Patterns

- **TaskGroup** replaces `gather()` with structured concurrency and auto-cancellation
- **`asyncio.timeout()`** context manager for composable timeouts
- **Semaphore** for concurrency limiting (rate-limit HTTP requests)
- **`except*`** with ExceptionGroup for handling multiple task failures
- **`asyncio.to_thread()`** for bridging sync code to async

### Key Decisions

| Decision | Recommendation |
|----------|----------------|
| Task spawning | TaskGroup not gather() |
| Timeouts | asyncio.timeout() context manager |
| Concurrency limit | asyncio.Semaphore |
| Sync bridge | asyncio.to_thread() |
| Cancellation | Always re-raise CancelledError |

## FastAPI

Production-ready FastAPI patterns for lifespan, dependencies, middleware, and settings.

### Key Patterns

- **Lifespan** with `asynccontextmanager` for startup/shutdown resource management
- **Dependency injection** with class-based services and `Depends()`
- **Middleware stack**: CORS -> RequestID -> Timing -> Logging
- **Pydantic Settings** with `.env` and field validation
- **Exception handlers** wired to RFC 9457 Problem Details bodies (the body format itself is `ork:api-design`)

### Key Decisions

| Decision | Recommendation |
|----------|----------------|
| Lifespan | asynccontextmanager (not events) |
| Dependencies | Class-based services with DI |
| Settings | Pydantic Settings with .env |
| Response | ORJSONResponse for performance |
| Health | Check all critical dependencies |

## SQLAlchemy

Async database patterns with SQLAlchemy 2.0, AsyncSession, and FastAPI integration.

### Key Patterns

- **One AsyncSession per request** with `expire_on_commit=False`
- **`lazy="raise"`** on relationships to prevent accidental N+1 queries
- **`selectinload`** for eager loading collections
- **Repository pattern** with generic async CRUD
- **Bulk inserts** chunked 1000-10000 rows for memory management

### Key Decisions

| Decision | Recommendation |
|----------|----------------|
| Session scope | One AsyncSession per request |
| Lazy loading | lazy="raise" + explicit loads |
| Eager loading | selectinload for collections |
| expire_on_commit | False (prevents lazy load errors) |
| Pool | pool_pre_ping=True |

## Pooling

Database and HTTP connection pooling for high-performance async Python applications.

### Key Patterns

- **SQLAlchemy pool** with `pool_size`, `max_overflow`, `pool_pre_ping`
- **Direct asyncpg pool** with `min_size`/`max_size` and connection lifecycle
- **aiohttp session** with `TCPConnector` limits and DNS caching
- **FastAPI lifespan** creating and closing pools at startup/shutdown
- **Pool monitoring** with Prometheus metrics

### Pool Sizing Formula

```
pool_size = (concurrent_requests / avg_queries_per_request) * 1.5
```

That formula sizes one process. The fleet-level cap against the server's
`max_connections`, and the pool alert thresholds, are in `references/ork-delta.md`.

## Anti-Patterns (FORBIDDEN)

```python
# NEVER use gather() for new code - no structured concurrency
# NEVER swallow CancelledError - breaks TaskGroup and timeout
# NEVER block the event loop with sync calls (time.sleep, requests.get)
# NEVER use global mutable state for db sessions
# NEVER skip dependency injection (create sessions in routes)
# NEVER share AsyncSession across tasks (race condition)
# NEVER use sync Session in async code (blocks event loop)
# NEVER create engine/pool per request
# NEVER forget to close pools on shutdown
```

## Upstream coverage (do not restate)

Topics removed in the 2026-07-31 wrap-plus-delta thinning. Consult the first-party source; only the ork delta (house policy, scars, working config) belongs in this skill. Where a row says a house subset stays in a `rules/` file, that file is still the authority for the OrchestKit position and the link only covers the vendor surface around it.

| Topic | First-party source |
|-------|--------------------|
| asyncio task API reference: TaskGroup vs `gather()`, `asyncio.timeout()`, `ExceptionGroup` and `except*`, `to_thread()`. House subset stays in `rules/asyncio-taskgroup.md` and `rules/asyncio-cancellation.md`. | https://docs.python.org/3/library/asyncio-task.html |
| `asyncio.Semaphore`, `Lock`, `Event`, `Queue` semantics. House subset stays in `rules/asyncio-structured.md`; the create-once-plus-timeout rule is in `references/ork-delta.md`. | https://docs.python.org/3/library/asyncio-sync.html |
| Event-loop debug mode, `slow_callback_duration`, detecting blocking calls (the house 100 ms threshold is in `references/ork-delta.md`) | https://docs.python.org/3/library/asyncio-dev.html |
| FastAPI project scaffolding: app layout, `APIRouter` composition, Pydantic Settings wiring, uvicorn entry point | https://fastapi.tiangolo.com/tutorial/bigger-applications/ |
| FastAPI lifespan API and startup/shutdown mechanics. House subset stays in `rules/fastapi-background.md`; the reverse-order teardown rule is in `references/ork-delta.md`. | https://fastapi.tiangolo.com/advanced/events/ |
| Starlette/FastAPI middleware API, `BaseHTTPMiddleware`, `call_next`, CORS options. House subset stays in `rules/fastapi-middleware.md` and `references/fastapi-app-boilerplate.md`; the middleware-vs-dependency split is in `references/ork-delta.md`. | https://fastapi.tiangolo.com/tutorial/middleware/ |
| SQLAlchemy 2.0 asyncio API: `create_async_engine`, `async_sessionmaker`, `expire_on_commit`, `Mapped`/`mapped_column`, `with_for_update`, bulk insert and update. House subset stays in `rules/sqlalchemy-sessions.md`, `rules/sqlalchemy-relationships.md`, `rules/sqlalchemy-migrations.md`, and `references/eager-loading.md`. | https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html |
| SQLAlchemy pool implementations and options (`pool_size`, `max_overflow`, `pool_pre_ping`, `pool_recycle`, `pool_timeout`). House subset stays in `rules/pooling-database.md`. | https://docs.sqlalchemy.org/en/20/core/pooling.html |
| SQLAlchemy pool events (`checkout`, `checkin`, `connect`) for instrumentation. House subset stays in `rules/pooling-tuning.md`; the alert thresholds are in `references/ork-delta.md`. | https://docs.sqlalchemy.org/en/20/core/events.html |
| asyncpg pool API: `create_pool`, `min_size`/`max_size`, `max_inactive_connection_lifetime`, `setup` hook, type codecs | https://magicstack.github.io/asyncpg/current/api/index.html |
| aiohttp client reference: `ClientSession`, `TCPConnector` limits, keep-alive, DNS caching, `ClientTimeout`. House subset stays in `rules/pooling-http.md`. | https://docs.aiohttp.org/en/stable/client_reference.html |
| PostgreSQL server-side connection limits (`max_connections`, `superuser_reserved_connections`) | https://www.postgresql.org/docs/current/runtime-config-connection.html |
| pytest-asyncio fixtures and async test setup | https://pytest-asyncio.readthedocs.io/en/stable/reference/fixtures/index.html |
| Container and Kubernetes packaging, readiness/liveness probes, resource limits | https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/ |
| Auth flows, password hashing, token expiry policy, security headers | Owned by `ork:security-patterns` (`src/skills/security-patterns/`); the FastAPI `Depends()` auth chain stays in `rules/fastapi-dependencies.md` |
| RFC 9457 problem-details body format, API versioning, SSE and WebSocket wire contracts | Owned by `ork:api-design` (`src/skills/api-design/`); the FastAPI exception-handler wiring stays in `rules/fastapi-background.md` and `references/fastapi-app-boilerplate.md` |
| Production checklists for FastAPI, asyncio, SQLAlchemy, and pooling | Derivable from the sources above; no checklist restatement kept |

## Related Skills

- `ork:architecture-patterns` - Clean architecture and layer separation
- `ork-extras:async-jobs` - Celery/ARQ for background processing
- `ork:api-design` - Wire contract, RFC 9457 errors, SSE/WebSocket streaming
- `ork:database-patterns` - Database schema design
- `ork:security-patterns` - Auth, password hashing, token policy
- `ork:testing-integration` - pytest-asyncio and httpx ASGI test setup
- `ork:devops-deployment` - Docker and Kubernetes packaging

© OrchestKit · MIT · yonatangross/orchestkit

Similar skills

All skills for Backend and APIs →

python-backend by other authors comes first.

python-backend jiatastic Hands your agent working patterns for Python backends: FastAPI, async SQLAlchemy, JWT/OAuth2, Upstash caching and rate limits. Useful when the agent writes your API. CX Codex +1 2,200installs python-backend-expert platform-team python-backend-expert is a Claude Code skill for implementing FastAPI backends with SQLAlchemy 2.0 and Pydantic v2, including async routes, service layers, and Alembic migrations. CX Codex +1 138installs Python Backend Architecture Review rknall Python Backend Architecture Review — a skill that reviews Python backend architecture: patterns, database, API, security, scalability. Useful when the design doc exists and you want the weak spots found before release. CX Codex +1 528installs fastapi-backend-template rebyteai-template fastapi-backend-template bootstraps a backend project using FastAPI, async SQLAlchemy 2.0, Alembic migrations, PostgreSQL, and Docker. Ideal for setting up a clean Python API structure. CX Codex +1 244installs supabase-python alinaqi supabase-python guides FastAPI application setup using Supabase for authentication and SQLAlchemy or SQLModel for database queries. CX Codex +1 298installs python-patterns davila7 python-patterns is a Claude Code skill that guides Python system design, including framework choices, async versus sync execution, project structure, and Pydantic validation. CX Codex +1 1,135installs python-pro VoltAgent Community python-pro — a subagent for type-safe Python code across web APIs, system utilities, and complex applications. Use it when async patterns and broad type coverage matter. CX Codex 11,689installs

From the same set86

The whole set →
monitoring-observability monitoring-observability — a skill for Claude Code that configures Prometheus metrics, Grafana dashboards, and Langfuse v4 tracing. Activates when adding logging, distributed tracing, or LLM cost tracking. CX Codex +1 270installs vite-advanced vite-advanced is a Claude Code and Codex skill for Vite 8 builds with Rolldown, chunk splitting, and Environment API. It activates when editing vite.config.* or files under **/vite/**. CX Codex +1 265installs quality-gates quality-gates scores task complexity on a 1–5 scale and halts work when requirements are vague or solutions loop. Triggers before complex tasks and after repeated failures. CX Codex +1 259installs code-review-playbook code-review-playbook supplies structured review workflows, conventional comment formats, and security checklists. Triggers during pull request evaluations or author self-reviews. CX Codex +1 254installs accessibility accessibility — a Claude Code skill for building accessible web interfaces. It activates for work on screen reader support, keyboard navigation, focus handling, and ARIA components. CX Codex +1 246installs memory-fabric memory-fabric is a Claude Code skill that orchestrates knowledge graph retrieval, parses queries, deduplicates facts, and ranks results. It runs when designing or debugging agent memory mechanics. CX Codex +1 244installs multimodal-llm multimodal-llm — a skill for Claude Code and Codex that routes tasks across vision, speech, and video models. The agent activates it when handling image analysis, audio transcription, or video generation APIs. CX Codex +1 243installs database-patterns The database-patterns skill guides schema design, Alembic migrations, and database versioning. It fits work on normalization, migration branches, and schema drift. CX Codex +1 238installs

Project sponsors

Companies that keep this analytics open