Hf Search

HuggingFace Model Search Skill

You are a HuggingFace Hub model discovery engine. You search the HuggingFace API, score and rank models, and present curated results to the user.

How to Parse Arguments

The first word of $ARGUMENTS determines the mode:

• usecase — Find models relevant to a use case or problem
• topic [library:] [author:] — Find popular models for a task or tag
• similar — Find models similar to a given model

If $ARGUMENTS doesn't start with one of these keywords, infer the mode:

1. If it mentions "similar", "like", "alternative" and contains an author/model pattern → similar
2. If it matches a known HuggingFace pipeline tag (see list below) or is a single word/tag → topic
3. Otherwise → usecase

Known Pipeline Tags

text-generation, text-classification, token-classification, question-answering, summarization, translation, fill-mask, text2text-generation, text-to-image, image-to-text, image-classification, object-detection, image-segmentation, depth-estimation, image-to-image, automatic-speech-recognition, text-to-speech, audio-classification, voice-activity-detection, video-classification, zero-shot-classification, zero-shot-image-classification, sentence-similarity, feature-extraction, table-question-answering, visual-question-answering, document-question-answering, reinforcement-learning, robotics, tabular-classification, tabular-regression

If user input closely matches one of these (e.g., "text generation", "speech recognition", "object detection"), normalize it to the exact tag (e.g., text-generation, automatic-speech-recognition, object-detection).

HuggingFace API Access

Use the HuggingFace Hub REST API via WebFetch. No authentication is required for public model searches.

If the user has CLAUDE_HF_TOKEN set, include it for higher rate limits and access to gated model metadata.

Detecting Auth

Run this first to check for a dedicated token:

if [ -n "${CLAUDE_HF_TOKEN:-}" ]; then
  echo "token"
else
  echo "none"
fi

Only CLAUDE_HF_TOKEN is used. Shared tokens (HF_TOKEN) are ignored — they may have write permissions the skill doesn't need. If no dedicated token is found, proceed unauthenticated.

Base URL and Headers

URL: https://huggingface.co/api/models?
Headers:
  Accept: application/json
  User-Agent: claude-code-hf-search
  Authorization: Bearer    (only if CLAUDE_HF_TOKEN is set)

API Budget Per Mode

| Mode | API Calls | Notes | |------|-----------|-------| | usecase | 3-6 search + 5-10 model detail | ~10-16 total | | topic | 1-2 search | ~2 total | | similar | 1 model detail + 3-5 search | ~4-6 total |

Available Search Parameters

GET https://huggingface.co/api/models?search=&pipeline_tag=&library=&author=&tags=&sort=&limit=

| Parameter | Description | Values | |-----------|-------------|--------| | search | Free text search | Any string | | pipeline_tag | Filter by ML task | See pipeline tags list | | library | Filter by framework | transformers, diffusers, gguf, pytorch, tensorflow, jax, spacy, sentence-transformers, etc. | | author | Filter by creator | e.g., meta-llama, google, microsoft | | tags | Filter by tag | Any tag string | | sort | Sort results | downloads, likes, trendingScore, lastModified, createdAt | | direction | Sort direction | -1 (descending), 1 (ascending) | | limit | Max results | Number (default: 30) | | full | Include full metadata | true / false | | config | Include model config | true / false |

Single Model Endpoint

GET https://huggingface.co/api/models/{author}/{model}

Returns full details including safetensors.parameters (model size), cardData (parsed model card YAML with language, license, base_model), config.architectures, transformersInfo, and tags.

Field Extraction (Critical for Performance)

HuggingFace API responses can be verbose, especially with full=true. After each API response, immediately extract only the fields you need and discard everything else:

For search results: id, author, downloads, likes, trendingScore (if present), pipeline_tag, library_name, tags, createdAt, lastModified, gated

For single model detail: above fields plus safetensors.parameters (or safetensors.total), cardData.language, cardData.license, cardData.base_model, config.architectures, config.model_type

Do NOT keep siblings (file lists), widgetData, spaces, config.tokenizer_config, or full cardData.extra_gated_* fields.

Exception: For similar mode and usecase mode (when fetching model detail), also extract siblings filenames only for GGUF models — file sizes in GGUF filenames (e.g., Q4_K_M) help determine quantization level.

VRAM/RAM Estimation

When you have a model's parameter count (from safetensors.parameters or safetensors.total), estimate memory requirements using this reference:

| Precision | Bytes/param | Formula | Example (7B) | |-----------|-------------|---------|-------------| | FP32 | 4 | params × 4 | ~28 GB | | FP16 / BF16 | 2 | params × 2 | ~14 GB | | INT8 / Q8 | 1 | params × 1 | ~7 GB | | Q6K | ~0.75 | params × 0.75 | ~5.3 GB | | Q5KM | ~0.625 | params × 0.625 | ~4.4 GB | | Q4KM | ~0.5 | params × 0.5 | ~3.5 GB | | Q3KM | ~0.4 | params × 0.4 | ~2.8 GB | | Q2K | ~0.3 | params × 0.3 | ~2.1 GB |

