Python Backend

What it does

When your agent uses it

• Building async services
• Wiring FastAPI dependencies
• Tuning database connection pools

Example prompts

• “/python-backend”

Requirements

• Python 3
• Docker
• Compatibility (from SKILL.md): Claude Code 2.1.277+.
• Pre-approved tools (allowed-tools): Read, Glob, Grep, WebFetch, WebSearch

What it can do on your machine

Read from SKILL.md and the folder at commit 1f8d8f3. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves these tools, so the agent can use them without asking each time:

  • Read
  • Glob
  • Grep
  • WebFetch
  • WebSearch

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Ships 1 file in scripts/ (Python, from the files we listed), which the agent can run.

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Links to these hosts (documentation or services it may open):

  • docs.python.org
  • fastapi.tiangolo.com
  • docs.sqlalchemy.org
  • magicstack.github.io
  • docs.aiohttp.org
  • postgresql.org
  • pytest-asyncio.readthedocs.io
  • kubernetes.io

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

• Compatibility

  Claude Code 2.1.277+.

  From compatibility in the SKILL.md frontmatter.

Context cost

Python Backend loads about 2.8k tokens when it runs, and up to ~6.5k if it reads all its reference files. Until then it costs about 112 tokens; SKILL.md has 778 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~112

When it runs · the whole SKILL.md, loaded when a task matches

~2.8k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~6.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

• NoteMentions a .env fileSKILL.md:104

  - **Pydantic Settings** with `.env` and field validation

• NoteMentions a .env fileSKILL.md:113

  | Settings | Pydantic Settings with .env |

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from yonatangross/orchestkit at commit 1f8d8f3, republished under its MIT licence (© yonatangross). 778 words, ~2,831 tokens.

name

python-backend

description

Production Python async patterns including asyncio TaskGroup, FastAPI dependency injection and middleware, SQLAlchemy 2.0 async sessions, and database connection pool tuning. Python 3.11+ runtime concerns such as ExceptionGroup, cancellation semantics, and session rollback. Use when building async services, wiring FastAPI dependencies, or tuning database connection pools. Runtime implementation layer, not the API wire contract.

allowed-tools

Read, Glob, Grep, WebFetch, WebSearch

compatibility

Claude Code 2.1.277+.

license

MIT

context

fork

agent

backend-system-architect

user-invocable

false

disable-model-invocation

false

metadata.category

document-asset-creation

metadata.version

2.0.0

metadata.author

OrchestKit

metadata.complexity

medium

metadata.tags

python, asyncio, fastapi, sqlalchemy, connection-pooling, async, postgresql

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

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

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

pool_size = (concurrent_requests / avg_queries_per_request) * 1.5

# 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

© yonatangross, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 25 other files (scripts, references, assets) in src/skills/python-backend of yonatangross/orchestkit.

• SKILL.md
• assets/fastapi-app-template.py
• metadata.json
• references/eager-loading.md
• references/fastapi-app-boilerplate.md
• references/ork-delta.md
• rules/_sections.md
• rules/_template.md
• rules/asyncio-cancellation.md
• rules/asyncio-structured.md
• rules/asyncio-taskgroup.md
• rules/fastapi-background.md
• rules/fastapi-dependencies.md
• rules/fastapi-middleware.md
• rules/pooling-database.md
• rules/pooling-http.md
• rules/pooling-tuning.md
• rules/sqlalchemy-migrations.md
• … and 8 more

Open the folder on GitHubat commit 1f8d8f3