backend-fastapi-python skill
✓ VerifiedDevelop Python backends using FastAPI, SQLModel, and async SQLAlchemy with specific patterns for services, authentication, and error handling.
- GitHub stars
- 126
- Files
- 12
- Last commit
- May 16, 2026
- License
- MIT
- Allowed tools
- —
What does the backend-fastapi-python skill do?
backend-fastapi-python is an agent skill. Develop Python backends using FastAPI, SQLModel, and async SQLAlchemy with specific patterns for services, authentication, and error handling.
Summary generated from the skill's SKILL.md.
About the backend-fastapi-python skill
Building Python backends using FastAPI, SQLModel, and async SQLAlchemy is the primary function of this skill. Developers use it to construct API endpoints, write stateless service functions, and define Pydantic or SQLModel schemas. It is specifically designed for backend architecture tasks, including setting up authentication dependency chains like get_current_user and is_superuser, managing async SQLAlchemy sessions, and handling Alembic migrations.
An agent should load this skill whenever a task involves Python API code, request/response design, or backend patterns within this codebase. It provides guidance on specific project conventions, such as using the ApiResponse[T] wrapper and implementing AppException for error codes. The skill helps navigate technical constraints like avoiding N+1 queries with selectinload, managing background tasks, and ensuring correct Pydantic V2 validator usage. It does not cover frontend development, Docker, CI/CD, or general infrastructure.
What an agent can do with it
- 1Implement secure API endpointsCreate FastAPI routes that use dependency injection for role-based access control.
- 2Manage database schemas and migrationsDefine ORM models and run Alembic migrations to update the database structure.
- 3Develop stateless service layersWrite service functions that interact with the database using an async session.
- 4Debug API response issuesTroubleshoot why certain fields are missing from API responses or why 422 errors occur.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the backend-fastapi-python skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the backend-fastapi-python skill in Claude Code
~/.claude/skills/backend-fastapi-python/SKILL.md
$ npx degit avibebuilder/claude-prime/.claude/starter-skills/backend-fastapi-python ~/.claude/skills/backend-fastapi-pythonInstall the backend-fastapi-python skill in Claude Code (project)
.claude/skills/backend-fastapi-python/SKILL.md
$ npx degit avibebuilder/claude-prime/.claude/starter-skills/backend-fastapi-python .claude/skills/backend-fastapi-pythonInstall the backend-fastapi-python skill in Codex
~/.agents/skills/backend-fastapi-python/SKILL.md
$ npx degit avibebuilder/claude-prime/.claude/starter-skills/backend-fastapi-python ~/.agents/skills/backend-fastapi-pythonInstall the backend-fastapi-python skill in Gemini CLI
~/.gemini/skills/backend-fastapi-python/SKILL.md
$ npx degit avibebuilder/claude-prime/.claude/starter-skills/backend-fastapi-python ~/.gemini/skills/backend-fastapi-pythonInstall the backend-fastapi-python skill in Claude.ai
npx degit avibebuilder/claude-prime/.claude/starter-skills/backend-fastapi-python backend-fastapi-python && zip -r backend-fastapi-python.zip backend-fastapi-python # claude.ai → Customize → Skills → + → Create skill → Upload a skill → backend-fastapi-python.zip
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachableavibebuilder/claude-prime/.claude/starter-skills/backend-fastapi-python is public and reachablegithub.com/avibebuilder/claude-prime/tree/HEAD/.claude/start ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-05-16github.com/avibebuilder/claude-prime/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/avibebuilder/claude-prime/blob/HEAD/.claude/start ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/avibebuilder/claude-prime/blob/HEAD/.claude/start ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 47 linesgithub.com/avibebuilder/claude-prime/blob/HEAD/.claude/start ↗Pass
SKILL.md
View on GitHubBackend FastAPI Python
Project-specific conventions for FastAPI with SQLModel, pydantic-settings, and async SQLAlchemy.
Architecture Decisions
- Services are stateless functions — Not classes. First param is
db: AsyncSession. - Generic response wrapper — Always use
ApiResponse[T]for consistency. - Dependencies chain —
get_current_user->require_auth->require_admin. - Module-scoped config — Each module can have its own
{module}_config.py. - Error codes for frontend —
AppException(status, message, error_code).
Gotchas
- SQLModel
Relationship()fields are NOT included in API responses by default. You must explicitly add them tomodel_configor use a separate response schema with those fields. AsyncSession.refresh()does not load relationships. After commit, re-query with.options(selectinload(...))if you need related objects.- Pydantic V2 uses
model_validatornotvalidator. The@validatordecorator is V1 and will break silently or raise deprecation warnings. Depends()in FastAPI creates a NEW instance per request — don't store state in dependency return values expecting it to persist.- Background tasks (
BackgroundTasks) run AFTER the response is sent. If they fail, the client already got a 200. Use proper task queues (Celery, ARQ) for anything that must not silently fail. - Alembic
--autogeneratemisses: table renames (generates drop+create), index changes on existing columns, andEnumtype modifications in PostgreSQL. Always review generated migrations. async defendpoints block the event loop if you call sync I/O inside them. Userun_in_executorfor sync libraries or define the endpoint asdef(FastAPI runs sync endpoints in a threadpool).HTTPExceptionfrom FastAPI andHTTPExceptionfrom Starlette are different classes. Importing the wrong one causes middleware to miss exception handlers.- SQLAlchemy's
lazy="selectin"on relationships causes N+1 queries in async sessions. Use explicitselectinload()in queries instead. Optional[str] = Nonein query params makes the field optional.str = Nonealso works but loses type information — prefer the explicitOptionalform.- When using
response_model, FastAPI filters OUT any fields not in the model. If your response is missing data, check that the response model includes all fields, not just the ORM model.
References
| When you need... | Read |
|---|---|
| Directory layout | file-structure.md |
| Settings and env vars | configuration.md |
| Database sessions and connections | database.md |
| ORM models | models.md |
| Request/response schemas | schemas.md |
| Router and endpoint patterns | routing.md |
| Service layer patterns | services.md |
| Dependency injection | dependencies.md |
| Middleware setup | middleware.md |
| Error handling | error-handling.md |
| Auth flow example | auth.md |
Files in this skill
12backend-fastapi-python skill questions
How do I install the backend-fastapi-python skill in Claude Code?
Run npx degit avibebuilder/claude-prime/.claude/starter-skills/backend-fastapi-python ~/.claude/skills/backend-fastapi-python. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the backend-fastapi-python skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How should service functions be structured in this project?
Services should be implemented as stateless functions rather than classes, where the first parameter is always an AsyncSession.
What should I do if SQLModel relationship fields are missing from API responses?
SQLModel Relationship fields are not included by default; you must explicitly add them to the model_config or use a separate response schema.
How do I handle background tasks that must not fail silently?
Since BackgroundTasks run after the response is sent, use proper task queues like Celery or ARQ for critical tasks that cannot fail silently.
What is the correct way to load related objects after an AsyncSession.refresh()?
Because refresh() does not load relationships, you should re-query the object using .options(selectinload(...)) to retrieve related data.