Skip to content
Get packs

Guide · Agent skill

How to use the Hugging Face Transformers agent skill

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

The Transformers skill gives an AI coding agent a working playbook for the Hugging Face Transformers library, which provides pre-trained models for language, vision, audio and multimodal tasks. This guide explains what the skill does, how to install it, how to ask for things in plain language, and what to check before running code it produces. By the end you will be able to add the skill, set up a Python environment, and get the agent to load a model, run inference, or fine-tune one on your own labelled data.

Hugging Face TransformersK-Dense-AI/scientific-agent-skills · MIT

Quick start

  1. 1Download the ZIP. Download the Transformers skill ZIP from the directory page. Keep it somewhere you can find it before you unzip it.
  2. 2Unzip into a skills folder. Unzip the skill into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project. If you use the Claude apps, upload it under Settings → Capabilities → Skills instead.
  3. 3Create a dedicated Python environment. Run the uv commands in the install section to create a separate environment with the pinned packages. Pick the Torch build that matches your hardware first.
  4. 4Authenticate if you need gated models. Run hf auth login with a token that has read scope, or set HF_TOKEN from a secret store on servers. Skip this step if you only use public models.
  5. 5Ask for the task in plain language. Describe the goal and name the Transformers concept, such as a pipeline, AutoModel or TrainingArguments. The agent uses the skill when the request matches.
  6. 6Review the code before running it. Read any downloads, file writes and remote-code loading the agent proposes. Pin revisions and confirm custom code is reviewed before you run it.

What the Transformers skill makes the agent do

An agent skill is a folder of instructions and reference files that an agent reads when a task matches it. This skill covers the parts of Transformers that Python developers use most: loading models from the Hugging Face Hub with AutoModel classes, running quick inference with pipelines, controlling text generation, tokenizing inputs, and fine-tuning with the Trainer API and TrainingArguments.

Once installed, the agent also knows how to set up a compatible environment, authenticate with Hub tokens, and handle migration notes for the v5 release. The skill's reference files cover pipelines, model loading, text generation, tokenization, training and a review of how the material was checked.

Install the Transformers skill

Download the ZIP for the skill from the directory page and unzip it. Then put the resulting folder in one of two places. For a personal setup, use ~/.claude/skills/. For a single project, use the .claude/skills/ folder inside that project. Both locations make the skill available to the agent when it works in that context.

If you use the Claude apps instead of a local setup, you can upload the skill under Settings → Capabilities → Skills.

  • Personal install: unzip into ~/.claude/skills/
  • Project install: unzip into .claude/skills/ inside your project folder
  • Claude apps: upload the skill under Settings → Capabilities → Skills

Set up a Python environment for Transformers

The skill's install guidance asks you to use a dedicated environment so the training stack stays consistent. The commands below are the ones in the skill's SKILL.md. The skill pins specific package versions, and the Torch build should match your hardware before you install it.

On Windows, the Python path inside the environment is different, so use the Scripts path instead of bin. Optional packages such as Pillow, torchvision, timm, librosa, soundfile, FFmpeg, Tesseract and bitsandbytes are only needed for the workflows that use them. The skill says librosa has its own Python requirement, so check it if you plan to work with audio preprocessing.

  • Install only the optional packages your workflow needs
  • Pick the Torch build for your hardware before installing
  • Transformers v5 is PyTorch-only, so TensorFlow and JAX setups will not work with it
uv venv --python 3.11 .venv-transformers uv pip install --python .venv-transformers/bin/python "transformers[torch]==5.18.0" "torch==2.14.1" "huggingface-hub==1.33.0" "datasets==5.0.1" "accelerate==1.15.0" "peft==0.21.2"

Authenticate with your Hugging Face token

Many Hub models are gated or private. For those, you need a Hugging Face token with read scope. The recommended way to store it is the CLI login, which saves the token to the cache location described in the skill. For servers and CI, set the HF_TOKEN environment variable from a secret manager instead.

Never paste a token into a notebook, a repository or a shared config file. Use the narrowest scope that works: read for downloads, and write only when you need to upload.

  • Recommended on a personal machine: run hf auth login
  • Servers and CI: set HF_TOKEN from a secret store
  • Do not commit tokens to git or put them in shell profiles
  • To stop the stored token being sent on every Hub request, set HF_HUB_DISABLE_IMPLICIT_TOKEN=1 and pass a token only where needed
hf auth login

Ask the agent for common tasks in plain language