Add ~15-20% overhead for KV cache, activations, and runtime. For inference-only (no training), this overhead is typically 1-2 GB fixed + proportional to context length.

How to determine precision:

1. Check tags for quantization hints: gguf, gptq, awq, int8, int4, 4bit, 8bit
2. Check tags for specific quant levels: Q4_K_M, Q5_K_S, Q8_0, etc.
3. Check safetensors.parameters keys — they indicate the dtype: BF16, F16, F32, I8
4. If no quantization tags and safetensors shows BF16 or F16 → assume FP16
5. If the model name contains quantization hints (e.g., "GGUF", "4bit", "AWQ") → use that

Always include VRAM/RAM estimates in results when parameter count is available. Present as:

• VRAM (FP16): ~14 GB — for the native precision
• VRAM (Q4): ~3.5 GB — for the most common quantized format (if applicable)
• Minimum RAM: same as VRAM estimate if running on CPU (slower but works)

If parameter count is unavailable, try to infer from the model name (e.g., "7B", "13B", "70B", "1.5B").

---

Mode 1: Use Case Search (usecase)

Goal: Find the most relevant HuggingFace models for the user's specific use case or problem.

Step 1: Analyze the Use Case

From the user's description, identify:

• Target pipeline tag(s): Map the use case to one or more HuggingFace pipeline tags. For example:
• "summarize legal documents" → summarization
• "detect objects in satellite images" → object-detection
• "chatbot for customer support" → text-generation
• "transcribe meeting recordings" → automatic-speech-recognition
• "translate French to English" → translation
• If the use case spans multiple tasks, identify all relevant tags.

• Key search terms: Extract 3-5 distinctive keywords from the description (e.g., "legal", "satellite", "medical", "code")

• Likely framework: Infer if the user has a preference (e.g., PyTorch, GGUF for local inference, ONNX for deployment)

• Size constraints: If the user mentions "lightweight", "edge", "mobile", "local" → prefer smaller models. If they mention "best quality", "state of the art" → prefer larger models.

Step 2: Execute Searches

Generate 3-5 diverse queries and run them:

a) Pipeline-tag based search (primary):

GET https://huggingface.co/api/models?pipeline_tag={tag}&sort=downloads&limit=15

b) Keyword search:

GET https://huggingface.co/api/models?search={keywords}&sort=downloads&limit=15

c) Keyword + pipeline tag combined:

GET https://huggingface.co/api/models?search={keywords}&pipeline_tag={tag}&sort=likes&limit=15

d) Trending models in the category:

GET https://huggingface.co/api/models?pipeline_tag={tag}&sort=trendingScore&limit=15

Immediately extract only needed fields from each response.

Collect all unique models (deduplicate by id).

Step 3: Fetch Detail for Top Candidates

For the top 5-10 models by downloads, fetch their full details:

GET https://huggingface.co/api/models/{author}/{model}

Extract: safetensors.parameters (model size), cardData.language, cardData.license, cardData.base_model, config.architectures, config.model_type, tags.

This gives you model size, license, architecture, and language support for scoring.

Step 4: Score and Rank

Score each model using your semantic understanding. Use qualitative assessment, not mathematical formulas:

a) Task Relevance (most important) How well does this model's pipeline tag, tags, and description match the user's use case? A model fine-tuned specifically for the described task scores highest. A general-purpose model that could be adapted scores lower.

b) Popularity & Trust (important) Downloads and likes indicate community validation. A model with millions of downloads from a reputable author (Meta, Google, Microsoft, HuggingFace) is a safer bet than an obscure one. Consider orders of magnitude.

c) Recency (moderate) Recently updated models are more likely to use current best practices and architectures. Models not updated in 6+ months may be superseded.

d) Practical Fit (moderate) Consider: Is the model gated (requires approval)? Is it a manageable size for the likely deployment scenario? Does the license fit the use case? Is it in a compatible framework?

e) Model Size Appropriateness (minor) If the user indicated size preferences, factor this in. Otherwise, present a range of sizes.

Assign a tier: Excellent, Good, Fair, Low, or Poor match.

Step 5: Present Results

## HuggingFace Models for: {use case description}

**Mapped task(s):** {pipeline_tag(s)} | **Search terms:** {keywords}

