Hugging Face Dataset ViewerSkill

Released Nov 24, 2025

Apache-2.0

Summary

Read-only recipes for the Hugging Face Dataset Viewer API — resolve splits, paginate rows, run text search and row filters, and pull parquet URLs and column statistics.

Features

Read-only Dataset Viewer API workflow: /is-valid, /splits, /first-rows, /rows
Text search via /search and row predicates via /filter with where and orderby
Parquet shard URLs through /parquet for direct download
Totals and per-column distributions via /size and /statistics
Croissant metadata retrieval where published
Pagination rules: zero-based offset, 100-row cap, partial-response continuation
Bearer-token auth for gated and private datasets

Install This Skill

Add this skill to your favorite AI agent in a few steps.

Any AI agent

This skill is plain instructions — it works with any assistant that accepts custom instructions or system prompts.

Copy the skill content with the button below.
Paste it into your agent's instruction file or system prompt (for example AGENTS.md, .cursorrules, or a custom instructions field).
Ask the agent to apply the skill whenever the task matches.

Claude Code & Claude apps

Claude loads skills automatically from its skills directory.

Claude Code

Create a skill folder — personal: ~/.claude/skills/huggingface-datasets/, or per-project: .claude/skills/huggingface-datasets/
Save the skill content as SKILL.md inside that folder.
Claude Code picks it up automatically and invokes it when relevant.

mkdir -p ~/.claude/skills/huggingface-datasets

Claude.ai / Claude Desktop

Enable Skills under Settings → Capabilities, then upload the skill (a folder or zip containing SKILL.md).

One-prompt install

Paste this prompt into any agent with web access and it will install the skill for you.

Install the "Hugging Face Dataset Viewer" skill from Onei AI. Fetch https://onei.ai/skills/huggingface-datasets, extract the full skill content from the page, and save it where you load skills from (for Claude Code: .claude/skills/huggingface-datasets/SKILL.md). From now on, apply this skill whenever it is relevant to my request.

Skill Content

Markdown Content

Copy this content and use it with your preferred AI agent

---
name: huggingface-datasets
description: 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.
---

# Hugging Face Dataset Viewer

Use this skill to execute read-only Dataset Viewer API calls for dataset exploration and extraction.

## Core workflow

1. Optionally validate dataset availability with `/is-valid`.
2. Resolve `config` + `split` with `/splits`.
3. Preview with `/first-rows`.
4. Paginate content with `/rows` using `offset` and `length` (max 100).
5. Use `/search` for text matching and `/filter` for row predicates.
6. Retrieve parquet links via `/parquet` and totals/metadata via `/size` and `/statistics`.

## Defaults

- Base URL: `https://datasets-server.huggingface.co`
- Default API method: `GET`
- Query params should be URL-encoded.
- `offset` is 0-based.
- `length` max is usually `100` for row-like endpoints.
- Gated/private datasets require `Authorization: Bearer <HF_TOKEN>`.

## Dataset Viewer

- `Validate dataset`: `/is-valid?dataset=<namespace/repo>`
- `List subsets and splits`: `/splits?dataset=<namespace/repo>`
- `Preview first rows`: `/first-rows?dataset=<namespace/repo>&config=<config>&split=<split>`
- `Paginate rows`: `/rows?dataset=<namespace/repo>&config=<config>&split=<split>&offset=<int>&length=<int>`
- `Search text`: `/search?dataset=<namespace/repo>&config=<config>&split=<split>&query=<text>&offset=<int>&length=<int>`
- `Filter with predicates`: `/filter?dataset=<namespace/repo>&config=<config>&split=<split>&where=<predicate>&orderby=<sort>&offset=<int>&length=<int>`
- `List parquet shards`: `/parquet?dataset=<namespace/repo>`
- `Get size totals`: `/size?dataset=<namespace/repo>`
- `Get column statistics`: `/statistics?dataset=<namespace/repo>&config=<config>&split=<split>`
- `Get Croissant metadata (if available)`: `/croissant?dataset=<namespace/repo>`

Pagination pattern:

```bash
curl "https://datasets-server.huggingface.co/rows?dataset=stanfordnlp/imdb&config=plain_text&split=train&offset=0&length=100"
curl "https://datasets-server.huggingface.co/rows?dataset=stanfordnlp/imdb&config=plain_text&split=train&offset=100&length=100"
```

When pagination is partial, use response fields such as `num_rows_total`, `num_rows_per_page`, and `partial` to drive continuation logic.

Search/filter notes:

- `/search` matches string columns (full-text style behavior is internal to the API).
- `/filter` requires predicate syntax in `where` and optional sort in `orderby`.
- Keep filtering and searches read-only and side-effect free.

For CLI-based parquet URL discovery or SQL, use the `hf-cli` skill with `hf datasets parquet` and `hf datasets sql`.

## Creating and Uploading Datasets

Use one of these flows depending on dependency constraints.