You do not need special commands to trigger the skill. Describe your goal in terms the skill covers, and mention the Transformers concept you are working with, such as a pipeline, AutoModel, a tokenizer, a generation config or TrainingArguments. The skill's description says it applies when you work with those items.

The skill itself suggests using the pipeline API for quick inference and the generation reference when you need control over decoding. Chat or instruction-tuned models should be formatted with the checkpoint's own chat template rather than hand-written role markers. The example below shows the kind of pipeline code the skill uses.

  • Try: Use a Transformers pipeline to classify the sentiment of these customer reviews.
  • Try: Load a causal language model from the Hub and generate a continuation with max_new_tokens set to 50.
  • Try: Fine-tune this classifier on my labelled CSV with TrainingArguments and show me the evaluation loop.
  • Try: Migrate this script from Transformers v4 to v5 and point out removed pipelines.
from transformers import pipeline classifier = pipeline("text-classification", model="distilbert/distilbert-base-uncased-finetuned-sst-2-english") result = classifier("This movie was excellent!")

Safety notes: scripts, network and remote code

The skill runs scripts and uses the network. Hub downloads need network access, and the code the agent writes will run on your machine. Read generated code before you execute it, especially code that downloads models or touches files.

Some Hub models need custom code. The skill says to load these with trust_remote_code only after the custom code has been reviewed, and to pin the exact commit with revision (and code_revision when code lives in a separate repository). Loading remote code runs code you have not checked, so this matters most for production deployments. A gated model with a built-in architecture does not need remote code.

  • Review generated code before running it, especially downloads and file writes
  • Pin revision to a reviewed commit for research or production work
  • Use trust_remote_code=True only after reviewing the custom code
  • Accept the model licence on the Hub before loading gated models

Tips for better results

Start with a pipeline to confirm a model works, then move to AutoModel and a tokenizer when you need custom preprocessing or decoding control. Use explicit checkpoint names rather than relying on task defaults, since the skill notes that defaults can change. Verify model answers against the supplied context, especially for generative question answering.

Set HF_HOME to move all Hugging Face caches, or HF_HUB_CACHE for Hub files only. Use HF_HUB_OFFLINE=1 only after the model files you need are already cached.

  • Prefer max_new_tokens over max_length for causal language models
  • Use the model's own chat template for chat and instruction models
  • Keep the training data formatted with the same template you used for inference
  • Check the Transformers v4 to v5 migration guide before upgrading old code

What people use it for

  • Prototype a sentiment classifier or named entity recognizer with a pipeline before building a custom service.
  • Generate text or code completions from a Hub language model with controlled max_new_tokens and sampling settings.
  • Fine-tune a pre-trained model on your own labelled dataset using TrainingArguments and the Trainer API.
  • Migrate an existing Transformers v4 script to v5 and identify pipelines that were removed.

Frequently asked questions

How do I install the Transformers agent skill?

Download the ZIP from the directory page and unzip it into ~/.claude/skills/ for personal use or into .claude/skills/ inside a project. In the Claude apps, you can upload it under Settings → Capabilities → Skills instead.

What do I need to run the Transformers skill?

You need Python with the minimum version listed in the skill's requirements, PyTorch, and the Transformers library with its related packages. You also need network access to the Hugging Face Hub, and a read-scope token for gated or private models. Optional packages are only needed for specific workflows.

Is the Transformers skill free to use, and what is its licence?

The directory lists the skill under the MIT licence. The SKILL.md header, however, states Apache-2.0, so check the licence files in the ZIP before you rely on either. The skill does not state a price.

Does the Transformers skill work with TensorFlow or JAX?

No. The skill states that Transformers v5 is PyTorch-only because TensorFlow and JAX backends were removed. Use an older Transformers release if you need those backends, and follow its documentation.

Why does loading a model fail with a gated or private model error?

Gated and private models need you to be authenticated. Run hf auth login with a read-scope token, or set HF_TOKEN on a server, and accept the model licence on the Hub. Gated built-in architectures do not need trust_remote_code.

Do I need this skill, or can I just use the Transformers documentation?

If you already know the library, the documentation may be enough. The skill helps most when you want the agent to follow a structured playbook for setup, loading, inference and fine-tuning. For simple chat with a model, the skill adds little because no coding setup is needed.

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 Python developers building NLP, vision or audio prototypes, data scientists fine-tuning an open model on their own labelled data, and engineers migrating code to Transformers v5. It is not a good fit for people who only want to chat with a model, for TensorFlow or JAX users, or for production use with gated or custom-code models that have not had a security review.

Download the skill