Rework agents docs: simplify, fix links, update skills

docs/hub/_toctree.yml

@@ -440,12 +440,12 @@
   sections:
   - local: agents-overview
     title: Agents on the Hub
+  - local: agents-cli
+    title: Hugging Face CLI for AI Agents
   - local: agents-mcp
     title: Hugging Face MCP Server
   - local: agents-skills
     title: Hugging Face Agent Skills
-  - local: agents-cli
-    title: Agents and the `hf` CLI
   - local: agents-sdk
     title: Building agents with the HF SDK
   - local: agents-local

docs/hub/agents-cli.md

@@ -1,86 +1,43 @@
-# Agents and the `hf` CLI
+# Hugging Face CLI for AI Agents
 
-Coding agents like Claude Code, OpenAI Codex, or Open Code are excellent at using the CLI to interact with the Hub through the `hf` command-line interface. Search for models, datasets, Spaces, and papers. Download models, upload files, manage repositories, and run compute jobs.
+The `hf` CLI is a great way to connect your agents to the Hugging Face ecosystem. Search models, manage datasets, launch Spaces, and run jobs from any coding agent.
 
 > [!TIP]
 > This is a quick guide on agents that use the CLI. For more detailed information, see the [CLI Reference itself](https://huggingface.co/docs/huggingface_hub/guides/cli).
 
-## Skills
+## Install the CLI
 
-Hugging Face Skills are available for the CLI to help your agents interact with the Hub. Skills give agents relevant instructions for how to use the CLI. See the [Skills Guide](./agents-skills) for available skills and usage. That said, most agents can get by using the CLI directly without Skills. Worst case scenario, they will rely on documentation and trial and error to get commands right. Skills will make your agents more efficient and productive.
+Make sure the `hf` CLI is installed and up to date. See the [CLI installation guide](https://huggingface.co/docs/huggingface_hub/guides/cli#getting-started) for setup instructions.
 
-## Installation
+## Add the CLI Skill
 
-Make sure the `hf` CLI is installed on your system.
-
-### Standalone Installer (Recommended)
-
-<hfoptions id="cli-install">
-
-<hfoption id="macOS / Linux">
+Skills give your agent the context it needs to use tools effectively. Install the CLI Skill so your agent knows every `hf` command and stays current with the latest updates. Learn more about Skills at [agentskills.io](https://agentskills.io).
 
 ```bash
-curl -LsSf https://hf.co/cli/install.sh | bash
-```
+# install globally (available in all projects)
+hf skills add --claude --global
 
-</hfoption>
-
-<hfoption id="Windows">
-
-```powershell
-powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"
+# or install for the current project only
+hf skills add --claude
 ```
 
-</hfoption>
-
-</hfoptions>
-
-### Alternative Methods
-
-```bash
-# Using pip
-pip install -U huggingface_hub
-
-# Using Homebrew (macOS)
-brew install hf
-
-# Using uvx (no install needed)
-uvx hf --help
-```
+> [!TIP]
+> The Skill is generated from your locally installed CLI version, so it's always up to date.
 
-### Verify Installation
+This also works with other coding agents:
 
 ```bash
-hf --help
+hf skills add --codex
+hf skills add --cursor
+hf skills add --opencode
 ```
 
-## Hugging Face Skills for the CLI
-
-Hugging Face Skills are available for the CLI to help you interact with the Hub. Skills give agents relevant instructions for how to use the CLI. See the [Skills Guide](./agents-skills) for available skills and usage. 
+Alternatively, you can install via the Claude Code plugin system:
 
 ```bash
-# start claude 
 claude
-
-# install the skills marketplace plugin
 /plugin marketplace add huggingface/skills
-
-# install the hugging face cli skill
-/plugin install hugging-face-cli@huggingface/skills
-```
-
-With Skills installed, your agent can use the CLI to interact with the Hub.
-
-For example, you could use Claude Code to search for datasets:
-
-```
-"What datasets are available for sentiment analysis?"
-```
-
-Or, you could use OpenAI Codex to create pull requests:
-
-```
-"Open a PR with evaluation results from the results.csv file to my/my-model repo on the Hub."
+/plugin install hf-cli@huggingface/skills
 ```
 
 ## Resources

docs/hub/agents-overview.md

@@ -2,8 +2,13 @@
 
 Hugging Face provides tools and protocols that connect AI agents directly to the Hub. Whether you're chatting with Claude, building with Codex, or developing custom agents, you can access models, datasets, Spaces, and community tools. This page covers connecting your [chat agents](#chat-with-hugging-face) and [coding agents](#coding-agents) to the Hub. 
 
-> [!TIP]
-> To build with agents on the Hub, check out the pages on [MCP Server](./agents-mcp), [Skills](./agents-skills), [CLI](./agents-cli), and [SDK](./agents-sdk).
+| Page | Description |
+| ---- | ----------- |
+| [CLI](./agents-cli) | Give your agent the `hf` CLI with a built-in Skill |
+| [MCP Server](./agents-mcp) | Connect any MCP-compatible client to the Hub |
+| [Skills](./agents-skills) | Task-specific guidance for AI/ML workflows |
+| [SDK](./agents-sdk) | Build agents programmatically with Python or JavaScript |
+| [Local Agents](./agents-local) | Run fully local agents with llama.cpp and Pi |
 
 ## Chat with Hugging Face
 
@@ -74,7 +79,7 @@ Integrate Hugging Face into your coding workflow with the MCP Server and Skills.
 | [Claude Code](https://code.claude.com/docs) | MCP Server + Skills |
 | [OpenAI Codex](https://openai.com/codex/) | MCP Server + Skills |
 | [Open Code](https://opencode.ai/) | MCP Server + Skills |
-| [Cursor](https://www.cursor.com/) | MCP Server |
+| [Cursor](https://www.cursor.com/) | MCP Server + Skills |
 | [VS Code](https://code.visualstudio.com/) | MCP Server |
 | [Gemini CLI](https://geminicli.com/) | MCP Server |
 | [Zed](https://zed.dev/) | MCP Server |
@@ -113,7 +118,7 @@ claude
 
 Then, to install a Skill specification:
 ```bash
-/plugin install hugging-face-cli@huggingface/skills
+/plugin install hf-cli@huggingface/skills
 ```
 
 See the [Skills Guide](./agents-skills) for available skills and usage.
@@ -178,7 +183,7 @@ Agent: [Fetches documentation]
 
 ## Next Steps
 
-- [MCP Server](./agens-mcp) - Connect any MCP-compatible AI assistant to the Hub
-- [Skills](./agens-skills) - Pre-built capabilities for coding agents
-- [CLI](./agens-cli) - Command-line interface for Hub operations  
-- [SDK](./agens-sdk) - Python and JavaScript libraries for building agents
+- [CLI](./agents-cli) - Command-line interface for Hub operations
+- [MCP Server](./agents-mcp) - Connect any MCP-compatible AI assistant to the Hub
+- [Skills](./agents-skills) - Pre-built capabilities for coding agents
+- [SDK](./agents-sdk) - Python and JavaScript libraries for building agents

docs/hub/agents-skills.md

@@ -1,115 +1,83 @@
 # Skills
 
-Skills are [Agent Context](https://agents.md) definitions that provide coding agents with structured guidance for AI/ML tasks. They help agents understand best practices for a given domain or task. Hugging Face Skills is a repository of skills specifically designed for AI/ML tasks that you can make available to your coding agents.
-
-Hugging Face Skills work with major coding agents:
-- OpenAI Codex
-- Anthropic Claude Code
-- Google Gemini CLI
-- Cursor
+> [!TIP]
+> Looking for the `hf` CLI Skill? It's the quickest way to connect your agent to the Hugging Face ecosystem. See the [Hugging Face CLI for AI Agents](./agents-cli) guide.
 
-Each skill includes:
-- Task definitions and workflows
-- Best practices and guidelines
-- Helper scripts and templates
-- Integration with Hugging Face tools
+Hugging Face provides a curated set of Skills built for AI builders. Train models, create datasets, run evaluations, track experiments. Each Skill is a self-contained `SKILL.md` that your agent follows while working on the task.
 
-> [!TIP]
-> In practice, coding agents are excellent at writing and defining custom skills using the [Agent Skills format](https://agentskills.io/home). Therefore, it is best to use Hugging Face Skills as building blocks for your domain-specific skills.
+Skills work with all major coding agents: Claude Code, OpenAI Codex, Google Gemini CLI, and Cursor. Learn more about the format at [agentskills.io](https://agentskills.io).
 
 ## Installation
 
-Skills provide task-specific guidance for AI/ML workflows. They work alongside MCP or standalone.
-
 <hfoptions id="install-skills">
 
 <hfoption id="Claude Code">
 
 ```bash
-# start claude 
-claude
-
-# install the skills marketplace plugin
+# register the skills marketplace
 /plugin marketplace add huggingface/skills
-```
-
-Then, to install a specific skill, use the following command:
 
-```bash
-# skill name + marketplace 
+# install a specific Skill
 /plugin install <skill-name>@huggingface/skills
-
-# for example, to install the hugging face cli skill
-/plugin install hugging-face-cli@huggingface/skills
 ```
 
 </hfoption>
 
 <hfoption id="OpenAI Codex">
 
-```bash
-# start codex
-codex
+Copy or symlink skills from the [repository](https://github.com/huggingface/skills) into one of Codex's standard `.agents/skills` locations (e.g. `$REPO_ROOT/.agents/skills` or `$HOME/.agents/skills`). Codex discovers them automatically via the Agent Skills standard.
 
-# install all Hugging Face Skills
-$skill-installer install https://github.com/huggingface/skills
-```
+Alternatively, use the bundled [`agents/AGENTS.md`](https://github.com/huggingface/skills/blob/main/agents/AGENTS.md) as a fallback.
+
+</hfoption>
 
-Or, to install a specific skill, use the following command:
+<hfoption id="Gemini CLI">
 
 ```bash
-# skill name + marketplace 
-$skill-installer install <skill-name> from https://github.com/huggingface/skills
+gemini extensions install https://github.com/huggingface/skills.git --consent
 ```
 
-For some GPT models, `skill-installer` works better with models on a local directory of skills, so do:
+</hfoption>
 
-```bash
-git clone https://github.com/huggingface/skills
+<hfoption id="Cursor">
 
-# start codex
-codex
+Install via the Cursor plugin flow using the [repository URL](https://github.com/huggingface/skills). The repo includes `.cursor-plugin/plugin.json` and `.mcp.json` manifests.
 
-# install the skills from the local directory
-$skill-installer install the hugging face cli skill from the skills/skills/hugging-face-cli/ folder
-```
 </hfoption>
 
 </hfoptions>
 
-### What You Can Do
-
-Once configured, your coding agent can:
-
-| Capability | Example |
-| ---------- | ------- |
-| Search the Hub | "Find a code generation model under 7B parameters" |
-| Explore datasets | "What datasets are available for sentiment analysis?" |
-| Run Spaces | "Use the Whisper Space to transcribe this audio file" |
-| Get documentation | "How do I fine-tune a model with transformers?" |
-| Train a model | "Train an LLM with SFT using the Qwen/Qwen3-0.6B model and the trl-lib/Capybara dataset" |
-| Query a dataset | "Tell me about the evalstate/mcp-clients dataset from the last 2 days" |
-
 ## Available Skills
 
-Hugging Face Skills are available in the [Hugging Face Skills repository](https://github.com/huggingface/skills) and include two types of skills:
+| Skill | What it does |
+| ----- | ------------ |
+| [`hf-cli`](https://github.com/huggingface/skills/tree/main/skills/hf-cli) | Hub operations via the `hf` CLI: download, upload, manage repos, run jobs |
+| [`hugging-face-datasets`](https://github.com/huggingface/skills/tree/main/skills/hugging-face-datasets) | Create and manage datasets on the Hub |
+| [`hugging-face-dataset-viewer`](https://github.com/huggingface/skills/tree/main/skills/hugging-face-dataset-viewer) | Explore and query any dataset via the Dataset Viewer API |
+| [`hugging-face-model-trainer`](https://github.com/huggingface/skills/tree/main/skills/hugging-face-model-trainer) | Train or fine-tune LLMs with TRL (SFT, DPO, GRPO) on HF Jobs |
+| [`hugging-face-vision-trainer`](https://github.com/huggingface/skills/tree/main/skills/hugging-face-vision-trainer) | Train object detection and image classification models |
+| [`hugging-face-object-detection-trainer`](https://github.com/huggingface/skills/tree/main/skills/hugging-face-object-detection-trainer) | Fine-tune object detection models (RTDETRv2, YOLOS, DETR) |
+| [`hugging-face-evaluation`](https://github.com/huggingface/skills/tree/main/skills/hugging-face-evaluation) | Add and manage evaluation results in model cards |
+| [`hugging-face-jobs`](https://github.com/huggingface/skills/tree/main/skills/hugging-face-jobs) | Run compute jobs on Hugging Face infrastructure |
+| [`hugging-face-trackio`](https://github.com/huggingface/skills/tree/main/skills/hugging-face-trackio) | Track and visualize ML training experiments |
+| [`hugging-face-paper-publisher`](https://github.com/huggingface/skills/tree/main/skills/hugging-face-paper-publisher) | Publish and manage research papers on the Hub |
+| [`hugging-face-tool-builder`](https://github.com/huggingface/skills/tree/main/skills/hugging-face-tool-builder) | Build reusable scripts for HF API operations |
+| [`gradio`](https://github.com/huggingface/skills/tree/main/skills/huggingface-gradio) | Build Gradio web UIs and demos |
+| [`transformers-js`](https://github.com/huggingface/skills/tree/main/skills/transformers.js) | Run ML models in JavaScript/TypeScript with WebGPU/WASM |
 
-- **Domain-specific skills** are ideal for instructing agents on specific AI tasks like dataset creation, model training, evaluation, and more.
-- **Tool skills** are ideal for instructing agents on how to use the Hugging Face tools like the CLI, Hugging Face Spaces, or Hugging Face Jobs.
+## Using Skills
 
-For example, currently available skills include:
+Once installed, mention the Skill directly in your prompt:
 
-- [hf-cli](https://github.com/huggingface/skills/tree/main/skills/hugging-face-cli) - The Hugging Face CLI skill
-- [hf-datasets](https://github.com/huggingface/skills/tree/main/skills/hugging-face-datasets) - The Hugging Face Dataset Creation and Management skill
-- [hf-trainer](https://github.com/huggingface/skills/tree/main/skills/hugging-face-model-trainer) - The Hugging Face Model Trainer skill
-- [hf-evaluation](https://github.com/huggingface/skills/tree/main/skills/hugging-face-evaluation) - The Hugging Face Model Evaluator skill
-- [hf-jobs](https://github.com/huggingface/skills/tree/main/skills/hugging-face-jobs) - The Hugging Face Jobs skill
+- "Use the HF model trainer Skill to fine-tune Qwen3-0.6B with SFT on the Capybara dataset"
+- "Use the HF evaluation Skill to add benchmark results to my model card"
+- "Use the HF datasets Skill to create a new dataset from these examples"
 
+Your agent loads the corresponding `SKILL.md` instructions and helper scripts automatically.
 
 ## Resources
 
 - [Skills Repository](https://github.com/huggingface/skills) - Browse and contribute
-- [Agent Context Protocol](https://agents.md) - ACP specification
-- [Agent Skills format](https://agentskills.io/home) - Agent Skills format
-- [MCP Guide](./agents-mcp) - Use alongside skills
-
+- [Agent Skills format](https://agentskills.io/home) - Specification and docs
+- [CLI Guide](./agents-cli) - Hugging Face CLI for AI Agents
+- [MCP Guide](./agents-mcp) - Use alongside Skills