playbooks

home / skills / yugasun / skills / server

server skill

/skills/server

This skill helps you scaffold and maintain a FastAPI backend in server/ with Async SQLAlchemy, migrations, and AI tooling.

npx playbooks add skill yugasun/skills --skill server

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
2.3 KB
---
name: dev-server
description: Create and manage Python backend services using uv, FastAPI, Pydantic, SQLAlchemy, and AI libraries. Use this skill when the user asks to build a backend, API, or server-side application.
metadata:
  author: Yuga Sun
  version: "2026.01.29"
---

# Server Development Skill

## Instructions

Use this skill to scaffold and maintain backend services in the `server/` directory. Follow the stack preferences and configuration details below.

### Quick Start

1.  **Initialize**: `uv init`.
2.  **Manager**: Use `uv` for all dependency operations.
3.  **Framework**: Setup `FastAPI` with `Pydantic`.
4.  **Database**: configure `SQLAlchemy` (Async) + `Alembic`.

## Core Stack Preferences

### Project Management (uv)

Use **uv** for all Python project management (scaffolding, dependency management, virtual environments).

| Command | Description |
|---------|-------------|
| `uv init` | Initialize a new project |
| `uv add <pkg>` | Add dependency |
| `uv add --dev <pkg>` | Add development dependency |
| `uv run <cmd>` | Run command in virtual environment |
| `uv venv` | Create virtual environment |

### Project Location

The backend project should be initialized in the `server/` directory.

### Framework (FastAPI)

Use **FastAPI** for building APIs.

-   Use `APIRouter` for modularizing routes.
-   Use `pydantic-settings` for configuration management.

### Database (SQLAlchemy + Alembic)

Use **SQLAlchemy 2.0+** with **AsyncIO** support.
Use **Alembic** for database migrations.

### AI & LLM (LiteLLM + Docling)

-   **LiteLLM**: For standardized access to various LLM providers.
-   **Docling**: For parsing and processing documents.

---

## References

### Setup & Configuration

| Topic | Description | Reference |
|-------|-------------|-----------|
| Project Setup | Using uv, strict python versioning, and environment variables | [setup](references/setup.md) |
| API Development | FastAPI structure, error handling, and validation | [api](references/api.md) |

### Data & Architecture

| Topic | Description | Reference |
|-------|-------------|-----------|
| Database Access | Async SQLAlchemy strategies and Alembic migrations | [database](references/database.md) |
| AI Integration | using LiteLLM and Docling for AI features | [ai](references/ai.md) |

Overview

This skill creates and manages Python backend services using uv, FastAPI, Pydantic, SQLAlchemy, and AI libraries. It scaffolds a server/ project, configures async SQLAlchemy with Alembic migrations, and wires in lightweight AI integrations. Use it to bootstrap production-ready APIs with clear conventions and maintainable structure.

How this skill works

The skill initializes projects under the server/ directory with uv and uses uv for all dependency and virtual environment operations. It scaffolds FastAPI app structure with APIRouter modules, Pydantic settings for configuration, and async SQLAlchemy plus Alembic for database access and migrations. Optional AI features are prepared using LiteLLM for model access and Docling for document parsing, integrated into service layers or background jobs.

When to use it

  • Starting a new Python backend or API service and you want a consistent, opinionated stack.
  • Converting a prototype into a maintainable async FastAPI app with database migrations.
  • Adding AI features like document parsing or LLM endpoints to an existing service.
  • Standardizing development workflows across teams using uv for dependency and environment management.
  • Creating modular route structure and robust configuration management via pydantic-settings.

Best practices

  • Initialize the backend in server/ using uv init and manage packages with uv add to keep environments reproducible.
  • Use APIRouter to split endpoints into focused modules and keep business logic separate from route handlers.
  • Prefer async SQLAlchemy 2.0 patterns and run Alembic migrations for schema changes rather than ad-hoc scripts.
  • Store secrets and runtime config in pydantic-settings and load via environment variables for 12-factor compliance.
  • Keep AI integration modular: wrap LiteLLM and Docling calls behind service interfaces to allow provider swaps and testing.

Example use cases

  • Bootstrap a new customer-facing REST API with authentication, CRUD endpoints, and async DB access.
  • Add an /ingest endpoint that parses uploaded documents with Docling and indexes content for search.
  • Expose a secure LLM-powered assistant endpoint using LiteLLM for product support or automated summaries.
  • Migrate data models safely by creating Alembic revisions after evolving SQLAlchemy models.
  • Create background tasks or worker processes that call AI services without blocking request handling.

FAQ

Do I have to use uv for everything?

Yes: this skill uses uv as the canonical project manager for scaffolding, dependency management, and venv handling to ensure reproducible workflows.

Can I use a different LLM provider?

Absolutely. LiteLLM provides a standardized adapter layer; swap providers by changing configuration and adapter implementation without touching business logic.