Skip to content
Get packs

Guide · Agent skill

How to use the Hugging Face API Tool Builder agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The Hugging Face API Tool Builder is an agent skill that tells an AI agent to write small, reusable command-line scripts for fetching, enriching or processing data from the Hugging Face Hub. This guide explains what the skill does, how to install it, how to trigger it with plain requests, and what to check before running the scripts it produces. By the end you will be able to get a reusable script that returns Hub model metadata as JSON.

Hugging Face API Tool Builderhuggingface/skills · Apache-2.0

Quick start

  1. 1Download and unzip. Download the skill ZIP from this page and unzip it so that SKILL.md and the references/ folder sit in one huggingface-tool-builder folder.
  2. 2Place the folder. Move the folder to ~/.claude/skills/ for personal use or to .claude/skills/ inside a project. Alternatively, upload it in the Claude apps under Settings → Capabilities → Skills.
  3. 3Install the requirements. Make sure bash, curl and jq are available. Add Python 3 and the hf command line tool if you plan to use those examples.
  4. 4Optionally set HF_TOKEN. Export your Hugging Face access token as HF_TOKEN to get higher rate limits and access to gated or private content.
  5. 5Describe the repeatable task. Ask the agent in plain language for a reusable script, naming the data you want and the output format.
  6. 6Review and test the script. Read the script, run its --help option, and test it on a small number of results before you automate it.

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

An agent skill is a folder of instructions and supporting files that an AI agent loads when a task matches the skill's description. This skill is triggered when you want to build a tool or script, or when a task would benefit from Hugging Face API data, especially if the task is repeated or automated or chains several API calls together.

When active, the agent writes command-line scripts that call the Hugging Face API directly or through the hf command line tool. The skill's examples show it chaining steps, such as listing trending models and then looking up each model's metadata, model card, or linked papers.

  • Models, datasets, papers and model cards on the Hub can be queried.
  • Output is designed for piping, typically raw or NDJSON JSON that tools like jq can filter.
  • The skill's rules ask the agent to add a --help option to scripts and to test non-destructive scripts before handing them over.

Install the skill from a ZIP file

Download the ZIP for this skill from this page and unzip it. The skill folder must contain SKILL.md along with the references/ folder.

For a personal install, place the folder in ~/.claude/skills/. For a single project, place it in the project's .claude/skills/ folder. Claude will then discover the skill in that location.

If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.

  • Personal install: ~/.claude/skills/huggingface-tool-builder/
  • Project install: .claude/skills/huggingface-tool-builder/ inside your project
  • Claude apps: Settings → Capabilities → Skills → upload

Set up what the skill needs

The skill relies on standard tools. The source lists bash, curl and jq as requirements, Python 3 for the Python example, and the hf command line tool for the model-card example. It also needs network access, and it runs scripts.

A Hugging Face access token is optional. If you set HF_TOKEN, the scripts send it as an Authorization header, which the skill says gives higher rate limits and access to gated or private content. Without it, public data should still be reachable, but limits may be lower.

  • Required: bash, curl, jq
  • Required for the Python example: Python 3
  • Required for the card-download example: the hf command line tool, which replaces the deprecated huggingface-cli
  • Optional: HF_TOKEN environment variable
export HF_TOKEN=your_token_here

Trigger the skill with a natural request

You do not need special syntax. Describe a repeatable data task and say you want a script or tool. The skill's description points to requests that involve reusable scripts, chained API calls, or automation.

Be specific about the output you want, such as fields, sorting, or how many results. The skill asks the agent to confirm your preferences when a question is unclear.

  • Write a reusable script that lists the 25 trending Hugging Face models with their license, downloads and tags as JSON.
  • Make a script that finds Hugging Face models linked to a given arXiv paper ID.
  • Build a tool that downloads model cards and outputs one line per model with license, pipeline tag and whether a gated prompt is set.

Understand the example scripts

The skill ships with example scripts in its references/ folder that the agent can follow and reuse. The source describes them as follows.

baseline_hf_api.sh and baseline_hf_api.py are minimal examples that print raw JSON using the HF_TOKEN header. find_models_by_paper.sh searches for models by arXiv paper, with an optional --token flag and a retry path for narrow searches. hf_enrich_models.sh reads model IDs from stdin and emits one JSON object per line. hf_model_card_frontmatter.sh uses the hf CLI to download model cards and output license, pipeline tag, tags and a gated prompt flag. hf_model_papers_auth.sh chains trending models, metadata and model card parsing with fallbacks.

baseline_hf_api.sh 25 | jq -r '.[].id' | references/hf_enrich_models.sh | jq -s 'sort_by(.downloads) | reverse | .[:10]'

Review the scripts before running them

The agent writes and executes code, and the scripts make network requests. Read a script before running it, especially if it will run on a machine with sensitive files or if your HF_TOKEN has access to private content. Use each script's --help option to see its inputs and outputs first.

Scripts that the skill creates are meant to be tested by the agent before handover, but you should still check any script that is non-destructive or that you plan to automate.

  • Confirm what the script sends to huggingface.co and which token it uses.
  • Do not run agent-generated scripts on sensitive machines without reviewing them.
  • Keep tokens out of shared scripts and logs.

What people use it for

  • Listing trending models and sorting them by downloads with jq.
  • Exporting model licenses, tags and pipeline tags as filterable JSON for analysis.
  • Finding models that reference a specific arXiv paper.
  • Checking which models in a list have a gated prompt before a pipeline uses them.
  • Building a scheduled script that refreshes model metadata for a team.

Frequently asked questions

How do I install the Hugging Face API Tool Builder skill?

Download the skill ZIP from this page and unzip it. Place the huggingface-tool-builder folder in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder, or upload it in the Claude apps under Settings → Capabilities → Skills.

What do I need to run the scripts?

The source lists bash, curl and jq as required, plus Python 3 for the Python example and the hf command line tool for the model card example. A Hugging Face access token in HF_TOKEN is optional but recommended for higher rate limits and gated or private content.

Is the Hugging Face API Tool Builder skill free?

The skill is published under the Apache-2.0 licence. The source does not state any pricing, so check the licence text for the terms that apply to reuse and redistribution.

Do I need a Hugging Face token?

No, the token is optional. The skill says HF_TOKEN gives higher rate limits and access to gated or private content, so add it if you hit limits or need restricted data.

Is this skill safe to run?

The skill runs scripts and uses the network, and the agent writes and executes code. Review each script and use its --help option before running it, and avoid running agent-generated scripts on sensitive machines without checking them first.

When should I use this skill instead of asking a one-off question?

Use it when you need a repeatable script or pipeline. If you only want a single answer about a model and do not need code you can rerun, a direct question is simpler.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits developers, data analysts and researchers who repeatedly need Hugging Face Hub data in scripts or pipelines, and who will review the code the agent produces. If you only want a one-off answer about a model, or you cannot run agent-generated code on the machine you are using, choose a simpler approach.

Download the skill