Zero local dependencies (Hub UI):

- Create dataset repo in browser: `https://huggingface.co/new-dataset`
- Upload parquet files in the repo "Files and versions" page.
- Verify shards appear in Dataset Viewer:

```bash
curl -s "https://datasets-server.huggingface.co/parquet?dataset=<namespace>/<repo>"
```

Low dependency CLI flow (`npx @huggingface/hub` / `hfjs`):

- Set auth token:

```bash
export HF_TOKEN=<your_hf_token>
```

- Upload parquet folder to a dataset repo (auto-creates repo if missing):

```bash
npx -y @huggingface/hub upload datasets/<namespace>/<repo> ./local/parquet-folder data
```

- Upload as private repo on creation:

```bash
npx -y @huggingface/hub upload datasets/<namespace>/<repo> ./local/parquet-folder data --private
```

After upload, call `/parquet` to discover `<config>/<split>/<shard>` values for querying with `@~parquet`.

## Agent Traces

The Hub supports raw agent session traces from Claude Code, Codex, and Pi Agent. Upload them to Hugging Face Datasets as original JSONL files and the Hub can auto-detect the trace format, tag the dataset as `Traces`, and enable the trace viewer for browsing sessions, turns, tool calls, and model responses. Common local session directories:

- Claude Code: `~/.claude/projects`
- Codex: `~/.codex/sessions`
- Pi: `~/.pi/agent/sessions`

Default to private dataset repos because traces can contain prompts, file paths, tool outputs, secrets, or PII. Preserve the raw `.jsonl` files and nest them by project/cwd instead of uploading every session at the dataset root.

```bash
hf repos create <namespace>/<repo> --type dataset --private --exist-ok
hf upload <namespace>/<repo> ~/.codex/sessions codex/<project-or-cwd> --type dataset
```

Usage Instructions

Learn how to use this skill with different AI agents.

Claude Desktop

Install the Hugging Face marketplace once, then add this skill with the hf CLI:

/plugin marketplace add huggingface/skills
/plugin install hf-cli@huggingface/skills

hf skills add huggingface-datasets

VS Code

Copy or symlink skills/huggingface-datasets/ from the repository into one of Codex's standard skill locations — $REPO_ROOT/.agents/skills or $HOME/.agents/skills. Codex discovers it through the Agent Skills standard and loads SKILL.md when the task matches.

Generic Instructions

The repository ships a gemini-extension.json, so Gemini CLI installs the whole bundle with gemini extensions install https://github.com/huggingface/skills.git --consent. Cursor installs via the plugin flow using .cursor-plugin/plugin.json. For any other Agent Skills-compatible client, drop the skills/huggingface-datasets/ folder into the client's skills directory. If your agent has no skill support at all, the repository's agentsmd/AGENTS.md bundle is the documented fallback.

Description

This skill teaches an agent to explore a Hugging Face dataset over HTTP without downloading it, which is usually what you want before committing to a multi-gigabyte pull. It is strictly read-only against https://datasets-server.huggingface.co, and it lays out the workflow in the order that actually works: validate with /is-valid, resolve the config and split with /splits, preview with /first-rows, then paginate through /rows.

The endpoint map covers the full surface — /search for text matching, /filter for row predicates with where and orderby, /parquet for shard download links, /size for totals, /statistics for per-column distributions, and /croissant for standardised metadata where a dataset publishes it.

The operational details it pins down are the ones that trip up ad-hoc scripting: offset is zero-based, length caps at 100 on row-like endpoints, query parameters must be URL-encoded, and gated or private datasets need an Authorization: Bearer <HF_TOKEN> header. For continuation logic it points the agent at the response's own num_rows_total, num_rows_per_page and partial fields rather than guessing when to stop.

The practical payoff is that dataset triage — how big is this, what do the columns look like, does it contain the thing I need, where are the parquet files — becomes a handful of cheap API calls instead of a download and a notebook.

Install

Related Skills

Skill: SerpApi Web Search

by SerpApi

SerpApi's official skill for structured search: which of 130+ engines to call for citations, local businesses, flights, hotels, shopping or jobs, which response key holds the answer, and the gotchas that silently return the wrong field.

Development

Skill: NVIDIA NeMo Data Designer

by NVIDIA

NVIDIA's official skill for building synthetic datasets with NeMo Data Designer — describe the data you want and the agent writes a declarative generation pipeline, column by column.

Development

Skill: Sentence Transformers Trainer

by Hugging Face

Train bi-encoders, rerankers, SPLADE sparse encoders and ColBERT multi-vector models with the loss, evaluator and template each type actually needs.

Development

Skill: Hugging Face Vision Trainer

by Hugging Face

Fine-tune object detection, image classification and SAM/SAM2 segmentation models on Hugging Face Jobs cloud GPUs, with dataset validation before you spend GPU minutes.

Development

Browse all skills →