opencode-skills-collection 3.1.12 → 3.1.13

package/bundled-skills/huggingface-tool-builder/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: huggingface-tool-builder
+description: 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...
+risk: unknown
+source: https://github.com/huggingface/skills/tree/main/skills/huggingface-tool-builder
+source_repo: huggingface/skills
+source_type: official
+date_added: 2026-07-01
+license: Apache-2.0
+license_source: https://github.com/huggingface/skills/blob/main/LICENSE
+---
+
+# Hugging Face API Tool Builder
+## When to Use
+
+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...
+
+
+Your 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.
+
+## Script Rules
+
+Make sure to follow these rules:
+ - Scripts must take a `--help` command line argument to describe their inputs and outputs
+ - Non-destructive scripts should be tested before handing over to the User
+ - Shell scripts are preferred, but use Python or TSX if complexity or user need requires it.
+ - 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.
+ - 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.
+ - Share usage examples once complete.
+
+Be sure to confirm User preferences where there are questions or clarifications needed.
+
+## Sample Scripts
+
+Paths below are relative to this skill directory.
+
+Reference examples:
+- `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.
+- `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.
+- `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.
+
+Baseline examples (ultra-simple, minimal logic, raw JSON output with `HF_TOKEN` header):
+- `references/baseline_hf_api.sh` — bash
+- `references/baseline_hf_api.py` — python
+- `references/baseline_hf_api.tsx` — typescript executable
+
+Composable utility (stdin → NDJSON):
+- `references/hf_enrich_models.sh` — reads model IDs from stdin, fetches metadata per ID, emits one JSON object per line for streaming pipelines.
+
+Composability through piping (shell-friendly JSON output):
+- `references/baseline_hf_api.sh 25 | jq -r '.[].id' | references/hf_enrich_models.sh | jq -s 'sort_by(.downloads) | reverse | .[:10]'`
+- `references/baseline_hf_api.sh 50 | jq '[.[] | {id, downloads}] | sort_by(.downloads) | reverse | .[:10]'`
+- `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})'`
+
+## High Level Endpoints
+
+The following are the main API endpoints available at `https://huggingface.co`
+
+```
+/api/datasets
+/api/models
+/api/spaces
+/api/collections
+/api/daily_papers
+/api/notifications
+/api/settings
+/api/whoami-v2
+/api/trending
+/oauth/userinfo
+```
+
+## Accessing the API
+
+The API is documented with the OpenAPI standard at `https://huggingface.co/.well-known/openapi.json`.
+
+**IMPORTANT:** DO NOT ATTEMPT to read `https://huggingface.co/.well-known/openapi.json` directly as it is too large to process.
+
+**IMPORTANT** Use `jq` to query and extract relevant parts. For example,
+
+ Command to Get All 160 Endpoints
+
+```bash
+curl -s "https://huggingface.co/.well-known/openapi.json" | jq '.paths | keys | sort'
+```
+
+Model Search Endpoint Details
+
+```bash
+curl -s "https://huggingface.co/.well-known/openapi.json" | jq '.paths["/api/models"]'
+```
+
+You 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.
+
+## Using the HF command line tool
+
+The `hf` command line tool gives you further access to Hugging Face repository content and infrastructure.
+
+```bash
+❯ hf --help
+Usage: hf [OPTIONS] COMMAND [ARGS]...
+
+  Hugging Face Hub CLI
+
+Options:
+  --help                Show this message and exit.
+
+Commands:
+  auth                 Manage authentication (login, logout, etc.).
+  buckets              Commands to interact with buckets.
+  cache                Manage local cache directory.
+  collections          Interact with collections on the Hub.
+  datasets             Interact with datasets on the Hub.
+  discussions          Manage discussions and pull requests on the Hub.
+  download             Download files from the Hub.
+  endpoints            Manage Hugging Face Inference Endpoints.
+  env                  Print information about the environment.
+  extensions           Manage hf CLI extensions.
+  jobs                 Run and manage Jobs on the Hub.
+  models               Interact with models on the Hub.
+  papers               Interact with papers on the Hub.
+  repos                Manage repos on the Hub.
+  skills               Manage skills for AI assistants.
+  spaces               Interact with spaces on the Hub.
+  sync                 Sync files between local directory and a bucket.
+  upload               Upload a file or a folder to the Hub.
+  upload-large-folder  Upload a large folder to the Hub.
+  version              Print information about the hf version.
+  webhooks             Manage webhooks on the Hub.
+```
+
+The `hf` CLI command has replaced the now deprecated `huggingface-cli` command.
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream product or API scope.
+- Verify commands, API behavior, pricing, quotas, credentials, and deployment effects against current official documentation before making changes.
+- Do not treat generated examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.

