Guide · Agent skill
How to use the Hugging Face ZeroGPU agent skill (huggingface-zerogpu)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The huggingface-zerogpu skill is a set of written rules that an AI coding agent reads before it writes or reviews code for Gradio demos running on Hugging Face Spaces with ZeroGPU hardware. ZeroGPU is a shared pool of GPUs that is attached to your process only while a function marked @spaces.GPU is running. This guide is for developers who are new to agent skills as well as to ZeroGPU; after reading it you will know how to install the skill, how to ask for help in a way that triggers it, and what the skill will and will not do for you.
Hugging Face ZeroGPUhuggingface/skills · Apache-2.0 Download the skill Quick start
- 1Download the ZIP. Download the huggingface-zerogpu skill ZIP from the skill page on this site.
- 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for all projects, or into your project's .claude/skills/ folder for one project.
- 3Or upload it in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the ZIP.
- 4Ask a ZeroGPU question. Mention ZeroGPU, @spaces.GPU or the spaces package in your request, or paste the code you are working on.
- 5Apply the rules. Review the agent's changes against the rules on module-scope loading, duration and size.
- 6Check the ZeroGPU docs for current values. Confirm the backing GPU, runtime versions and tier thresholds at the official ZeroGPU documentation, since these change over time.
What the skill makes the agent do
The skill gives the agent guidance for ML demos on ZeroGPU Spaces. It covers how to structure model loading at module scope, how to pick a sensible @spaces.GPU duration so users do not hit quota errors, which features are unsupported (such as torch.compile, where the skill points to ahead-of-time compilation (AoTI) instead), how to handle CUDA-only wheel builds with no nvcc at build or runtime, and how to keep concurrent requests safe.
The skill only changes how code is written and reviewed. It does not run anything itself, provision hardware, or change quota settings.
- Hardware sizes: large (default, half of the backing GPU, 1x quota) and xlarge (full GPU, 2x quota).
- Covers pickle-based process isolation, gr.State behaviour across the worker boundary, and dynamic duration callables.
- Scope is Gradio SDK Spaces only. Docker and Static Spaces cannot run on ZeroGPU.
Install the huggingface-zerogpu skill
Download the skill ZIP from the skill page on this site and unzip it. To make it available across all your projects, place the unzipped skill folder in ~/.claude/skills/. To limit it to one project, place it in that project's .claude/skills/ folder.
If you use the Claude apps instead of a local setup, upload the ZIP under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills
Trigger the skill with natural requests
You do not need to name the skill. The skill description tells the agent to use it whenever you mention ZeroGPU, the @spaces.GPU decorator, or the spaces Python package, or paste code containing import spaces or @spaces.GPU. It also triggers on ZeroGPU-specific errors such as PicklingError across the worker boundary, illegal duration, and flash-attn wheel-build failures.
Plain requests that should trigger it include asking the agent to review a Space's app.py for ZeroGPU problems, or to choose a duration for a generation function.
Examples of what to ask
Good prompts name the Space type, the function and the symptom. For instance: "Review my app.py, which uses @spaces.GPU and loads a text-generation pipeline at module scope, and tell me if the duration is sensible." Or: "My ZeroGPU Space fails with illegal duration when I call generate_image. Fix the decorator."
- Ask for a duration: "Set a duration for this image function that fits a 20-second run."
- Debug a build: "My requirements.txt install of flash-attn fails on ZeroGPU. Which wheel should I pin?"
- Review state: "Check whether this gr.State usage is safe when several users hit the Space at once."
What it needs before you start
The skill is guidance, but the code it helps you write runs in a specific environment. The source lists these requirements: a Python environment for a Gradio SDK Hugging Face Space, Hugging Face Spaces with ZeroGPU hardware for running the code (not needed for the skill itself), and the spaces Python package, torch and transformers as used in the examples.
The skill itself runs no scripts and uses no network access.
- Gradio SDK Space
- ZeroGPU hardware to run the code
- spaces, torch and transformers packages
Safety notes on scripts and network
The skill does not run scripts and does not use the network. Its effect is limited to the code and advice the agent produces, so you still need to review any code it writes before you deploy it.
Keep in mind the code it helps you write may download models or packages when your Space runs, which is a property of your project rather than of the skill.
- Runs scripts: no
- Uses network: no
- Review generated requirements.txt and wheel URLs yourself before deploying.
Tips for ZeroGPU code
Load models at module scope and call .to("cuda") there; the skill explains that ZeroGPU manages device migration. Do not run inference at module scope, because the real GPU is only attached inside a @spaces.GPU function. Keep per-user data out of module-level variables, and use gr.State for per-session data.
Set duration to the realistic worst case rather than leaving the 60 second default, because the platform checks requested duration against the user's remaining quota.
- Use the device idiom torch.device("cuda" if torch.cuda.is_available() else "cpu") instead of hardcoding cuda.
- Do not wrap import spaces in try/except; the package is already a no-op off ZeroGPU.
- Leave size at large unless the workload needs more memory or compute; xlarge costs 2x quota.
@spaces.GPU(duration=120)
def generate_image(prompt: str):
return pipe(prompt).images[0]What people use it for
- Reviewing a Gradio Space's app.py that uses @spaces.GPU for code problems before deployment.
- Choosing a realistic duration for an image or text generation function to avoid quota errors.
- Fixing an illegal duration or PicklingError across the worker boundary.
- Resolving a flash-attn wheel-build failure in requirements.txt by choosing a matching prebuilt wheel.
- Replacing torch.compile with ahead-of-time compilation (AoTI) in a ZeroGPU demo.
Frequently asked questions
Is the huggingface-zerogpu skill free?
The skill is published under the Apache-2.0 licence in the huggingface/skills repository. Using ZeroGPU itself depends on your Hugging Face account and tier, and the ZeroGPU docs cover the quota details.
How do I install the huggingface-zerogpu skill?
Download the ZIP from the skill page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.
What does the skill need to run?
The skill runs no scripts and uses no network. The code it helps you write needs a Gradio SDK Hugging Face Space, ZeroGPU hardware to run, and the spaces, torch and transformers packages as used in the examples.
Does this skill work with Docker or Static Spaces?
No. Docker and Static Spaces cannot be scheduled onto ZeroGPU, and the skill applies only to Gradio SDK Spaces. For general Gradio layout and component work, the skill points to a separate huggingface-gradio skill.
Why does my ZeroGPU Space show an illegal duration error?
The skill's guidance is to check the duration passed to @spaces.GPU against the allowed limits and the size setting, since the requested duration is validated before the run. Ask the agent to review the decorator, and check the ZeroGPU docs for current limits.
How does this compare with just asking an AI for ZeroGPU help?
The skill bundles specific rules and reference notes on concurrency, CUDA dependencies and quota behaviour, so the agent follows the same checked guidance each time. It does not run code, provision hardware or change quota, so you still test on a real ZeroGPU Space.
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 this skill if you are building or reviewing Gradio demos on ZeroGPU Spaces and keep hitting errors like illegal duration, PicklingError or flash-attn build failures. Pick something else if you run Docker or Static Spaces, need general Gradio component work (use the huggingface-gradio skill), or expect it to provision hardware or change quota.
Download the skill