How to use the HuggingFace Best Model Finder agent skill

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

An agent skill is a folder containing a SKILL.md file that gives an AI agent extra instructions for a particular kind of task. When a request matches the skill's description, the agent follows the skill's steps instead of guessing.

This skill covers one question: which model is best for a job. The agent fetches the list of official Hugging Face benchmarks, selects the ones that match your task, pulls the top-ranked models from each leaderboard, and looks up each model's parameter count and license. If you name your hardware, it removes models that should not fit in memory. The output is a comparison table with benchmark scores and a suggested top pick, followed by an offer to help you run that model.

Install the huggingface-best skill

Download the skill ZIP from the agent-skills directory page. Then choose one of the following options.

For Claude Code, unzip the file into ~/.claude/skills/ to make the skill available in all your projects, or into a project's .claude/skills/ folder to limit it to that project.

In the Claude apps, you can upload the ZIP under Settings, then Capabilities, then Skills instead.

• Personal install: ~/.claude/skills/ (available across projects)
• Project install: .claude/skills/ inside the project folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Set up the requirements

The skill's commands depend on two standard command-line tools, curl and jq, which must be installed in the environment where the agent runs. It also needs a Hugging Face access token saved at ~/.cache/huggingface/token, because every request to the Hugging Face API is authorized with it.

The hf-cli tool is optional. The skill uses it only as an alternative way to fetch model information.

• curl and jq installed in the agent environment
• A Hugging Face access token stored at ~/.cache/huggingface/token
• Optional: hf-cli for the alternative model info command

How to trigger the skill with natural requests

You do not need to type a command. Ask the question the way you would ask a colleague, and the agent will match it to the skill. The skill description says it should be used for any question about choosing an AI model for a specific use case, even if you do not mention Hugging Face or benchmarks.

Including your task and your device helps the agent filter results. If you do not mention a device, the agent skips size filtering and ranks models by benchmark score alone. If your task is unclear, the agent asks one clarifying question.

• best model for code review
• what model should I use for OCR on scanned invoices
• which model runs on my laptop with 16GB of memory
• compare models for speech recognition
• what's state of the art for retrieval

What the agent does step by step

First, the agent identifies your task and device. Next it lists official benchmark datasets and picks the relevant ones, using their IDs, tags and descriptions. For each chosen benchmark it reads the top 15 entries on the leaderboard.

For up to 15 candidate models, it looks up parameter counts and licenses. Using the rule of thumb that fp16 needs about 2 GB per billion parameters, it sorts models into fits in fp16, fits only with Q4 quantization, or too large. It then ranks by benchmark score and keeps the top 5 to 8 models.

The final table lists each model with a link to its Hugging Face page, parameter count, benchmark scores, license and an 'On device' value. The top pick is marked with a star.

• Budget rule: fp16 max parameters in billions is roughly memory in GB divided by 2; Q4 is roughly memory in GB multiplied by 2
• Proprietary models such as GPT-4, Claude or Gemini can appear, marked as API only, unless you asked for local or open models only
• Leaderboards that fail to load are skipped and noted in the output

Safety, privacy and offline limits

This skill runs scripts and uses the network. Every step queries huggingface.co, and the commands read your token from ~/.cache/huggingface/token and send it with each request. If you cannot share a Hugging Face token, do not use this skill.

The skill will not work offline or in an air-gapped environment, because it needs live access to Hugging Face. Its memory estimates are rough rules of thumb, and leaderboard scores may be gamed or may not match your own workload, so test candidate models before committing.

• Runs scripts: yes
• Uses network: yes
• Your token is sent with each request to huggingface.co

Tips for better model recommendations

Name the task precisely, for example 'OCR on scanned forms' rather than 'documents', because the agent matches benchmarks on dataset id, tags and description. State your exact hardware, such as '24GB VRAM' or '16GB unified memory', so the size filter has a number to work with.

Ask for open models only if you need to self-host, since the default includes API-only proprietary models. After the table, you can accept the offer to run the top pick locally or through HF Jobs.

• Be specific about the task and the hardware
• Say 'open models only' if you need to self-host
• Treat the top pick as a starting point and verify it on your own data