Skip to content
Hugging Face Dataset Viewer

Hugging Face Dataset Viewer Skill

by Hugging Face huggingface/skills skills/huggingface-datasets

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.

GitHub Docs
Data & Analytics
Released
Apache-2.0

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from huggingface/skills.

$ npx skills add huggingface/skills --skill huggingface-datasets

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

Copy the whole skill folder — SKILL.md and any scripts or references beside it — into ~/.claude/skills/huggingface-datasets/, where Claude Code picks it up in every project. Only git is needed.

tmp=$(mktemp -d) && \
  git clone --depth 1 --branch main https://github.com/huggingface/skills.git "$tmp" && \
  mkdir -p ~/.claude/skills && \
  cp -R "$tmp"/skills/huggingface-datasets ~/.claude/skills/huggingface-datasets

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/huggingface-datasets/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/
Open folder on GitHub

About

  • 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

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.

SKILL.md

The instructions your agent loads, as published by Hugging Face.

SKILL.md
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:

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:
curl -s "https://datasets-server.huggingface.co/parquet?dataset=<namespace>/<repo>"

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

  • Set auth token:
export HF_TOKEN=<your_hf_token>
  • Upload parquet folder to a dataset repo (auto-creates repo if missing):
npx -y @huggingface/hub upload datasets/<namespace>/<repo> ./local/parquet-folder data
  • Upload as private repo on creation:
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.

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

Related Skills

See all Hugging Face Dataset Viewer alternatives

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.

Data & Analytics

Skill: Firecrawl CLI

by Firecrawl

New

Firecrawl's official routing skill for its CLI: lets an agent search the web, scrape and map sites, crawl sections, monitor pages for changes and interact with pages behind clicks or logins, saving clean markdown to .firecrawl/.

DevelopmentData & Analytics
Browse all skills →