前言¶

要把模型做成可分享的 Web Demo，常见路径是自建服务器或写一长串部署文档。Hugging Face Spaces 把每个应用做成一个 Git 仓库，用 Gradio、Docker 或 Static 直接托管；但 SDK 选型、免费账号下的 ZeroGPU 配额、硬件 flavor、hf spaces 命令与 README frontmatter 等细节分散在 Hub 文档里，Agent 很容易在「能跑」和「能长期维护」之间踩坑。

下面介绍 Hugging Face 官方仓库中的 huggingface-spaces Skill：它把创建、构建、调试与维护 Space 的流程写进 SKILL.md，供 Cursor、Claude Code、Codex、Gemini CLI 等兼容 Agent Skills 的客户端按需加载。

这是什么¶

huggingface-spaces 是 huggingface/skills 仓库里的一个工作流 Skill，遵循 Agent Skills 标准（文件夹内含 SKILL.md 及参考文档）。

官方描述概括为：在 Hugging Face Spaces 上构建、部署与维护应用，覆盖 Gradio / Docker / Static SDK、ZeroGPU 与专用 GPU、spaces Python 包与 @spaces.GPU、模型加载、排障、Buckets、Inference Providers、社区 Grant 等。当用户要在 Hub 上创建或托管应用、把代码迁到 ZeroGPU、修复无法构建或运行的 Space，或涉及 hf spaces …、Space README frontmatter 时，Skill 会指导 Agent 按步骤执行。

Skill 建议与 hf-cli 搭配：后者覆盖完整 hf 命令，可用 hf skills add hf-cli 安装；本 Skill 用 hf skills add huggingface-spaces（或等价名称）按需加装。

核心功能¶

依据官方 SKILL.md，Skill 覆盖的能力包括：

1. 环境与账号：检查 hf CLI（which hf，未安装则 pip install -U huggingface_hub）、登录（hf auth whoami / hf auth login 或带 write 权限的 token），并关注 canPay、isPro 对硬件选择的限制。
2. Space 概念：每个 Space 是一个 Git 仓库；SDK 为 Gradio（主流、支持 ZeroGPU）、Docker（任意容器、不支持 ZeroGPU）、Static（HTML 或构建时编译的前端，无需算力）。
3. 硬件层级：Static 全员免费；Gradio/Docker 默认需付费方案，免费个人账号在符合条件时可托管最多 2 个 ZeroGPU Space。ZeroGPU（zero-a10g）为按请求分配 GPU，Gradio 且 PyTorch 优先；另有 cpu-basic、按小时计费的专用 GPU（hf spaces hardware 查列表与价格）。
4. 先搜再建：hf spaces search "<model or task>" --sdk gradio --limit 10，参考已有 app.py 与 requirements.txt。
5. SDK 与硬件决策：默认公开 ML Demo 倾向 Gradio + ZeroGPU；非 PyTorch 主推理路径、浏览器侧 ML、非 Python 栈等另有对应选型说明（Skill 内链到 references/zerogpu.md、references/inference-providers.md、references/grants.md 等）。
6. 创建 Space：hf repos create <namespace>/<name> --type space --space-sdk <gradio|docker|static>，配合 --flavor、--secrets、--env、可见性；强调 README 里 hardware: 会被忽略，硬件以创建时 --flavor 或后续 hf spaces settings 为准。
7. 构建应用：README.md YAML frontmatter（title、sdk、sdk_version 等）、依赖与 Gradio/Static/Docker 约定；以及调试、维护相关指引（资料截断处仍明确 frontmatter 为必填项）。

Hub 上 Spaces 数量已达百万级量级（官方 Skill 表述为 1M+），该 Skill 面向的是在这一平台上持续迭代 Demo 的完整运维路径，而非单次「上传几个文件」。

安装与启用¶

Hugging Face Skills 支持 Claude Code、Codex、Gemini CLI、Cursor 等。仓库说明：Cursor 市场条目 intentionally 仅包含 hf-cli，其余工作流 Skill 通过 hf CLI 安装。

通用（推荐已有 hf 时）

