Skip to content
Get packs

Guide · Agent skill

How to use the Hugging Face Spaces agent skill

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

The huggingface-spaces skill gives an AI agent working knowledge of Hugging Face Spaces, which are git-backed hosted projects for machine-learning demos. It is for developers who want to publish a model as a public web demo, port an existing Gradio or PyTorch app onto ZeroGPU, or fix a Space that will not build or start. After this guide you will know how to install the skill, how to ask for work in plain language, and what your account needs before the agent can create a Space.

Hugging Face Spaceshuggingface/skills · Apache-2.0

Quick start

  1. 1Install the CLI and log in. Run pip install -U huggingface_hub, then hf auth login and follow the URL and code prompt.
  2. 2Install the skill. Run hf skills add huggingface-spaces --claude --global, or download the ZIP and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder.
  3. 3Check your account. Run hf auth whoami and note canPay and isPro, since they decide which hardware you can use.
  4. 4Ask for what you want. Describe the model, the app and whether it should be public, in plain language.
  5. 5Review the create command. Check the SDK, flavor and visibility the agent proposes before it runs hf repos create.
  6. 6Iterate and debug. If the build or run fails, ask the agent to diagnose it using the skill's debugging notes.

What is an agent skill and what does this one do?

An agent skill is a folder of instructions and reference files that an AI agent loads when a task matches it. This skill, named huggingface-spaces, teaches the agent how to create, build, debug and maintain Spaces.

Once installed, the agent can choose between the Gradio, Docker and Static SDKs, pick hardware such as the free-for-visitors ZeroGPU option or paid GPUs, and use the hf command-line tool to create and configure a Space. It also looks for an existing demo to copy from before building from scratch, and it helps debug Spaces that fail to build or run.

Install the huggingface-spaces skill

Option 1: install with the hf CLI. First install the CLI, then log in, then run the skill installer. The README for this skill gives these steps.

Option 2: download the ZIP from this page and unzip it. Put the folder in ~/.claude/skills/ to make it available to all your projects, or in a project's .claude/skills/ folder to limit it to that project.

Option 3: in the Claude apps, open Settings, go to Capabilities, then Skills, and upload the skill.

  • Install the CLI: pip install -U huggingface_hub
  • Log in: hf auth login
  • Install the skill for Claude Code, user-level: hf skills add huggingface-spaces --claude --global
pip install -U huggingface_hub hf auth login hf skills add huggingface-spaces --claude --global

Check your account before you start

The skill checks your login with hf auth whoami and reads the canPay and isPro flags, because these decide which hardware you can use. A free account can host Static Spaces and up to 2 ZeroGPU Spaces. Gradio and Docker Spaces run on compute and need a paid plan to create, with one exception: the free ZeroGPU allowance.

If you log in with a browser, hf auth login prints a URL and a one-time code. Open the URL and enter the code. Alternatively, pass a write-scoped access token with --token.

  • Hugging Face account
  • hf command-line tool installed
  • Login through hf auth login (OAuth) or a write-scoped access token
  • PRO, Team or Enterprise plan for Gradio or Docker hardware beyond the free ZeroGPU allowance
hf auth whoami

How do you trigger the skill with natural requests?

You do not need special syntax. Describe the goal in plain language. The skill is meant to activate when you ask to create or host an app on Hugging Face, port code onto ZeroGPU, fix a Space that will not build or run, or work with hf spaces commands, the @spaces.GPU decorator, Space README frontmatter, or the spaces Python package.

Be specific about the model or task and the result you want. The agent will ask for missing details such as visibility and hardware when they matter.

  • "Make a public Gradio demo of this text-to-image model on Hugging Face Spaces."
  • "Port my existing Gradio app to ZeroGPU and deploy it as a Space."
  • "My Space shows a build error after I pushed it. Find out why and fix it."
  • "Search Hugging Face Spaces for a demo of image segmentation I can start from."

Choose an SDK and hardware

Gradio is the default for a public ML demo and supports ZeroGPU. Docker runs any container for non-Python stacks, but does not support ZeroGPU. Static is for plain HTML or JavaScript front ends, including in-browser ML, and needs no hardware.

