Skip to content
Get packs

Guide · Agent skill

How to use the Modal Cloud Python Runner agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The modal agent skill is a set of instructions and reference files that teaches an AI agent how to package Python code for Modal, a serverless cloud platform that runs code on demand and can attach GPUs. This guide explains what the skill does, how to install it, how to ask for work with plain requests, and what you need in place first. By the end you will know how to get a Modal app written, run or deployed on your own Modal account.

Modal Cloud Python RunnerK-Dense-AI/scientific-agent-skills · MIT

Quick start

  1. 1Download and unzip the skill. Download the ZIP from this page and unzip it so the folder contains SKILL.md and references/.
  2. 2Place it in a skills folder. Move the folder into ~/.claude/skills/ for personal use, or into your project's .claude/skills/, or upload it under Settings → Capabilities → Skills in the Claude apps.
  3. 3Install the pinned Modal SDK. Run uv pip install "modal==1.6.0" in a Python 3.10 to 3.14 environment.
  4. 4Authenticate. Reuse an existing Modal profile or token pair, or run modal setup to log in through your browser. Create credentials at modal.com/settings if you have none.
  5. 5Ask for a task in plain language. Describe the workload, such as serving a model on an L40S GPU or scheduling a job, and mention Modal.
  6. 6Run or deploy. Let the agent run the app with modal run or deploy it with modal deploy, after confirming the cost and account settings.

What is an agent skill and what does the modal skill do?

An agent skill is a folder containing a SKILL.md file and optional reference files. When the skill is installed, an agent such as Claude can read it and follow its guidance for matching tasks. The modal skill covers Modal's Python SDK: it knows how to write a Modal App, define a container image, set GPU options, and run or deploy the result on your Modal account.

The skill's source lists the capabilities it covers: GPU compute on demand (including H100, H200, B200 and B300), serverless functions that autoscale, custom container images defined in Python, Volumes for persistent storage, web endpoints, and scheduled jobs via cron or fixed intervals.

Install the modal skill from the ZIP download

Download the modal skill as a ZIP file from this page and unzip it. The folder should contain SKILL.md and a references folder. Then place it in one of these locations:

For a personal skill available across your projects, put the unzipped folder inside ~/.claude/skills/.

For a skill limited to one project, put it inside that project's .claude/skills/ folder.

Alternatively, in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.

  • Personal: ~/.claude/skills/modal
  • Project: .claude/skills/modal inside your project folder
  • Claude apps: Settings → Capabilities → Skills

Set up Python and the Modal SDK

The skill is written against Python 3.10 to 3.14 and modal 1.6.0. The skill's install instruction uses uv to install the pinned SDK version. You can ask the agent to run this step for you, or run it yourself in your project environment.

  • Requires Python 3.10-3.14
  • Install the SDK pinned by the skill: modal 1.6.0
uv pip install "modal==1.6.0"

Authenticate with Modal

You need a Modal account. The skill tells the agent to reuse an existing Modal profile or token pair before creating new credentials. If there is no usable profile, the agent can run modal setup, which opens a browser for authentication. For CI/CD or headless environments, set the two Modal token variables instead. You can create credentials at https://modal.com/settings.

Only MODAL_TOKEN_ID and MODAL_TOKEN_SECRET are relevant to this skill. The skill is written so the agent does not read other environment variables or .env contents.

  • Option 1: an existing Modal profile (the SDK supports profiles in .modal.toml)
  • Option 2: environment variables MODAL_TOKEN_ID and MODAL_TOKEN_SECRET
  • Option 3: run modal setup for interactive browser login
export MODAL_TOKEN_ID=<your-token-id> export MODAL_TOKEN_SECRET=<your-token-secret>

How do you trigger the skill with natural requests?

You do not need special syntax. Describe the task in plain language and mention Modal or the kind of work. The skill's description covers deploying or serving AI/ML models, GPU workloads such as training, fine-tuning and inference, web endpoints, batch jobs, and scaling Python code to cloud containers.

Good requests name the goal, the hardware, and whether you want a one-off run or a deployment.

  • Deploy a model-serving endpoint on Modal with an L40S GPU.
  • Run this batch inference script in parallel on Modal and collect the results.
  • Schedule this data pipeline to run every hour on Modal.
  • Write a Modal web endpoint that wraps my Python function.

What does a Modal app look like?

A Modal App groups functions. Functions decorated with @app.function() run remotely when you call .remote(). The agent writes code like the example below and runs it with modal run, or deploys it with modal deploy.

  • modal run script.py runs the app
  • modal deploy script.py deploys it