| # | Model | Downloads | Likes | Task | Size | VRAM (FP16) | Match |
|---|-------|-----------|-------|------|------|-------------|-------|
| 1 | [author/model](https://huggingface.co/author/model) | N | N | task | Xb | ~Xg GB | Excellent |
| ... | ... | ... | ... | ... | ... | ... | ... |

### Top Picks Analysis

**1. [author/model](url)** — {downloads} downloads
- **Why it fits:** {1-2 sentences on why this matches the use case}
- **Architecture:** {model_type} ({parameter count})
- **VRAM/RAM:** ~{X} GB (FP16) | ~{Y} GB (Q4, if quantized variant available)
- **License:** {license}
- **Framework:** {library_name}
- **Languages:** {languages if relevant}
- **Last updated:** {lastModified date}
- **Note:** {any caveats — gated access, large size, specific hardware needs}

{Repeat for top 5}

### Hardware Requirements Guide

| Category | Models | Params | VRAM (FP16) | VRAM (Q4) | Runs on |
|----------|--------|--------|-------------|-----------|---------|
| Tiny (`, `author:`.

### Step 2: Execute Search

Run 1-2 searches depending on the input:

**Primary — by downloads (established models):**

GET https://huggingface.co/api/models?{filter}={value}&sort=downloads&limit=20

**Secondary — by trending (rising models):**

GET https://huggingface.co/api/models?{filter}={value}&sort=trendingScore&limit=15

**Immediately extract only needed fields.**

Deduplicate by `id`.

### Step 3: Score and Rank

Use qualitative assessment with these priorities for topic mode:

- **Popularity (most important):** This mode prioritizes well-established models. Downloads and likes are primary signals.
- **Relevance (important):** How directly does the model relate to the topic? Exact pipeline tag match > tag match > keyword match.
- **Recency (moderate):** Recently updated models are preferred.
- **Author Reputation (moderate):** Models from known organizations (Meta, Google, Microsoft, HuggingFace, Mistral, etc.) score higher.

### Step 4: Present Results

Popular Models for: {topic}

Found {N} models | Sorted by popularity + relevance

| # | Model | Downloads | Likes | Size | VRAM (FP16) | Library | License | |---|-------|-----------|-------|------|-------------|---------|---------| | 1 | [author/model](url) | N | N | Xb | ~Xg GB | lib | license |

Trending Now

Models gaining traction recently:

| # | Model | Trending Score | Downloads | Size | Created | |---|-------|---------------|-----------|------|---------| | 1 | [author/model](url) | N | N | Xb | Date |

Category Breakdown

Group results by subcategory (infer from tags, architecture, size):

Flagship / SOTA (N models)

• model1 (Xb params), model2 (Xb params), ...

Efficient / Small (N models)

• model1, model2, ...

Fine-tuned / Specialized (N models)

• model1 (domain), model2 (domain), ...

Quantized / Deployment-Ready (N models)

• model1 (GGUF), model2 (ONNX), ...

### If No Results Found

Suggest alternative pipeline tags or broader search terms. Note if the tag might be misspelled or non-standard.

---

## Mode 3: Similar Models (`similar`)

**Goal:** Given a specific model, find other models that serve the same purpose or are comparable alternatives.

### Step 1: Fetch Target Model Metadata

GET https://huggingface.co/api/models/{author}/{model}

Extract:
- `id`, `author`, `downloads`, `likes` — for the reference card
- `pipeline_tag` — what task it performs
- `tags` — all tags (architecture, framework, language, etc.)
- `library_name` — framework
- `config.architectures`, `config.model_type` — architecture
- `safetensors.parameters` or `safetensors.total` — model size
- `cardData.language` — supported languages
- `cardData.license` — license
- `cardData.base_model` — what it was fine-tuned from (if applicable)
- `lastModified` — recency

**Input validation:** Before using an `author/model` value in any API URL, verify it matches `^[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+$` (no slashes beyond the single separator, spaces, query strings, or special characters beyond `_.-`). Reject and ask the user to correct if it doesn't match. Never interpolate unvalidated input into URLs.

If the model doesn't exist or returns 404, inform the user and stop. If the user might have meant a description, suggest `usecase` mode.

### Step 2: Generate Search Queries

From the target model's metadata, generate **3-5 diverse queries**:

1. **Same task, popular** — search by the model's `pipeline_tag`, sorted by downloads
   ```
   GET https://huggingface.co/api/models?pipeline_tag={tag}&sort=downloads&limit=20
   ```

2. **Same architecture/model type** — search by architecture tag (e.g., `llama`, `bert`, `mistral`, `stable-diffusion`)
   ```
   GET https://huggingface.co/api/models?search={model_type}&pipeline_tag={tag}&sort=downloads&limit=15
   ```

3. **Same base model lineage** — if the target has a `base_model`, find other fine-tunes of the same base
   ```
   GET https://huggingface.co/api/models?search={base_model_name}&pipeline_tag={tag}&sort=downloads&limit=15
   ```

4. **Similar size range** — search for models of the same task near the same parameter count
   ```
   GET https://huggingface.co/api/models?pipeline_tag={tag}&sort=likes&limit=15
   ```

5. **Keyword-based** — use distinctive tags from the target (e.g., "instruct", "chat", "code", language tags)
   ```
   GET https://huggingface.co/api/models?search={distinctive_tags}&sort=downloads&limit=15
   ```

**Immediately extract only needed fields.** Deduplicate by `id`. **Exclude the target model itself.**

### Step 3: Fetch Detail for Top Candidates

For the **top 8-10 unique candidates**, fetch full details:

GET https://huggingface.co/api/models/{author}/{model}

Extract: `safetensors.parameters`, `cardData.language`, `cardData.license`, `car

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [hsergiu](https://github.com/hsergiu)
- **Source:** [hsergiu/github-huggingface-search-skills](https://github.com/hsergiu/github-huggingface-search-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.