pip install -U huggingface_hub
hf auth login
hf skills add huggingface-spaces

若尚未安装 CLI 能力包，可先：

hf skills add hf-cli

（Claude Code 用户可加 --claude --global 做用户级安装，见官方仓库 Installation 小节。）

Claude Code

1. 注册插件市场：/plugin marketplace add huggingface/skills
2. 安装 CLI Skill：/plugin install hf-cli@huggingface/skills
3. 其他 Skill：hf skills add <skill-name>（例如 huggingface-spaces）

Cursor

通过 Cursor Marketplace 的 Hugging Face 插件 或仓库内 .cursor-plugin / MCP 配置接入；额外 Skill 仍用 hf skills add huggingface-spaces。

Codex

将 skills/huggingface-spaces 复制或符号链接到 Codex 约定的 .agents/skills 路径，或由已配置 hf skills add 的客户端发现。

Gemini CLI

可安装仓库扩展：gemini extensions install https://github.com/huggingface/skills.git --consent，再按项目文档加载对应 Skill。

典型用法¶

以下命令均来自官方 Skill 正文，可按顺序理解 Agent 被引导的执行路径。

1. 确认 CLI 与身份

which hf
hf auth whoami

2. 查找同类 Demo

hf spaces search "bert classification" --sdk gradio --limit 10

3. 创建 Gradio + ZeroGPU Space（免费账号需显式指定 flavor）

hf repos create my-user/my-demo --type space --space-sdk gradio \
  --flavor zero-a10g \
  --public \
  --exist-ok

敏感配置用 --secrets HF_TOKEN=hf_...（访客不可见）；仅展示用环境变量用 --env KEY=val。

4. 查看可用硬件与价格

hf spaces hardware

5. README frontmatter 示例（Gradio）

Skill 要求仓库根目录 README.md 顶部包含 YAML，例如：

---
title: My Demo
emoji: 🚀
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 6.15.1
---

（colorFrom / colorTo 仅允许文档列出的若干色名；sdk_version 宜跟当前稳定版，以 Hub 文档为准。）

推送代码后，Space 地址为 https://huggingface.co/spaces/<namespace>/<name>。需要 GPU 推理的 Gradio 代码通常会结合 spaces 包与 @spaces.GPU 装饰器，细节见 Skill 内 ZeroGPU 参考文。

适用场景与注意¶

适合谁

• 要把 PyTorch 模型做成公开 Demo，且希望 Agent 自动处理 Hub 创建、硬件与 secrets。
• Space 构建失败、运行异常，需要按官方排障清单查日志、依赖与硬件不匹配问题。
• 免费账号下尽量用 ZeroGPU 托管 Gradio，或改用 Static / Inference Providers / 社区 Grant 等替代路径。

限制与坑

• 免费个人账号：仅 Static 不限数量；Gradio 仅能通过 ZeroGPU 且最多 2 个（需 verified email、账号满 30 天等条件，以 Hub 当前政策为准）。
• 创建时若省略 --flavor，默认 cpu-basic，但该 tier 也需付费方案；免费账号应显式 --flavor zero-a10g。
• Docker Space 不支持 ZeroGPU；非 Python 技术栈选 Docker，但要接受专用或 CPU 付费 tier。
• README 中的 hardware: 不会生效，避免与 CLI 设置混用产生误解。
• Skill 内含大量指向 references/*.md 的链接（Grant、Inference Providers、ZeroGPU 量化估算等），Agent 应在具体子任务时展开阅读，而不是只靠摘要。

更权威的 Hub 行为以 Spaces 概览文档 为准。

结尾¶

huggingface-spaces 把 Hugging Face Spaces 从「又一个托管平台」收敛成可执行的 Agent 工作流：先 hf auth 与硬件边界，再搜索、选型、hf repos create，最后补齐 README frontmatter 与运行时调试。若你已在用 hf-cli 管理 Hub，用 hf skills add huggingface-spaces 即可让 Agent 在 Demo 全生命周期里少踩文档碎片化的坑。

官方 Skill 目录：github.com/huggingface/skills/tree/main/skills/huggingface-spaces