How do I install the Hf Download skill?

Run npx skillmds@latest add wzh4464/hf-download in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Hf Download safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: executes scripts, reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Hf Download?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Hf Download free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Hf Download?

wzh4464 (@wzh4464) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Hf Download by wzh4464 — Agent Skill

Name: Hf Download
Rating: 4.2 (5 reviews)
Author: wzh4464

Hf Download

Use when downloading models from Hugging Face, especially large models (LLM, diffusion, VLM) that fail with timeouts or connection drops. Trigger on "download model", "hf download", "pull model from Hugging Face", or when hf download crashes with httpx.ReadTimeout / RemoteProtocolError.

wzh4464 Updated Sep 22, 2026

File contents

HF Robust Download

Auto-retry wrapper for hf download that handles timeouts, connection drops, and stale lock files.

Usage

Run the script directly:

~/.claude/skills/hf-download/hf-download.sh <repo_id> [local_dir] [max_retries] [-- extra_flags...]

Or invoke as a Claude skill — Claude will run the script with the right arguments.

Examples

# MLX models for oMLX
hf-download.sh mlx-community/Qwen3-32B-8bit ~/.omlx/models/Qwen3-32B-8bit

# Diffusion models
hf-download.sh stabilityai/stable-diffusion-xl-base-1.0 ~/models/sdxl

# With extra hf download flags (include/exclude, revision)
hf-download.sh bigscience/bloom ~/models/bloom 100 -- --include "*.safetensors"
hf-download.sh meta-llama/Llama-3-8B ~/models/llama 50 -- --revision main

# Background download
nohup ~/.claude/skills/hf-download/hf-download.sh black-forest-labs/FLUX.1-dev ~/models/flux > /tmp/hf-flux.log 2>&1 &

What It Handles

Problem	Solution
`httpx.ReadTimeout`	Auto-retry with resume
`httpx.RemoteProtocolError`	Auto-retry with resume
Stale `.lock` files	Cleaned before each attempt
Rate limiting (no token)	Reads `~/.cache/huggingface/token` or `HF_TOKEN` env
Slow downloads	Enables `hf_transfer` by default
xet protocol hangs	Disables xet by default
Need `--include`/`--exclude`/`--revision`	Pass extra flags after `--` separator

Prerequisites

uv tool install 'huggingface-hub' --with hf_transfer --force

Environment Variables

HF_TOKEN — access token (reads ~/.cache/huggingface/token as fallback)
HF_DOWNLOAD_RETRY_DELAY — initial seconds between retries, with exponential backoff (default: 5)
HF_HUB_ENABLE_HF_TRANSFER — parallel downloads (default: 1)
HF_HUB_DISABLE_XET — disable xet protocol (default: 1)

Network Notes

If using Clash Verge / mihomo, add Hugging Face to DIRECT rules to avoid proxy bottleneck:

# In rules override (prepend section)
- DOMAIN-SUFFIX,huggingface.co,DIRECT
- DOMAIN-SUFFIX,hf.co,DIRECT
- DOMAIN-SUFFIX,huggingface.com,DIRECT

Must use Rule mode (not Global) for rules to take effect.

---name: hf-downloaddescription: Use when downloading models from Hugging Face, especially large models (LLM, diffusion, VLM) that fail with timeouts or connection drops. Trigger on "download model", "hf download", "pull model from Hugging Face", or when hf download crashes with httpx.ReadTimeout / RemoteProtocolError.---# HF Robust DownloadAuto-retry wrapper for `hf download` that handles timeouts, connection drops, and stale lock files.## UsageRun the script directly:```bash~/.claude/skills/hf-download/hf-download.sh <repo_id> [local_dir] [max_retries] [-- extra_flags...]```Or invoke as a Claude skill — Claude will run the script with the right arguments.## Examples```bash# MLX models for oMLXhf-download.sh mlx-community/Qwen3-32B-8bit ~/.omlx/models/Qwen3-32B-8bit# Diffusion modelshf-download.sh stabilityai/stable-diffusion-xl-base-1.0 ~/models/sdxl# With extra hf download flags (include/exclude, revision)hf-download.sh bigscience/bloom ~/models/bloom 100 -- --include "*.safetensors"hf-download.sh meta-llama/Llama-3-8B ~/models/llama 50 -- --revision main# Background downloadnohup ~/.claude/skills/hf-download/hf-download.sh black-forest-labs/FLUX.1-dev ~/models/flux > /tmp/hf-flux.log 2>&1 &```## What It Handles| Problem | Solution ||---------|----------|| `httpx.ReadTimeout` | Auto-retry with resume || `httpx.RemoteProtocolError` | Auto-retry with resume || Stale `.lock` files | Cleaned before each attempt || Rate limiting (no token) | Reads `~/.cache/huggingface/token` or `HF_TOKEN` env || Slow downloads | Enables `hf_transfer` by default || xet protocol hangs | Disables xet by default || Need `--include`/`--exclude`/`--revision` | Pass extra flags after `--` separator |## Prerequisites```bashuv tool install 'huggingface-hub' --with hf_transfer --force```## Environment Variables- `HF_TOKEN` — access token (reads `~/.cache/huggingface/token` as fallback)- `HF_DOWNLOAD_RETRY_DELAY` — initial seconds between retries, with exponential backoff (default: 5)- `HF_HUB_ENABLE_HF_TRANSFER` — parallel downloads (default: 1)- `HF_HUB_DISABLE_XET` — disable xet protocol (default: 1)## Network NotesIf using Clash Verge / mihomo, add Hugging Face to DIRECT rules to avoid proxy bottleneck:```yaml# In rules override (prepend section)- DOMAIN-SUFFIX,huggingface.co,DIRECT- DOMAIN-SUFFIX,hf.co,DIRECT- DOMAIN-SUFFIX,huggingface.com,DIRECT```Must use **Rule mode** (not Global) for rules to take effect.

Frequently asked questions