Hugging Face Tool Builder

1---
2name: hugging-face-tool-builder
3description: Use this skill when the user wants to build tool/scripts or achieve a task where using data from the Hugging Face API would help. This is especially useful when chaining or combining API calls or the task will be repeated/automated. This Skill creates a reusable script to fetch, enrich or process data.
4---
5 
6# Hugging Face API Tool Builder
7 
8Your purpose is now is to create reusable command line scripts and utilities for using the Hugging Face API, allowing chaining, piping and intermediate processing where helpful. You can access the API directly, as well as use the `hf` command line tool. Model and Dataset cards can be accessed from repositories directly.
9 
10## Script Rules
11 
12Make sure to follow these rules:
13 - Scripts must take a `--help` command line argument to describe their inputs and outputs
14 - Non-destructive scripts should be tested before handing over to the User
15 - Shell scripts are preferred, but use Python or TSX if complexity or user need requires it.
16 - IMPORTANT: Use the `HF_TOKEN` environment variable as an Authorization header. For example: `curl -H "Authorization: Bearer ${HF_TOKEN}" https://huggingface.co/api/`. This provides higher rate limits and appropriate authorization for data access.
17 - Investigate the shape of the API results before commiting to a final design; make use of piping and chaining where composability would be an advantage - prefer simple solutions where possible.
18 - Share usage examples once complete.
19 
20Be sure to confirm User preferences where there are questions or clarifications needed.
21 
22## Sample Scripts
23 
24Paths below are relative to this skill directory.
25 
26Reference examples:
27- `references/hf_model_papers_auth.sh` — uses `HF_TOKEN` automatically and chains trending → model metadata → model card parsing with fallbacks; it demonstrates multi-step API usage plus auth hygiene for gated/private content.
28- `references/find_models_by_paper.sh` — optional `HF_TOKEN` usage via `--token`, consistent authenticated search, and a retry path when arXiv-prefixed searches are too narrow; it shows resilient query strategy and clear user-facing help.
29- `references/hf_model_card_frontmatter.sh` — uses the `hf` CLI to download model cards, extracts YAML frontmatter, and emits NDJSON summaries (license, pipeline tag, tags, gated prompt flag) for easy filtering.
30 
31Baseline examples (ultra-simple, minimal logic, raw JSON output with `HF_TOKEN` header):
32- `references/baseline_hf_api.sh` — bash
33- `references/baseline_hf_api.py` — python
34- `references/baseline_hf_api.tsx` — typescript executable
35 
36Composable utility (stdin → NDJSON):
37- `references/hf_enrich_models.sh` — reads model IDs from stdin, fetches metadata per ID, emits one JSON object per line for streaming pipelines.
38 
39Composability through piping (shell-friendly JSON output):
40- `references/baseline_hf_api.sh 25 | jq -r '.[].id' | references/hf_enrich_models.sh | jq -s 'sort_by(.downloads) | reverse | .[:10]'`
41- `references/baseline_hf_api.sh 50 | jq '[.[] | {id, downloads}] | sort_by(.downloads) | reverse | .[:10]'`
42- `printf '%s\n' openai/gpt-oss-120b meta-llama/Meta-Llama-3.1-8B | references/hf_model_card_frontmatter.sh | jq -s 'map({id, license, has_extra_gated_prompt})'`
43 
44## High Level Endpoints
45 
46The following are the main API endpoints available at `https://huggingface.co`
47 
48```
49/api/datasets
50/api/models
51/api/spaces
52/api/collections
53/api/daily_papers
54/api/notifications
55/api/settings
56/api/whoami-v2
57/api/trending
58/oauth/userinfo
59```
60 
61## Accessing the API
62 
63The API is documented with the OpenAPI standard at `https://huggingface.co/.well-known/openapi.json`.
64 
65**IMPORTANT:** DO NOT ATTEMPT to read `https://huggingface.co/.well-known/openapi.json` directly as it is too large to process. 
66 
67**IMPORTANT** Use `jq` to query and extract relevant parts. For example, 
68 
69 Command to Get All 160 Endpoints
70 
71```bash
72curl -s "https://huggingface.co/.well-known/openapi.json" | jq '.paths | keys | sort'
73```
74 
75Model Search Endpoint Details
76 
77```bash
78curl -s "https://huggingface.co/.well-known/openapi.json" | jq '.paths["/api/models"]'
79```
80 
81You can also query endpoints to see the shape of the data. When doing so constrain results to low numbers to make them easy to process, yet representative.
82 
83## Using the HF command line tool
84 
85The `hf` command line tool gives you further access to Hugging Face repository content and infrastructure. 
86 
87```bash
88❯ hf --help
89Usage: hf [OPTIONS] COMMAND [ARGS]...
90 
91  Hugging Face Hub CLI
92 
93Options:
94  --help                Show this message and exit.
95 
96Commands:
97  auth                 Manage authentication (login, logout, etc.).
98  cache                Manage local cache directory.
99  download             Download files from the Hub.
100  endpoints            Manage Hugging Face Inference Endpoints.
101  env                  Print information about the environment.
102  jobs                 Run and manage Jobs on the Hub.
103  repo                 Manage repos on the Hub.
104  repo-files           Manage files in a repo on the Hub.
105  upload               Upload a file or a folder to the Hub.
106  upload-large-folder  Upload a large folder to the Hub.
107  version              Print information about the hf version.
108```
109 
110The `hf` CLI command has replaced the now deprecated `huggingface_hub` CLI command.
111