serverpod-overview - SKILL.md Agent Skill

name: serverpod-overview description: Serverpod overview — what it is, project structure, how to work with. Always use at least once when working with projects that use Serverpod.

Serverpod Overview

Serverpod is an open-source backend framework for Flutter written in Dart. A Serverpod project consists of usually three packages:

my_project_server - the server code. my_project_client - generated client code. my_project_flutter - a Flutter app (imports the client).

There can also be packages that share code, e.g., my_project_shared.

The server exposes endpoint classes that the client calls via generated RPC client. Add methods to the endpoints, the code generation will recreate them on the client side. Models are defined in YAML and generate Dart classes for both server and client.

Serverpod projects use a Postgres database for persistence and include an ORM, caching, real-time streaming (using Dart streams), file uploads, scheduling (called future calls), logging, and a built-in web server (Relic). Each of these features have specific skills that you can use to get more details.

Running the server

Most likely the server is already running with hot reload and serverpod generate --watch. NEVER attempt to start the server. The user is running the server with the serverpod start command (as an agent do NOT run this command, instead prompt the user to run serverpod start, if neccessary). Hot reload will update the generated code and quickly restart the server when files are changed.

ALWAYS use the MCP server instead of the command line. Use the MCP server to:

create_migration and apply_migrations for database (after you change data models).
tail_server_logs to read logs from the server.
tail_flutter_logs to read raw stdout/stderr from the Flutter app.
hot_restart will reload the server and the Flutter app. ALWAYS call it after doing changes in the Flutter app that may not work with normal hot reload (which is automatically applied).

Working on the project with no running instance

NEVER use the CLI unless you have already attempted to use the MCP.
ONLY if you cannot connect to the MCP server, the code can be generated by calling serverpod generate.
NEVER edit the generated code, as it will be overwritten by the next generation.

After generating the code, database migrations can be created by calling serverpod create-migration. Use ONLY if you cannot use the MCP.

# Use `--force` to create migrations with destructive changes
# Use the `--tag` flag to name the migration
serverpod create-migration [--force] [--tag <tag>]

See the Serverpod Migrations skill for more details.

Checklist after doing changes:

dart analyze (dart MCP server)
dart format (dart MCP server)
Do serverpod MCP hot_restart if required (hot reload is done automatically). Will also hot restart Flutter app
Check serverpod MCP tails_logs for any issues