前言¶

要把模型做成可分享的 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