huggingface-skills — плагин для Claude Code: скиллы для работы с Hub

# Hugging Face Skills

Hugging Face Skills are definitions for AI/ML tasks like dataset creation, model training, and evaluation. The client plugin marketplaces expose the `hf-cli` skill as the bootstrap path for core Hub operations; additional workflow skills can be installed on demand with `hf skills add <skill-name>` or discovered by skill-aware clients over CLI/MCP integrations.

The skills in this repository follow the standardized [Agent Skills](https://agentskills.io/home) format.

> [!NOTE]
> **Just want to give your agent access to the Hugging Face Hub?** Start with [`hf-cli`](https://huggingface.co/docs/hub/agents-cli). It's the recommended first Skill to install: it teaches your agent every `hf` command (search models, manage datasets and buckets, launch Spaces, run jobs) and is generated from your locally installed CLI so it stays current.

## How do Skills work?

In practice, skills are self-contained folders that package instructions, scripts, and resources together for an AI agent to use on a specific use case. Each folder includes a `SKILL.md` file with YAML frontmatter (name and description) followed by the guidance your coding agent follows while the skill is active. 

> [!TIP]
> If your agent doesn't support skills, you can use [`agentsmd/AGENTS.md`](agentsmd/AGENTS.md) directly as a fallback.

The `hf-cli` skill in this repository is also available through:
 - Cursor Marketplace (https://cursor.com/marketplace/huggingface)
 - Codex Plugins Directory (https://developers.openai.com/codex/plugins)

## Installation

Hugging Face skills are compatible with Claude Code, Codex, Gemini CLI, and Cursor.

### Claude Code

1. Register the repository as a plugin marketplace:  
   
```
/plugin marketplace add huggingface/skills
```

2. Install the CLI skill:  
   
```
/plugin install hf-cli@huggingface/skills
```

3. To install another Hugging Face skill, use the `hf` CLI:  

```
hf skills add <skill-name>
```

### Codex

1. Copy or symlink any skills you want to use from this repository's `skills/` directory into one of Codex's standard `.agents/skills` locations (for example, `$REPO_ROOT/.agents/skills` or `$HOME/.agents/skills`) as described in the [Codex Skills guide](https://developers.openai.com/codex/skills/).

2. Once a skill is available in one of those locations, Codex will discover it using the Agent Skills standard and load the `SKILL.md` instructions when it decides to use that skill or when you explicitly invoke it.

3. If your Codex setup still relies on `AGENTS.md`, you can use the generated [`agentsmd/AGENTS.md`](agentsmd/AGENTS.md) file in this repo as a fallback bundle of instructions.

### Gemini CLI

1. This repo includes `gemini-extension.json` to integrate with the Gemini CLI.

2. Install locally:  

```
gemini extensions install . --consent
```

or use the GitHub URL:

```
gemini extensions install https://github.com/huggingface/skills.git --consent
```

4. See [Gemini CLI extensions docs](https://geminicli.com/docs/extensions/#installing-an-extension) for more help.

### Cursor

This repository includes Cursor plugin manifests:

- `.cursor-plugin/plugin.json`
- `.mcp.json` (configured with the Hugging Face MCP server URL)

Install from repository URL (or local checkout) via the Cursor plugin flow. The marketplace entry is intentionally limited to `hf-cli`; use `hf skills add <skill-name>` to install additional workflow skills.

For contributors, regenerate manifests with:

```bash
./scripts/publish.sh
```

## Skills

This repository contains a few skills to get you started. You can also contribute your own skills to the repository.

### Available skills

<!-- This table is auto-generated by scripts/generate_agents.py. Do not edit manually. -->
<!-- BEGIN_SKILLS_TABLE -->
| Name | Description | Documentation |
|------|-------------|---------------|
| `hf-cli` | Hugging Face Hub CLI (`hf`) for downloading, uploading, and managing models, datasets, spaces, buckets, repos, papers, jobs, and more on the Hugging Face Hub. | [SKILL.md](skills/hf-cli/SKILL.md) |
| `hf-cloud-aws-context-discovery` | Discover the user''s local AWS context (active profile, region, account ID, caller identity) at the start of any AWS task. | [SKILL.md](skills/hf-cloud-aws-context-discovery/SKILL.md) |
| `hf-cloud-python-env-setup` | Set up an isolated Python environment for SageMaker / AWS work, with the right Python version and current boto3. | [SKILL.md](skills/hf-cloud-python-env-setup/SKILL.md) |
| `hf-cloud-sagemaker-deployment-planner` | Plan and coordinate the deployment of a model to Amazon SageMaker AI. | [SKILL.md](skills/hf-cloud-sagemaker-deployment-planner/SKILL.md) |
| `hf-cloud-sagemaker-iam-preflight` | Ensure a usable SageMaker execution role exists before deploying or training. | [SKILL.md](skills/hf-cloud-sagemaker-iam-preflight/SKILL.md) |
| `hf-cloud-sagemaker-production-defaults` | Create a SageMaker endpoint (real-time, real-time scale-to-zero, or async) with autoscaling, CloudWatch alarms, and tagging enabled by default. | [SKILL.md](skills/hf-cloud-sagemaker-production-defaults/SKILL.md) |
| `hf-cloud-serving-image-selection` | Pick the right serving container for a SageMaker model deployment and find its current image URI. | [SKILL.md](skills/hf-cloud-serving-image-selection/SKILL.md) |
| `hf-mem` | Hugging Face CLI to estimate the required memory to load Safetensors or GGUF model weights for inference from the Hugging Face Hub | [SKILL.md](skills/hf-mem/SKILL.md) |
| `huggingface-best` | Use when the user asks about finding the best, top, or recommended model for a task, wants to know what AI model to use, or wants to compare models by benchmark scores. | [SKILL.md](skills/huggingface-best/SKILL.md) |
| `huggingface-community-evals` | Run evaluations for Hugging Face Hub models using inspect-ai and lighteval on local hardware. | [SKILL.md](skills/huggingface-community-evals/SKILL.md) |
| `huggingface-datasets` | Use this skill for Hugging Face Dataset Viewer API workflows that fetch subset/split metadata, paginate rows, search text, apply filters, download parquet URLs, and read size or statistics. | [SKILL.md](skills/huggingface-datasets/SKILL.md) |
| `huggingface-gradio` | Build Gradio web UIs and demos in Python. | [SKILL.md](skills/huggingface-gradio/SKILL.md) |
| `huggingface-llm-trainer` | Train or fine-tune language and vision models using TRL (Transformer Reinforcement Learning) or Unsloth with Hugging Face Jobs infrastructure. | [SKILL.md](skills/huggingface-llm-trainer/SKILL.md) |
| `huggingface-local-models` | Use to select models to run locally with llama.cpp and GGUF on CPU, Mac Metal, CUDA, or ROCm. | [SKILL.md](skills/huggingface-local-models/SKILL.md) |
| `huggingface-lora-space-builder` | Build and publish a Gradio demo on Hugging Face Spaces for a user-provided LoRA. | [SKILL.md](skills/huggingface-lora-space-builder/SKILL.md) |
| `huggingface-paper-publisher` | Publish and manage research papers on Hugging Face Hub. | [SKILL.md](skills/huggingface-paper-publisher/SKILL.md) |
| `huggingface-papers` | Look up and read Hugging Face paper pages in markdown, and use the papers API for structured metadata such as authors, linked models/datasets/spaces, Github repo and project page. | [SKILL.md](skills/huggingface-papers/SKILL.md) |
| `huggingface-spaces` | Build, deploy, and maintain applications on Hugging Face Spaces — Gradio / Docker / Static SDKs, ZeroGPU and dedicated hardware, model loading, debugging, buckets, inference providers, community grants. | [SKILL.md](skills/huggingface-spaces/SKILL.md) |
| `huggingface-tool-builder` | 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. | [SKILL.md](skills/huggingface-tool-builder/SKILL.md) |
| `huggingface-trackio` | Track and visualize ML training experiments with Trackio. | [SKILL.md](skills/huggingface-trackio/SKILL.md) |
| `huggingface-vision-trainer` | Trains and fine-tunes vision models for object detection (D-FINE, RT-DETR v2, DETR, YOLOS), image classification (timm models — MobileNetV3, MobileViT, ResNet, ViT/DINOv3 — plus any Transformers classifier), and SAM/SAM2 segmentation using Hugging Face Transformers on Hugging Face Jobs cloud GPUs. | [SKILL.md](skills/huggingface-vision-trainer/SKILL.md) |
| `huggingface-zerogpu` | AI demos and GPU compute with Gradio Spaces and Hugging Face Spaces ZeroGPU. | [SKILL.md](skills/huggingface-zerogpu/SKILL.md) |
| `train-sentence-transformers` | Train or fine-tune sentence-transformers models across `SentenceTransformer` (bi-encoder; dense or static embedding model; for retrieval, similarity, clustering, classification, paraphrase mining, dedup, multimodal), `CrossEncoder` (reranker; pair scoring for two-stage retrieval / pair classification), and `SparseEncoder` (SPLADE, sparse embedding model; for learned-sparse retrieval). | [SKILL.md](skills/train-sentence-transformers/SKILL.md) |
| `transformers-js` | Use Transformers.js to run state-of-the-art machine learning models directly in JavaScript/TypeScript. | [SKILL.md](skills/transformers-js/SKILL.md) |
| `trl-training` | Train and fine-tune transformer language models using TRL (Transformers Reinforcement Learning). | [SKILL.md](skills/trl-training/SKILL.md) |
<!-- END_SKILLS_TABLE -->

### Using skills in your coding agent

Once a skill is installed, mention it directly while giving your coding agent instructions:

- "Use the HF LLM trainer skill to estimate the GPU memory needed for a 70B model run."
- "Use the HF model evaluation skill to launch `run_eval_job.py` on the latest checkpoint."
- "Use the HF dataset creator skill to draft new few-shot classification templates."
- "Use the HF paper publisher skill to index my arXiv paper and link it to my model."

Your coding agent automatically loads the corresponding `SKILL.md` instructions and helper scripts while it completes the task.

### Contribute or customize a skill

1. Copy one of the existing skill folders (for example, `hf-datasets/`) and rename it.
2. Update the new folder's `SKILL.md` frontmatter:
   ```markdown
   ---
   name: my-skill-name
   description: Describe what the skill does and when to use it
   ---

   # Skill Title
   Guidance + examples + guardrails
   ```
3. Add or edit supporting scripts, templates, and documents referenced by your instructions.
4. Do not add the skill to `.claude-plugin/marketplace.json` by default. Client marketplaces are intentionally limited to `hf-cli`; the full Hub CLI marketplace is generated at `.claude-plugin/marketplace-internal.json`.
5. Run:
   ```bash
   ./scripts/publish.sh
   ```
   to regenerate and validate all generated metadata.
6. Reinstall or reload the skill bundle in your coding agent so the updated folder is available.

### Marketplace

The `.claude-plugin/marketplace.json` and `.cursor-plugin/marketplace.json` files intentionally expose only `hf-cli` for client marketplace installation. This keeps install-time manifests focused on core Hub operations and points users to `hf skills add <skill-name>` for the rest of the repository.

The generated `.claude-plugin/marketplace-internal.json` file contains the full skill list. Publish automation uploads it to the Hub bucket as `marketplace.json` so `hf skills list`, `hf skills add`, and `hf skills update` continue to see every available skill.

Newer skill-aware integrations can also pull capabilities dynamically. Hugging Face's discovery flow lets clients search skills, MCP servers, and Spaces, while Skills-over-MCP work is standardizing how skills are discovered and consumed through MCP resources.

### Additional references
- Browse the latest instructions, scripts, and templates directly at [huggingface/skills](https://github.com/huggingface/skills).
- Review Hugging Face documentation for the specific libraries or workflows you reference inside each skill.