From zegging-skills
Guide the creation, iteration, and long-term maintenance of FastAPI projects with production-oriented structure, dependency design, async boundaries, schema discipline, testing, and operations hygiene. Use this skill whenever the user is building or cleaning up a FastAPI backend, organizing modules, designing services or dependencies, adding schemas/models, fixing async or blocking behavior, introducing auth or validation boundaries, setting up tests or migrations, or asking for FastAPI best practices even if they do not explicitly ask for "architecture" or "maintenance".
How this skill is triggered — by the user, by Claude, or both
Slash command
/zegging-skills:fastapi-project-stewardThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Use this skill to help users build or improve FastAPI projects in a way that stays understandable as the codebase grows.
Use this skill to help users build or improve FastAPI projects in a way that stays understandable as the codebase grows.
The goal is not to produce the smallest demo app. The goal is to produce a codebase that is predictable, testable, and maintainable after many iterations. Keep changes proportional to the user's scope: improve the shape of the codebase without forcing a full rewrite for a small task.
Prioritize these qualities:
When there is a tradeoff, prefer the smallest structure that keeps future changes safe and legible.
Use this skill when the user is doing any of the following in a FastAPI codebase:
Start by identifying which lifecycle stage the user is in:
Then adapt depth accordingly.
Before proposing structure changes:
For a small change, do not force a giant architecture rewrite. For a growing codebase, favor patterns that reduce future churn.
Follow this sequence unless the user already narrowed the task:
If the user only needs advice, still anchor the answer in a concrete next step such as a proposed file layout, a refactor sequence, or an execution-boundary fix.
Prefer module-oriented structure over splitting the whole app into global routers/, models/, schemas/, and crud/ buckets.
Good default:
app/
auth/
router.py
schemas.py
models.py
dependencies.py
service.py
exceptions.py
constants.py
users/
router.py
schemas.py
models.py
dependencies.py
service.py
exceptions.py
core/
config.py
logging.py
middleware.py
db/
base.py
engine.py
session.py
mixins.py
services/
mailer.py
storage.py
main.py
Notes:
Routes should stay thin.
Route handlers should usually do only these things:
Avoid putting complex business logic directly in handlers.
Use dependencies for reusable request-scoped concerns, especially when they validate or enrich request context.
Strong use cases:
Design guidance:
async dependencies unless there is a clear reason not to.Prefer explicit service boundaries over route-level business sprawl.
Use service classes when they improve organization, especially if:
Keep services focused on business behavior, not HTTP transport details.
If persistence logic becomes substantial, it is reasonable to split repository/data-access concerns from higher-level service logic.
Do not create a service class only for ceremony. A small module-level service function is fine when the domain is still simple.
Treat async boundaries as a correctness concern, not just a style preference.
async def for handlers and dependencies that await non-blocking I/O.If you spot time.sleep, blocking file/network SDK calls, or long sync computations inside async routes, call it out and fix the execution boundary.
Use Pydantic models and Python types aggressively to make data contracts explicit.
Recommended patterns:
Be careful with validation behavior:
ValueError messagesPrefer clear SQL/data-access logic over excessive Python-side data reshaping.
Avoid hidden or deeply nested session lifecycle management inside service methods. Prefer explicit session ownership patterns that are consistent across the codebase.
Favor consistent RESTful design so validation and dependencies can be reused cleanly.
_at for datetimes and _date for datesConsistency matters because it reduces duplicated validation and makes the codebase easier to scan.
When adding or changing endpoints:
response_model, status_code, summary, and description when usefulIf a custom response strategy is used, watch for drift between actual responses and declared API docs.
When changing core behavior, add tests.
Prefer:
For async stacks, set up the test client and fixtures in an async-friendly way early rather than patching it later after event loop issues appear.
When the user is refactoring without changing behavior, prioritize tests around the boundaries most likely to regress before moving code around.
Keep configuration explicit and maintainable.
When the project needs background jobs, worker processes, or event/message hubs, introduce them as explicit architecture choices rather than as ad hoc helper calls hidden in routes.
When you see these, prefer to fix them rather than copying them forward:
crud.py sprawl across the whole appMatch the output to the task.
If the user asks for implementation:
If the user asks for architecture advice:
If the user asks for review/refactor guidance:
Keep answers concrete. Prefer showing the smallest safe structure or patch over a generic catalog of best practices.
Example 1:
Input: "帮我给 FastAPI 项目加一个订单模块,顺便把代码结构整理一下。"
Output: Propose a module-oriented orders/ package, keep routes thin, introduce request/response schemas, move business rules into service layer, add dependencies for auth/resource validation, and mention tests/migrations.
Example 2:
Input: "Why is my FastAPI app becoming unresponsive when one endpoint calls a legacy SDK?"
Output: Inspect whether blocking sync I/O is being called inside async def, move the legacy SDK call to a threadpool if it is I/O-bound, and explain when a worker process is needed instead.
Example 3: Input: "我们想把现在到处 scattered 的鉴权校验整理一下。" Output: Consolidate repeated checks into reusable dependencies or explicit permission abstractions, reduce duplication in routes, and keep auth context parsing request-scoped and composable.
npx claudepluginhub zegging/zegging-skills --plugin fastapi-project-stewardGenerates production-ready FastAPI project structures with async patterns, dependency injection, middleware, error handling, and best practices for high-performance APIs.
Guides FastAPI app development with Pydantic models, dependency injection, async DB access via SQLAlchemy/asyncpg, background tasks, WebSockets, and testing. Activates on FastAPI, Pydantic, or async Python API queries.
Provides FastAPI best practices for project structure, Pydantic v2 schemas, dependency injection, async handlers, auth, transactional service layers, and testing with httpx and pytest.