ZeroGPU allocates a GPU per request and is Gradio-only and PyTorch-first. Dedicated GPUs are billed to the Space creator by the hour and need canPay=True. Run hf spaces hardware for the current list and pricing.

  • Gradio + ZeroGPU: default for public ML demos
  • Docker: non-Python stacks or prebuilt templates
  • Static: browser-side ML or project pages
  • Dedicated GPU: only when ZeroGPU genuinely does not fit

Understand the safety and network behaviour

This skill runs scripts and uses the network. The agent runs hf commands that create repos, set visibility and write secrets, and it downloads models and code. Review the commands it proposes before you approve them, especially those that change visibility or spend money.

Secrets set with --secrets are environment variables inside the Space and are not visible to visitors. Values set with --env are visible to visitors, so use them only for non-sensitive settings. The skill is built around public hosting, so choose --public, --private or --protected deliberately. Do not use it for sensitive or private production workloads without reviewing those settings.

  • --public: anyone can view the Space
  • --private: only you can view it
  • --protected: the app is reachable but the git repo and Files tab are private
  • Put API keys and tokens in --secrets, never in --env
hf repos create <namespace>/<name> --type space --space-sdk <gradio|docker|static> --flavor zero-a10g --secrets KEY=val --public --exist-ok

Debug a Space that fails to build or run

Ask the agent to check why the Space failed. The skill includes reference notes on debugging and known errors. A common trap: hardware set under hardware: in the README YAML is silently ignored. Hardware is set with --flavor at creation or later with hf spaces settings <id> --hardware <name>.

Also note that omitting --flavor gives cpu-basic, which is gated behind a paid plan, so a free account should pass --flavor zero-a10g explicitly.

  • Confirm the README frontmatter has the required fields and valid colour names
  • Check that hardware is set through the CLI, not the README
  • Look for an existing Space with a similar app and compare its app.py and requirements.txt
hf spaces settings <id> --hardware <name>

What people use it for

  • Publishing a machine-learning model as a public Gradio demo on ZeroGPU
  • Porting an existing Gradio or PyTorch app onto ZeroGPU with the @spaces.GPU decorator
  • Fixing a Space whose build fails because of README frontmatter or dependencies
  • Building a Static Space that runs a model in the browser with transformers.js
  • Searching existing Spaces for a working app to adapt before writing code

Frequently asked questions

Is the huggingface-spaces skill free?

The skill is published under the Apache-2.0 licence. Creating a Space depends on your Hugging Face account: Static Spaces are free for everyone, and ZeroGPU is available on free personal accounts in good standing up to a limit of 2 Spaces. Dedicated hardware requires a paid plan.

What do I need to use the Hugging Face Spaces skill?

You need a Hugging Face account, the hf command-line tool installed with pip install -U huggingface_hub, and a login through hf auth login or a write-scoped access token. For Gradio or Docker hardware beyond the free ZeroGPU allowance, you need a PRO, Team or Enterprise plan.

How do I install the skill in Claude?

Either run hf skills add huggingface-spaces --claude --global, or download the ZIP from this page and unzip it into ~/.claude/skills/ for all projects or a project's .claude/skills/ folder. In the Claude apps you can also upload it under Settings, Capabilities, Skills.

Can I use ZeroGPU on a free account?

Yes, within limits. Free personal accounts in good standing can host up to 2 ZeroGPU Spaces. On a free account, ZeroGPU is the only way to host a Gradio Space, so pass --flavor zero-a10g when creating it.

Why does my Space fail to build or start?

Common causes include hardware set in the README YAML (which is ignored), a missing or invalid README frontmatter field, or a Gradio or Docker setup that does not match the chosen SDK. Ask the agent to debug it, and it will use the skill's debugging and known-errors notes.

Are there alternatives if I cannot pay for a GPU?

The skill suggests checking Inference Providers, which avoids hosting the model yourself, and requesting a community grant for a Static Space that pushes your app. Dedicated GPUs need a paid plan and billing enabled on the creator's account.

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 want an agent to build, host and fix public machine-learning demos on Hugging Face Spaces, especially on ZeroGPU. Pick something else if you need a guaranteed paid GPU without any billing setup, or if you are running sensitive or private production workloads, since the skill centres on public hosting.

Download the skill