import modal app = modal.App("my-app") @app.function() def square(x): return x ** 2 @app.local_entrypoint() def main(): # .remote() runs in the cloud print(square.remote(42))

Choose GPUs, images and storage

Container images are defined in Python, and the recommended installer is uv. GPUs are requested with a string in the gpu parameter, such as gpu="H100" or gpu="H100:4". The skill lists available GPU strings including T4, L4, A10, L40S, A100, H100, H200, B200 and B300, and notes that L40S is recommended for inference. Volumes provide persistent storage for model weights and datasets.

  • GPU strings: T4, L4, A10, L40S, A100, A100-40GB, A100-80GB, RTX-PRO-6000, H100, H200, B200, B200+, B300
  • Up to 8 GPUs per container (A10: up to 4)
  • Use gpu="H100!" to prevent auto-upgrade
  • Volumes are for write-once, read-many workloads such as model weights; check modal volume ls, put and get for CLI access
image = ( modal.Image.debian_slim(python_version="3.11") .uv_pip_install("torch==2.12.0", "transformers==5.9.0", "accelerate==1.13.0") .apt_install("git") ) @app.function(image=image, gpu="L40S") def inference(prompt): from transformers import pipeline pipe = pipeline("text-generation", model="openai-community/gpt2", device=0) return pipe(prompt)

Safety notes: scripts, network and your data

This skill runs scripts and uses the network. Code it writes runs on Modal's cloud, and the code and any data you send leave your machine. Review what is stored in Volumes and what is sent to Modal before running sensitive workloads.

Cloud runs and GPU use are billed to your Modal account. The skill says to check current pricing and workspace quotas before sizing a run, and GPU use requires a payment method even when credits remain. Volume commits matter for handoffs: the skill says to close output files and call vol.commit() before signaling completion, and a consumer must reload the volume before reading new state.

  • Code and data are sent to Modal's cloud
  • Check pricing at https://modal.com/pricing and workspace quotas before large runs
  • Review Volume contents before storing sensitive data
  • Give concurrent runs distinct output paths

Tips for better results

Ask the agent to name the GPU and expected run size up front, so it sets gpu and max settings deliberately. Put workload dependencies in the container image rather than your local environment, since the skill's compatibility note says workload dependencies belong in their container Images. Model loading still takes time even with container reuse and warm pools, so plan for cold starts.

  • State the GPU and scale you want
  • Keep dependencies in the image
  • Expect model loading time on cold starts
  • Read references/gpu.md, references/scaling.md or references/web-endpoints.md when you need more detail

What people use it for

  • Deploy an AI/ML model as a serverless endpoint without managing servers.
  • Run GPU training, fine-tuning or inference jobs in parallel across containers.
  • Serve a simple web API backed by Python code.
  • Schedule recurring tasks such as data pipelines or retraining on cron or a fixed interval.
  • Store model weights or datasets in a Modal Volume for later runs.

Frequently asked questions

Is the modal agent skill free?

The skill is published under the MIT licence on the source repository. Running Modal workloads is separate: cloud runs and GPU use are billed to your Modal account, and GPU use requires a payment method. Check https://modal.com/pricing before sizing a run.

What do I need before I can use the modal skill?

You need Python 3.10 to 3.14, the modal 1.6.0 SDK, and a Modal account with authentication via a profile or the MODAL_TOKEN_ID and MODAL_TOKEN_SECRET variables. A payment method is needed for GPU use. Without a Modal account the skill cannot run remote work.

Where do I put the skill folder?

Place the unzipped modal folder in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder for one project. In the Claude apps you can instead upload it under Settings → Capabilities → Skills.

How do I authenticate Modal for the agent?

Run modal setup to log in through your browser, or set MODAL_TOKEN_ID and MODAL_TOKEN_SECRET as environment variables for CI or headless setups. You can create credentials at https://modal.com/settings. The skill is written to reuse existing credentials first.

Does the modal skill run code on my own machine?

No. The skill is built around remote cloud execution, so the code runs on Modal's cloud and any data you send leaves your machine. If you only want local execution, this skill is not the right fit.

How does Modal compare with running my own GPU server?

The source does not compare Modal with other platforms. Its stated benefit is that you do not manage servers: functions autoscale and GPUs are requested with a parameter. Weigh that against cost, data handling and your own infrastructure needs.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use the modal skill if you want an agent to write and run Python on Modal's cloud, especially for GPU model serving, batch inference or scheduled jobs, and you already have or are willing to set up a Modal account with billing. Pick something else if you only need to run code locally, cannot send your data to a third-party cloud, or do not want to pay for remote compute.

Download the skill