Add a skill to help agents deploy python functions to vercel.

README.md

@@ -136,6 +136,25 @@ Preview URL: https://skill-deploy-abc123.vercel.app
 Claim URL:   https://vercel.com/claim-deployment?code=...
 ```
 
+### vercel-python
+
+Diagnose, fix, and prepare Python projects for Vercel deployments. Complements the deployment and CLI token skills with Python-specific runtime, framework, and dependency guidance.
+
+**Use when:**
+- Deploying FastAPI, Flask, Django, or generic ASGI/WSGI apps to Vercel
+- Fixing Python entrypoint, handler, or framework detection errors
+- Debugging `pyproject.toml`, `requirements.txt`, `uv`, lockfile, or `.python-version` issues
+- Investigating Python bundle size, runtime dependency installation, or Vercel Python diagnostics
+- Using the Vercel Python SDK or runtime helper APIs
+
+**Categories covered:**
+- Entrypoint and callable discovery
+- FastAPI, Flask, and Django deployment patterns
+- Python version and dependency manifest selection
+- `uv` and lockfile behavior
+- Bundle size and runtime dependency troubleshooting
+- Vercel Python SDK and runtime APIs
+
 ## Installation
 
 ```bash

skills/vercel-python/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: vercel-python
+description: Diagnose, fix, and prepare Python projects for Vercel deployments. Use for FastAPI, Flask, Django, ASGI/WSGI, Python entrypoints, pyproject.toml, requirements.txt, uv, .python-version, bundle size, Python runtime errors, or Vercel's Python SDK/runtime APIs. Use this skill whenever the user mentions Python and Vercel in the same context, even if they don't explicitly ask for deployment help.
+metadata:
+  author: vercel
+  version: "1.0.0"
+---
+
+# Vercel Python
+
+Use this skill when a Vercel deployment involves Python, including FastAPI, Flask, Django, generic ASGI/WSGI apps, Python runtime diagnostics, dependency resolution, Python version selection, bundle size issues, or the `vercel` Python SDK.
+
+This skill diagnoses and fixes Python-specific deployment issues. It does not handle the deployment itself.
+
+## How It Works
+
+1. **Inspect the project structure** before changing any files. Check the following:
+
+   **Entrypoint:** Identify the app entrypoint and confirm it exposes a supported top-level callable (`app`, `application`, or `handler`). The entrypoint priority is: `[tool.vercel].entrypoint` in `pyproject.toml`, then framework-specific discovery (Django uses the settings module; others use conventional files like `app.py`, `main.py`, etc.), then `[project.scripts].app` (legacy). For Django projects, if `manage.py` exists at the root or one directory below, check that the settings module defines `ASGI_APPLICATION` or `WSGI_APPLICATION`. See `references/runtime-and-entrypoints.md` for full details.
+
+   **Dependencies:** Identify the dependency manifest. Vercel discovers manifests from the entrypoint directory upward to the project root. The highest-priority manifest wins: `pyproject.toml` > `Pipfile.lock` / `Pipfile` > `requirements.txt` (and variants like `requirements.frozen.txt`, `requirements.in`, `requirements/prod.txt`). Check for a lockfile: `uv.lock` or `pylock.toml` (used with `pyproject.toml` projects). See `references/dependencies-and-versions.md` for the full priority list.
+
+   **Bundle size:** Vercel Python functions support up to [500 MB](https://vercel.com/docs/functions/limitations#bundle-size-limits). Do not use 250 MB as the limit. When a `uv.lock` is present, the builder can automatically externalize large public PyPI packages and install them at cold start, allowing even larger dependency sets. See `references/dependencies-and-versions.md` for size reduction strategies.
+
+   **Python version:** Check `.python-version` (takes priority) and `project.requires-python` in `pyproject.toml`. Vercel supports Python 3.12, 3.13, and 3.14 for new projects. Only flag a version as blocking if it excludes all supported versions (e.g., `==3.11.*`, `<3.12`, `>=3.15`). A range like `>=3.11` is fine because it includes 3.12+.
+
+   **Database:** If the project requires a database (PostgreSQL, MySQL, etc.), note that Vercel Marketplace provides managed database integrations (Neon Postgres, Supabase, AWS RDS) that automatically set connection environment variables. Do not assume the app cannot connect to a database on Vercel. See `references/frameworks.md` for details.
+
+   **Vercel config:** If `vercel.json` exists, check for custom `buildCommand` or `installCommand` (these can limit dependency optimization).
+
+   **Monorepo:** If the Python app is in a subdirectory of a monorepo, confirm `rootDirectory` is set correctly in the Vercel project settings. The builder resolves `uv.lock` from the workspace root automatically for uv workspace projects.
+
+   **Background workers:** If the project uses task queues, background jobs, or event-driven workers (Celery, Dramatiq, Django tasks, or similar), check `references/frameworks.md` for Vercel's worker service support via the `vercel-workers` package. Do not assume background processing is incompatible with Vercel.
+
+2. **Identify blockers and risks** from what you found:
+   - **Blocking:** No entrypoint file and no configurable path, no callable symbol, Python version that excludes all supported versions, malformed config files, Django without `manage.py`.
+   - **Risk:** No dependency manifest, custom build/install commands, Django without ASGI/WSGI settings.
+   - **Info:** Which manifest, lockfile, and Python version source were detected. Nonstandard entrypoint path (fixable with `[tool.vercel].entrypoint`).
+
+3. Read only the reference file that matches the problem:
+   - Entry points and runtime behavior: `references/runtime-and-entrypoints.md`
+   - Dependency manifests, `uv`, and Python versions: `references/dependencies-and-versions.md`
+   - FastAPI, Flask, Django, and static assets: `references/frameworks.md`
+   - Build/runtime errors: `references/troubleshooting.md`
+   - Python SDK and runtime helpers: `references/sdk-runtime-apis.md`
+
+4. Make the smallest safe project change that addresses the root cause, or give the user exact remediation when credentials, missing env vars, or account state block progress.
+
+5. **Verify.** Re-check the project against the same checklist from step 1. Confirm that no blocking findings remain and all risks have been documented or addressed.
+
+## Exit Criteria
+
+This skill's job is done when the Python project has no blocking deployment issues. It does not handle deployment, auth, environment variables, domains, or logs.
+
+## Common Misconceptions
+
+Do not accept these conclusions without checking the reference docs first:
+
+| Claim | Reality |
+|---|---|
+| "The bundle is too large for Vercel" | The limit is 500 MB, not 250 MB. With `uv.lock`, the builder externalizes public packages beyond that. |
+| "This app requires a database, so it can't deploy to Vercel" | Vercel Marketplace provides Neon Postgres, Supabase, and AWS RDS integrations. |
+| "Background processing is impossible on Vercel" | Vercel supports worker services via `vercel-workers` with Celery, Dramatiq, and Django task adapters. |
+| "Vercel doesn't support uv workspaces or monorepos" | It does. The builder resolves `uv.lock` from the workspace root. |
+| "This entrypoint path isn't supported" | Any path works with `[tool.vercel].entrypoint` in `pyproject.toml`. |
+| "Python version X.Y isn't compatible" | Only blocking if the range excludes all of 3.12, 3.13, and 3.14. Ranges like `>=3.11` are fine. |
+
+## Present Results to User
+
+Lead with the concrete blocker or readiness status:
+
+```text
+I inspected the Python project. Vercel should use `app/main.py` as the entrypoint with `app` as the ASGI callable. No blocking issues found.
+```
+
+When several findings exist, group them by deployment impact:
+
+- Blocking: prevents Vercel from building or routing the app.
+- Risk: likely runtime failure or slow/large deployment.
+- Info: useful context such as manifest, lockfile, or detected entrypoint.
+
+## Troubleshooting
+
+- Entrypoint or handler not found: inspect `references/runtime-and-entrypoints.md`.
+- Dependency sync, `uv`, lockfile, or Python version issues: inspect `references/dependencies-and-versions.md`.
+- FastAPI, Flask, Django, static assets, or `collectstatic` issues: inspect `references/frameworks.md`.
+- Vercel diagnostic codes such as `PYTHON_ENTRYPOINT_NOT_FOUND`, `PYTHON_HANDLER_NOT_FOUND`, `DJANGO_SETTINGS_FAILED`, `PYTHON_REQUIREMENTS_PARSE_ERROR`, `PYTHON_DEPENDENCY_SYNC_FAILED`, or `LAMBDA_SIZE_EXCEEDED`: inspect `references/troubleshooting.md`.
+- Runtime helper APIs such as Blob storage, OIDC, caching, geolocation, or cron scheduling: inspect `references/sdk-runtime-apis.md`.

skills/vercel-python/metadata.json

@@ -0,0 +1,13 @@
+{
+  "version": "1.0.0",
+  "organization": "Vercel",
+  "date": "April 2026",
+  "abstract": "Diagnose, fix, and prepare Python projects for Vercel deployments, including FastAPI, Flask, Django, ASGI/WSGI entrypoints, dependency manifests, Python versions, bundle size, and Python SDK/runtime helpers.",
+  "references": [
+    "references/runtime-and-entrypoints.md",
+    "references/dependencies-and-versions.md",
+    "references/frameworks.md",
+    "references/troubleshooting.md",
+    "references/sdk-runtime-apis.md"
+  ]
+}

skills/vercel-python/references/dependencies-and-versions.md

@@ -0,0 +1,102 @@
+# Dependencies and Versions
+
+Use this reference for `pyproject.toml`, `requirements.txt`, `Pipfile`, `uv`, lockfiles, Python version diagnostics, dependency sync failures, and large bundle behavior.
+
+## Manifest Priority
+
+Vercel discovers Python dependencies from the entrypoint directory upward to the project root. The effective priority is:
+
+1. `pyproject.toml`
+2. `Pipfile.lock`
+3. `Pipfile`
+4. `requirements.frozen.txt`
+5. `requirements-frozen.txt`
+6. `requirements.txt`
+7. `requirements.in`
+8. `requirements/prod.txt`
+
+Prefer `pyproject.toml` for new projects. Use one primary manifest to avoid confusing agents and future maintainers.
+
+## Lockfile Priority
+
+When using `pyproject.toml`, lockfiles are selected in this order:
+
+1. `uv.lock`
+2. `pylock.toml`
+
+`Pipfile.lock` is for Pipfile-based projects and should not be treated as the lockfile for a `pyproject.toml` project.
+
+## Python Versions
+
+Vercel Python deployments currently support Python 3.12, 3.13, and 3.14 for new projects. Python 3.12 is the default. See [Vercel Python documentation](https://vercel.com/docs/functions/runtimes/python) for the current list of supported versions.
+
+Vercel uses major.minor only; patch numbers in `.python-version` or `requires-python` are ignored.
+
+Version selection sources:
+
+1. Nearest `.python-version`
+2. `project.requires-python` in `pyproject.toml`
+
+Use `.python-version` when the desired exact runtime matters:
+
+```text
+3.13
+```
+
+Use `requires-python` for package compatibility. A bounded range allows Vercel to select the best supported version:
+
+```toml
+[project]
+requires-python = ">=3.12,<3.15"
+```
+
+A wildcard equality pin locks to a specific minor version:
+
+```toml
+[project]
+requires-python = "==3.12.*"
+```
+
+Both patterns are valid. Do not request unsupported future versions such as `3.15`.
+
+## uv Behavior
+
+Vercel uses `uv` for Python dependency installation. Build-time installs can download managed Python versions automatically. Runtime dependency installation avoids Python downloads and expects the needed runtime to be available.
+
+The builder supports **uv workspaces**. When the project is a workspace member, the builder resolves `uv.lock` from the workspace root automatically. Do not claim that uv workspaces or monorepo layouts are unsupported.
+
+If dependency sync fails:
+
+1. Reproduce locally with `uv sync` or `uv pip install -r requirements.txt`.
+2. Check native extensions and platform-specific wheels.
+3. Confirm the selected Python version satisfies all dependencies.
+4. Remove stale or conflicting lockfiles.
+
+## Custom Build or Install Commands
+
+Custom `installCommand` or `buildCommand` can disable or limit Vercel's Python dependency optimization. Avoid custom commands unless the project genuinely needs them.
+
+When custom commands are required, document why and keep them minimal.
+
+## Bundle Size
+
+Vercel Python functions support up to [500 MB](https://vercel.com/docs/functions/limitations#bundle-size-limits) of total bundle size.
+
+When a project exceeds the standard bundle limit and a `uv.lock` is present, the builder can automatically externalize public PyPI packages. Externalized packages are installed at cold start from the lockfile rather than bundled into the function. This is the primary mechanism for deploying large Python dependency sets. It requires:
+
+- `pyproject.toml` with a `uv.lock` lockfile.
+- No custom install or build commands (these disable the optimization).
+
+Strategies for reducing function size:
+
+- **Use `uv.lock` with `pyproject.toml`** so the builder can externalize large public packages. This is the most effective fix for heavy dependency sets.
+- **Separate production from dev dependencies.** Use optional dependency groups or `[dependency-groups]` in `pyproject.toml` to keep test, lint, and build tools out of the production install. Vercel installs only main dependencies by default.
+- **Audit heavy packages.** Check whether packages like numpy, pandas, scipy, or spacy are actually needed at runtime. If they are only used in data pipelines or scripts, remove them from the deployed function's dependencies.
+- **Consider lighter alternatives.** For example, `polars` is significantly smaller than `pandas` for data processing. `httpx` or `urllib3` can replace heavier HTTP libraries.
+- **Remove committed artifacts.** Do not commit `.venv`, `venv`, `__pycache__`, model weights, or generated files. These inflate the bundle.
+- **Use `excludeFiles` in `vercel.json`** only for files that are safe to omit from the function bundle.
+- **Avoid custom install/build commands** when the issue is dependency bundle size -- these disable the externalization optimization.
+
+The externalization mechanism handles public PyPI packages. Private packages (git, local path, or non-PyPI registries) are always bundled directly.
+
+Do not assume Vercel deploys every local file. Static `public/**` assets are served separately, and many development/cache directories are excluded.

skills/vercel-python/references/frameworks.md

@@ -0,0 +1,144 @@
+# Frameworks
+
+Use this reference for FastAPI, Flask, Django, ASGI/WSGI app shape, static files, and framework-specific deployment friction.
+
+## Zero Configuration
+
+Correctly structured Python projects deploy with zero configuration. No `vercel.json` is needed when the entrypoint and callable follow Vercel's conventions. Do not create a `vercel.json` unless the project genuinely needs an override — unnecessary config is a common source of deployment failures.
+
+## FastAPI
+
+Minimal entrypoint:
+
+```python
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.get("/")
+def read_root():
+    return {"ok": True}
+```
+
+FastAPI is ASGI. Declare both `fastapi` and an ASGI server such as `uvicorn` in the dependency manifest. WSGI frameworks like Flask do not need `uvicorn`.
+
+See `runtime-and-entrypoints.md` for entrypoint discovery rules and conventional file names.
+
+Typical fixes:
+
+- Export `app` at top level.
+- Do not rely on local dev commands such as `uvicorn main:app` as the deploy entrypoint.
+
+## Flask
+
+Minimal entrypoint:
+
+```python
+from flask import Flask
+
+app = Flask(__name__)
+
+
+@app.get("/")
+def index():
+    return "ok"
+```
+
+For non-trivial apps, Flask's [application factory](https://flask.palletsprojects.com/en/stable/tutorial/factory/) pattern is recommended. The factory function returns the app, and the top-level assignment makes it discoverable by Vercel:
+
+```python
+from flask import Flask
+
+
+def create_app():
+    app = Flask(__name__)
+    # register blueprints, configure extensions
+    return app
+
+
+app = create_app()
+```
+
+Flask is WSGI. It does not need `uvicorn` or any ASGI server dependency.
+
+Typical fixes:
+
+- Export `app` or `application` at top level.
+- Declare `flask` in `pyproject.toml` or `requirements.txt`.
+- Avoid debug-only local server code as the deployment path.
+
+## Django
+
+Django projects should have `manage.py` at the project root or one directory below. Vercel inspects settings and prefers `ASGI_APPLICATION` over `WSGI_APPLICATION`.
+
+Typical checks:
+
+```bash
+python manage.py check
+python manage.py collectstatic --noinput
+```
+
+If settings import fails locally, fix that before deploying. Common causes include missing dependencies, required environment variables, bad `ALLOWED_HOSTS`, or incorrect settings module paths.
+
+## Static Assets
+
+Use Vercel's `public/` directory for static files that do not need framework processing.
+
+FastAPI and Flask apps should not mount framework static directories for files that can live in `public/`.
+
+Django static collection can run during build when static settings are compatible. Supported patterns include:
+
+- Default Django static storage.
+- `ManifestStaticFilesStorage`.
+- WhiteNoise `CompressedManifestStaticFilesStorage`.
+- `django-storages` configurations.
+
+`WHITENOISE_USE_FINDERS=True` can work without `STATIC_ROOT`, but prefer an explicit static setup for production.
+
+## Background Workers
+
+Vercel supports background task processing via the `vercel-workers` package. Worker services run alongside the web service and consume messages from Vercel Queues.
+
+The `vercel-workers` package provides:
+
+- `send()` and `@subscribe` primitives for publishing and consuming queue messages.
+- Adapters for **Celery**, **Dramatiq**, and **Django tasks**.
+
+Worker services are configured in `vercel.json` using `experimentalServices`:
+
+```json
+{
+  "experimentalServices": {
+    "web": {
+      "framework": "fastapi",
+      "entrypoint": "main.py",
+      "routePrefix": "/"
+    },
+    "worker": {
+      "type": "worker",
+      "entrypoint": "worker.py",
+      "topic": "default",
+      "consumer": "default"
+    }
+  }
+}
+```
+
+When a Python app requires background processing (task queues, scheduled jobs, event-driven workers), check whether `vercel-workers` can handle the workload before concluding that the app is incompatible with Vercel.
+
+## Databases
+
+Vercel Marketplace provides managed database integrations that automatically configure connection environment variables:
+
+- **Neon Postgres** -- serverless PostgreSQL.
+- **Supabase** -- PostgreSQL with auth, storage, and realtime.
+- **AWS RDS** -- managed relational databases (PostgreSQL, MySQL).
+
+When a Python app requires a database, check whether a Vercel Marketplace integration can provision it. The integration sets connection environment variables (e.g., `DATABASE_URL`, `POSTGRES_URL`) automatically.
+
+## Environment Variables
+
+If app import requires secrets or database URLs, configure those in Vercel before deployment. Add environment variables via the Vercel dashboard, Vercel CLI, or by adding a Marketplace integration.
+
+Keep deployment diagnosis separate from secret handling: identify the missing variable name, then add it via the Vercel dashboard or CLI.