package/bundled-skills/huggingface-tool-builder/references/baseline_hf_api.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""
+Ultra-simple Hugging Face API example (Python).
+
+Fetches a small list of models from the HF API and prints raw JSON.
+Uses HF_TOKEN for auth if the environment variable is set.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import urllib.request
+
+
+def show_help() -> None:
+    print(
+        """Ultra-simple Hugging Face API example (Python)
+
+Usage:
+  baseline_hf_api.py [limit]
+  baseline_hf_api.py --help
+
+Description:
+  Fetches a small list of models from the HF API and prints raw JSON.
+  Uses HF_TOKEN for auth if the environment variable is set.
+
+Examples:
+  baseline_hf_api.py
+  baseline_hf_api.py 5
+  HF_TOKEN=your_token baseline_hf_api.py 10
+"""
+    )
+
+
+def main() -> int:
+    if len(sys.argv) > 1 and sys.argv[1] == "--help":
+        show_help()
+        return 0
+
+    limit = sys.argv[1] if len(sys.argv) > 1 else "3"
+    if not limit.isdigit():
+        print("Error: limit must be a number", file=sys.stderr)
+        return 1
+
+    token = os.getenv("HF_TOKEN")
+    headers = {"Authorization": f"Bearer {token}"} if token else {}
+    url = f"https://huggingface.co/api/models?limit={limit}"
+
+    req = urllib.request.Request(url, headers=headers)
+    with urllib.request.urlopen(req) as resp:
+        sys.stdout.write(resp.read().decode("utf-8"))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-skills/huggingface-tool-builder/references/baseline_hf_api.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+show_help() {
+    cat << EOF
+Ultra-simple Hugging Face API example (Shell)
+
+Usage:
+  $0 [limit]
+  $0 --help
+
+Description:
+  Fetches a small list of models from the HF API and prints raw JSON.
+  Uses HF_TOKEN for auth if the environment variable is set.
+
+Examples:
+  $0
+  $0 5
+  HF_TOKEN=your_token $0 10
+EOF
+}
+
+if [[ "${1:-}" == "--help" ]]; then
+    show_help
+    exit 0
+fi
+
+LIMIT="${1:-3}"
+if ! [[ "$LIMIT" =~ ^[0-9]+$ ]]; then
+    echo "Error: limit must be a number" >&2
+    exit 1
+fi
+
+headers=()
+if [[ -n "${HF_TOKEN:-}" ]]; then
+    headers=(-H "Authorization: Bearer ${HF_TOKEN}")
+fi
+
+curl -s "${headers[@]}" "https://huggingface.co/api/models?limit=${LIMIT}"

package/bundled-skills/huggingface-tool-builder/references/baseline_hf_api.tsx

@@ -0,0 +1,57 @@
+#!/usr/bin/env tsx
+
+/**
+ * Ultra-simple Hugging Face API example (TSX).
+ *
+ * Fetches a small list of models from the HF API and prints raw JSON.
+ * Uses HF_TOKEN for auth if the environment variable is set.
+ */
+
+const showHelp = () => {
+  console.log(`Ultra-simple Hugging Face API example (TSX)
+
+Usage:
+  baseline_hf_api.tsx [limit]
+  baseline_hf_api.tsx --help
+
+Description:
+  Fetches a small list of models from the HF API and prints raw JSON.
+  Uses HF_TOKEN for auth if the environment variable is set.
+
+Examples:
+  baseline_hf_api.tsx
+  baseline_hf_api.tsx 5
+  HF_TOKEN=your_token baseline_hf_api.tsx 10
+`);
+};
+
+const arg = process.argv[2];
+if (arg === "--help") {
+  showHelp();
+  process.exit(0);
+}
+
+const limit = arg ?? "3";
+if (!/^\d+$/.test(limit)) {
+  console.error("Error: limit must be a number");
+  process.exit(1);
+}
+
+const token = process.env.HF_TOKEN;
+const headers: Record<string, string> = token
+  ? { Authorization: `Bearer ${token}` }
+  : {};
+
+const url = `https://huggingface.co/api/models?limit=${limit}`;
+
+(async () => {
+  const res = await fetch(url, { headers });
+
+  if (!res.ok) {
+    console.error(`Error: ${res.status} ${res.statusText}`);
+    process.exit(1);
+  }
+
+  const text = await res.text();
+  process.stdout.write(text);
+})();

