SkillRepo
Sign InSign Up
Catalog
huggingface/huggingface-datasets

huggingface

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.

global
New~1.2k
v1.0Saved Jul 11, 2026

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
Files1
1 files · 11.1 KB

Select a file to preview

Overall Score

78/100

Grade

B

Good

Safety

82

Quality

76

Clarity

82

Completeness

68

Summary

This skill provides structured guidance for executing read-only Hugging Face Dataset Viewer API calls. It covers dataset exploration (validation, listing splits, previewing rows), pagination, searching, filtering, and metadata retrieval. It also documents workflows for creating and uploading datasets, plus uploading agent session traces to the Hub with privacy considerations.

Detected Capabilities

http request (GET to Hugging Face API)environment variable read (HF_TOKEN for authentication)CLI tool usage (npx @huggingface/hub, hf CLI)file upload (parquet files, session traces)

Trigger Keywords

Phrases that MCP clients use to match this skill to user intent.

explore datasetsearch hugging facepaginate dataset rowsfilter datasetdownload parquetupload to hubcreate dataset repo

Risk Signals

INFO

Authorization token reference (HF_TOKEN) for gated/private datasets

Defaults section and 'Creating and Uploading Datasets'
INFO

Environment variable export (HF_TOKEN) in CLI flow

'Low dependency CLI flow' subsection
INFO

Session trace upload documentation mentions potential sensitive content (secrets, PII, file paths)

'Agent Traces' section

Referenced Domains

External domains referenced in skill content, detected by static analysis.

datasets-server.huggingface.cohuggingface.cowww.apache.org

Use Cases

  • Explore a dataset's structure by validating availability, listing configurations and splits, and previewing rows
  • Paginate through large datasets using offset and length parameters to extract subsets of rows
  • Search and filter dataset rows using text queries and predicates to find specific records
  • Retrieve parquet file URLs and metadata (size, statistics) for downstream processing or SQL analysis
  • Upload local parquet files to Hugging Face Datasets using the Hub UI or CLI
  • Create private dataset repositories to archive agent session traces (Claude, Codex, Pi) with full context preservation

Quality Notes

  • Strength: Clear core workflow section with numbered steps and API endpoint patterns documented comprehensively
  • Strength: Well-structured endpoint reference table with curl examples for pagination
  • Strength: Explicit pagination guidance including `num_rows_total`, `partial` field usage for continuation logic
  • Strength: Separate flows for dataset creation (Hub UI vs. CLI) with clear dependency trade-offs
  • Strength: Security-conscious guidance on private repos for agent traces; explicitly warns about sensitive content
  • Strength: Cross-references to `hf-cli` skill for advanced parquet/SQL operations (avoids duplication)
  • Minor gap: No explicit error handling guidance (e.g., 401 for auth failure, 404 for missing dataset, rate limiting)
  • Minor gap: No documentation of response structure examples (what fields are returned by each endpoint)
  • Minor gap: Search/filter notes are brief; no predicate syntax examples or query best practices provided
  • Minor gap: No guidance on handling gated datasets or token refresh strategies
Model: claude-haiku-4-5-20251001Analyzed: Jul 11, 2026

Reviews

Add this skill to your library to leave a review.

No reviews yet

Be the first to share your experience.

Add huggingface/huggingface-datasets to your library

Get Started Free

Command Palette

Search for a command to run...