---

name: serve-deployments description: "Develop, run, deploy, configure, update, lint, and troubleshoot Ray Serve applications and deployments." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Ray Serve Deployments

Use this sub-skill when the task mentions ray.serve, @serve.deployment, serve.run, Deployment.bind, Serve YAML, serve run, serve deploy, serve build, serve status, serve config, HTTP/gRPC endpoints, autoscaling_config, runtime_env, user_config, or in-place Serve updates.

Ray Serve is Ray's Python serving layer for online inference APIs and general Python web services. Default to the narrow install extra ray[serve]; avoid recommending ray[all] unless the user explicitly needs many unrelated Ray libraries.

Route the task

• For Python application code, deployment decorators, handles, batching, FastAPI ingress, or local serve.run, use references/api-reference.md.
• For Serve YAML, serve build, serve deploy, serve run <config.yaml>, runtime_env, HTTP/gRPC/proxy/logging fields, or in-place update planning, use references/configuration.md.
• For import errors, config validation, blocked serve run, idempotent deploy confusion, remote URI failures, HTTP/gRPC symptoms, and status/config debugging, use references/troubleshooting.md.
• For config linting without contacting a Ray cluster, run scripts/serve_config_lint.py.
• For a tiny self-contained deployment pattern or optional local smoke check, use scripts/serve_smoke_app.py.
• For generic Ray cluster lifecycle, dashboard, node resources, ray start, or ray status, route to ../cluster-ops/SKILL.md.
• For training, tuning, or model development workflows before serving, route to ../train-tune/SKILL.md.

Default workflow

1. Confirm the user is working on Serve rather than generic Ray cluster operations.
2. For new apps, write a Python module with @serve.deployment, bind an application object, then test importability before starting Serve.
3. For local development, use serve run module:app --app-dir . or a small guarded script; remember the CLI blocks by default.
4. For production-style deployment, generate or maintain a Serve YAML and use serve deploy config.yaml against an already running Ray cluster.
5. After deploys or updates, inspect serve status and serve config; do not assume serve deploy blocks until replicas are healthy.
6. Use lightweight in-place updates only for deployment options that Serve can apply without replica restarts; plan code updates separately.

Bundled helpers

python scripts/serve_config_lint.py serve_config.yaml
python scripts/serve_smoke_app.py --validate-only

The helpers are safe by default: the linter only parses YAML, and the smoke app only validates imports/configuration unless --run-local is explicitly passed.