package/bundled-skills/huggingface-tool-builder/references/find_models_by_paper.sh

@@ -0,0 +1,230 @@
+#!/bin/bash
+
+# Find models associated with papers on Hugging Face
+# Usage: ./find_models_by_paper.sh [arXiv_id|search_term]
+# Optional: Set HF_TOKEN environment variable for private/gated models
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Help function
+show_help() {
+    echo -e "${BLUE}Find models associated with papers on Hugging Face${NC}"
+    echo ""
+    echo -e "${YELLOW}Usage:${NC}"
+    echo "  $0 [OPTIONS] [search_term|arXiv_id]"
+    echo ""
+    echo -e "${YELLOW}Options:${NC}"
+    echo "  --help    Show this help message"
+    echo "  --token   Use HF_TOKEN environment variable (if set)"
+    echo ""
+    echo -e "${YELLOW}Environment:${NC}"
+    echo "  HF_TOKEN  Optional: Hugging Face token for private/gated models"
+    echo ""
+    echo -e "${YELLOW}Examples:${NC}"
+    echo "  $0 1910.01108                    # Search by arXiv ID"
+    echo "  $0 distilbert                     # Search by model name"
+    echo "  $0 transformer                    # Search by keyword"
+    echo "  HF_TOKEN=your_token $0 1910.01108  # Use authentication"
+    echo ""
+    echo -e "${YELLOW}Description:${NC}"
+    echo "This script finds Hugging Face models that are associated with research papers."
+    echo "It searches for models that have arXiv IDs in their tags or mentions papers in their metadata."
+    echo ""
+    echo -e "${YELLOW}Notes:${NC}"
+    echo "• HF_TOKEN is optional for public models"
+    echo "• Use HF_TOKEN for private repositories or gated models"
+    echo "• HF_TOKEN enables higher rate limits for heavy usage"
+}
+
+# Parse arguments
+USE_TOKEN=false
+POSITIONAL_ARGS=()
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --help)
+            show_help
+            exit 0
+            ;;
+        --token)
+            USE_TOKEN=true
+            shift
+            ;;
+        -*)
+            echo -e "${RED}Unknown option: $1${NC}"
+            show_help
+            exit 1
+            ;;
+        *)
+            POSITIONAL_ARGS+=("$1")
+            shift
+            ;;
+    esac
+done
+
+set -- "${POSITIONAL_ARGS[@]}"
+
+if [[ $# -eq 0 ]]; then
+    echo -e "${RED}Error: Please provide a search term or arXiv ID${NC}"
+    echo -e "Use ${YELLOW}$0 --help${NC} for usage information"
+    exit 1
+fi
+
+SEARCH_TERM="$1"
+
+# Set up authentication header if HF_TOKEN is available
+if [[ -n "$HF_TOKEN" ]] && [[ "$USE_TOKEN" == true || -n "$HF_TOKEN" ]]; then
+    AUTH_HEADER="-H \"Authorization: Bearer $HF_TOKEN\""
+    echo -e "${BLUE}Using HF_TOKEN for authentication${NC}"
+else
+    AUTH_HEADER=""
+    if [[ -n "$HF_TOKEN" ]]; then
+        echo -e "${YELLOW}HF_TOKEN found but not using it (add --token flag to use)${NC}"
+    fi
+fi
+
+# Check if the input looks like an arXiv ID (format: YYYY.NNNNN or YYYY.NNNNNNN)
+if [[ "$SEARCH_TERM" =~ ^[0-9]{4}\.[0-9]{4,7}$ ]]; then
+    echo -e "${BLUE}Searching for models associated with arXiv paper: $SEARCH_TERM${NC}"
+    SEARCH_QUERY="arxiv%3A$SEARCH_TERM"
+    IS_ARXIV_SEARCH=true
+else
+    echo -e "${BLUE}Searching for models related to: $SEARCH_TERM${NC}"
+    SEARCH_QUERY="$SEARCH_TERM"
+    IS_ARXIV_SEARCH=false
+fi
+
+# Function to extract arXiv IDs from tags
+extract_arxiv_ids() {
+    local tags="$1"
+    echo "$tags" | jq -r '.[] | select(. | startswith("arxiv:")) | split(":")[1]' 2>/dev/null || true
+}
+
+# Function to get paper title from arXiv ID
+get_paper_title() {
+    local arxiv_id="$1"
+    # Try to get paper title from Hugging Face tags if available
+    # This is a simplified approach - in practice, you might want to call arXiv API
+    echo "Paper Title (arXiv:$arxiv_id)"
+}
+
+# Search for models
+API_URL="https://huggingface.co/api/models"
+echo -e "${YELLOW}Searching Hugging Face API...${NC}"
+
+# Build curl command with authentication if available
+CURL_CMD="curl -s $AUTH_HEADER \"$API_URL?search=$SEARCH_QUERY&limit=50\""
+echo -e "${BLUE}API Query: $API_URL?search=$SEARCH_QUERY&limit=50${NC}"
+
+# Execute the API call
+if [[ -n "$HF_TOKEN" ]]; then
+    RESPONSE=$(curl -s -H "Authorization: Bearer $HF_TOKEN" "$API_URL?search=$SEARCH_QUERY&limit=50" || true)
+else
+    RESPONSE=$(curl -s "$API_URL?search=$SEARCH_QUERY&limit=50" || true)
+fi
+
+# Check if we got a valid response
+if [[ -z "$RESPONSE" ]] || [[ "$RESPONSE" == "[]" ]]; then
+    echo -e "${RED}No models found for search term: $SEARCH_TERM${NC}"
+
+    # If arXiv search failed, try without arxiv: prefix
+    if [[ "$IS_ARXIV_SEARCH" == true ]]; then
+        echo -e "${YELLOW}Trying broader search without arxiv: prefix...${NC}"
+        SEARCH_QUERY="$SEARCH_TERM"
+        IS_ARXIV_SEARCH=false
+
+        if [[ -n "$HF_TOKEN" ]]; then
+            RESPONSE=$(curl -s -H "Authorization: Bearer $HF_TOKEN" "$API_URL?search=$SEARCH_QUERY&limit=50" || true)
+        else
+            RESPONSE=$(curl -s "$API_URL?search=$SEARCH_QUERY&limit=50" || true)
+        fi
+
+        if [[ -z "$RESPONSE" ]] || [[ "$RESPONSE" == "[]" ]]; then
+            echo -e "${RED}Still no results found. Try a different search term.${NC}"
+            exit 1
+        fi
+    else
+        exit 1
+    fi
+fi
+
+# Process the results
+echo -e "${GREEN}Found models! Processing results...${NC}"
+
+# Use jq to process the JSON response and find models with paper associations
+MODELS_WITH_PAPERS=$(echo "$RESPONSE" | jq -r '
+  .[] |
+  select(.id != null) |
+  {
+    id: .id,
+    arxiv_tags: [.tags[] | select(. | startswith("arxiv:"))] | join("; "),
+    downloads: (.downloads // 0),
+    likes: (.likes // 0),
+    task: (.pipeline_tag // "unknown"),
+    library: (.library_name // "unknown")
+  }
+  | @base64' 2>/dev/null || true)
+
+# Count total results
+TOTAL_MODELS=$(echo "$RESPONSE" | jq 'length' 2>/dev/null || echo "0")
+MODELS_WITH_PAPERS_COUNT=$(echo "$MODELS_WITH_PAPERS" | wc -l)
+
+echo -e "${BLUE}Results Summary:${NC}"
+echo -e "  Total models found: $TOTAL_MODELS"
+echo -e "  Models with paper associations: $MODELS_WITH_PAPERS_COUNT"
+echo ""
+
+if [[ -z "$MODELS_WITH_PAPERS" ]]; then
+    # Show all models even if no paper associations found
+    echo -e "${YELLOW}No explicit paper associations found. Showing all matching models:${NC}"
+    echo "$RESPONSE" | jq -r '
+      .[] |
+      select(.id != null) |
+      "📦 \(.id)
+   Task: \(.pipeline_tag // "unknown")
+   Downloads: \(.downloads // 0)
+   Likes: \(.likes // 0)
+   Library: \(.library_name // "unknown")
+   ---"
+    ' 2>/dev/null || echo "Failed to parse response"
+else
+    # Show models with paper associations
+    echo -e "${GREEN}Models with paper associations:${NC}"
+    echo "$MODELS_WITH_PAPERS" | while read -r model_data; do
+        if [[ -n "$model_data" ]]; then
+            # Decode base64 and show formatted
+            echo "$model_data" | base64 -d | jq -r '
+                "📄 \(.id)
+   arXiv: \(.arxiv_tags)
+   Task: \(.task)
+   Downloads: \(.downloads)
+   Likes: \(.likes)
+   Library: \(.library)
+   ---"
+            ' 2>/dev/null || echo "Failed to parse model data"
+        fi
+    done
+fi
+
+# Additional search tips
+echo ""
+echo -e "${BLUE}Search Tips:${NC}"
+echo "• Try searching with the full arXiv ID (e.g., 1910.01108)"
+echo "• Try searching with the paper title keywords"
+echo "• Try searching with the model name"
+echo "• Use HF_TOKEN for private models or higher rate limits"
+echo ""
+echo -e "${BLUE}Examples to try:${NC}"
+echo "  $0 1910.01108                    # DistilBERT paper"
+echo "  $0 1810.04805                    # BERT paper"
+echo "  $0 1706.03762                    # Attention is All You Need paper"
+echo "  $0 roberta                       # RoBERTa models"
+echo "  $0 transformer                   # Transformer models"
+echo "  HF_TOKEN=your_token $0 1910.01108  # Use authentication"

package/bundled-skills/huggingface-tool-builder/references/hf_enrich_models.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+show_help() {
+    cat << 'USAGE'
+Stream model IDs on stdin, emit one JSON object per line (NDJSON).
+
+Usage:
+  hf_enrich_models.sh [MODEL_ID ...]
+  cat ids.txt | hf_enrich_models.sh
+  baseline_hf_api.sh 50 | jq -r '.[].id' | hf_enrich_models.sh
+
+Description:
+  Reads newline-separated model IDs and fetches basic metadata for each.
+  Outputs NDJSON with id, downloads, likes, pipeline_tag, tags.
+  Uses HF_TOKEN for auth if the environment variable is set.
+
+Examples:
+  hf_enrich_models.sh gpt2 distilbert-base-uncased
+  baseline_hf_api.sh 50 | jq -r '.[].id' | hf_enrich_models.sh | jq -s 'sort_by(.downloads)'
+  HF_TOKEN=your_token hf_enrich_models.sh microsoft/DialoGPT-medium
+USAGE
+}
+
+if [[ "${1:-}" == "--help" ]]; then
+    show_help
+    exit 0
+fi
+
+if ! command -v jq >/dev/null 2>&1; then
+    echo "Error: jq is required but not installed" >&2
+    exit 1
+fi
+
+headers=()
+if [[ -n "${HF_TOKEN:-}" ]]; then
+    headers=(-H "Authorization: Bearer ${HF_TOKEN}")
+fi
+
+emit_error() {
+    local model_id="$1"
+    local message="$2"
+    jq -cn --arg id "$model_id" --arg error "$message" '{id: $id, error: $error}'
+}
+
+process_id() {
+    local model_id="$1"
+
+    if [[ -z "$model_id" ]]; then
+        return 0
+    fi
+
+    local url="https://huggingface.co/api/models/${model_id}"
+    local response
+    response=$(curl -s "${headers[@]}" "$url" 2>/dev/null || true)
+
+    if [[ -z "$response" ]]; then
+        emit_error "$model_id" "request_failed"
+        return 0
+    fi
+
+    if ! jq -e . >/dev/null 2>&1 <<<"$response"; then
+        emit_error "$model_id" "invalid_json"
+        return 0
+    fi
+
+    if jq -e '.error' >/dev/null 2>&1 <<<"$response"; then
+        emit_error "$model_id" "not_found"
+        return 0
+    fi
+
+    jq -c --arg id "$model_id" '{
+        id: (.id // $id),
+        downloads: (.downloads // 0),
+        likes: (.likes // 0),
+        pipeline_tag: (.pipeline_tag // "unknown"),
+        tags: (.tags // [])
+    }' <<<"$response" 2>/dev/null || emit_error "$model_id" "parse_failed"
+}
+
+if [[ $# -gt 0 ]]; then
+    for model_id in "$@"; do
+        process_id "$model_id"
+    done
+    exit 0
+fi
+
+if [[ -t 0 ]]; then
+    show_help
+    exit 1
+fi
+
+while IFS= read -r model_id; do
+    process_id "$model_id"
+done