kaggle-skill

kaggle-skill is an agent skill and plugin for end-to-end Kaggle work: credential setup, competition research, dataset/model downloads, notebook execution, submissions, forums and writeups, benchmark workflows, and badge collection.

This is an independent, unofficial project. It is not affiliated with, endorsed by, or sponsored by Kaggle or Google.

The repository name is kaggle-skill; the public skill and plugin name is kaggle. It works with agents that support SKILL-style packages, including Claude Code, Codex, OpenClaw, Antigravity CLI (agy), Hermes, Cursor, and 35+ agents via skills.sh. Antigravity CLI is recommended for new installs; Gemini CLI remains tested for legacy compatibility.

Demo

Quick agent use case: ask the agent to use the Kaggle skill to retrieve and preview the writeups from the top 3 ranked submissions in the Vesuvius Challenge surface detection competition. Replay it with asciinema play docs/demo/vesuvius-top-writeups.cast.

Terminal walkthrough: install kaggle@shepsci, verify Kaggle credentials without exposing secrets, summarize Titanic competition pages, and retrieve recent Kaggle writeup discussions. Replay the committed clean source cast with asciinema play docs/demo/install-and-demo.cast.

More task-focused local screencasts live in the demo library.

Available On

Platform	Link	Install
skills.sh	skills.sh/shepsci/kaggle-skill	npx skills add shepsci/kaggle-skill
ClawHub	clawhub.ai/skills/kaggle	clawhub install kaggle
Codex self-hosted repo marketplace	github.com/shepsci/kaggle-skill	codex plugin marketplace add shepsci/kaggle-skill --ref main then codex plugin add kaggle@shepsci
Claude Code self-hosted marketplace	github.com/shepsci/kaggle-skill	/plugin marketplace add shepsci/kaggle-skill then /plugin install kaggle@shepsci

What You Can Ask

• "Set up my Kaggle credentials."
• "Summarize the rules and evaluation metric for the Titanic competition."
• "Generate a Kaggle competition landscape report for the last 30 days."
• "Search Kaggle discussion topics about ensembling."
• "Find recent solution writeups for this competition."
• "Use the Kaggle skill to retrieve and preview the writeups from the top 3 ranked submissions in the Vesuvius Challenge surface detection competition."
• "Pull every writeup from kaggle-measuring-agi and group by track."
• "Download this dataset and prepare it for a notebook."
• "Push this notebook to Kaggle Kernels and tell me when it finishes."
• "Initialize a Kaggle benchmark task and run one model."
• "What badges can I still earn through API activity?"

Documentation

Need	Start Here
Install and first run	Docs hub
Choose the right workflow	Workflow guide
Credential setup	Setup module
Module map	Modules guide
Competition and hackathon workflows	Competitions module
Dataset workflows	Datasets module
Model workflows	Models module
Notebook workflows	Notebooks module
Forums, discussions, and writeups	Discussions module
Benchmark task workflows	Benchmarks module
Badge collection	Badges module
Current Kaggle CLI command surface	CLI reference
MCP tool inventory	MCP reference
Troubleshooting	Troubleshooting guide
Plugin distribution status	Codex request packet and Claude directory packet
Screencasts and demo recording	Demo library

Install

Claude Code

/plugin marketplace add shepsci/kaggle-skill
/plugin install kaggle@shepsci

Claude's marketplace add command adds a marketplace catalog, not an individual plugin. shepsci/kaggle-skill contains its own .claude-plugin/marketplace.json, so it is the canonical Claude marketplace source for kaggle.

Codex

codex plugin marketplace add shepsci/kaggle-skill --ref main
codex plugin add kaggle@shepsci

skills.sh

npx skills add shepsci/kaggle-skill

ClawHub

clawhub install kaggle

Manual Clone

git clone https://github.com/shepsci/kaggle-skill.git
cd kaggle-skill
python3 -m pip install \
  "kagglehub>=1.0.0" \
  "kaggle>=2.2.3" \
  "kagglesdk>=0.1.33,<1.0" \
  python-dotenv requests

Then copy skills/kaggle/ into your agent's skills directory if your agent does not support plugin or marketplace installs.

Credential Setup

Kaggle's current token flow uses a single token string. Save it in one of these locations:

mkdir -p ~/.kaggle
printf '%s\n' 'YOUR_TOKEN' > ~/.kaggle/access_token
chmod 600 ~/.kaggle/access_token

or:

export KAGGLE_API_TOKEN='YOUR_TOKEN'

Legacy ~/.kaggle/kaggle.json credentials still work for many CLI workflows, but KAGGLE_API_TOKEN or ~/.kaggle/access_token is preferred for MCP-backed workflows. Verify setup with:

python3 skills/kaggle/modules/setup/scripts/check_all_credentials.py

Quick Examples

Competition Pages

python3 skills/kaggle/modules/competitions/scripts/competition_pages.py \
  --competition titanic --summary

python3 skills/kaggle/modules/competitions/scripts/competition_pages.py \
  --competition titanic --page evaluation

Forums And Topics

python3 skills/kaggle/modules/discussions/scripts/forums.py forum-topics \
  --category competition_write_ups --sort-by recent --format json

python3 skills/kaggle/modules/discussions/scripts/forums.py resource-topics \
  competitions titanic --sort-by recent --page 1 --format json

Leaderboard Writeup Links

python3 skills/kaggle/modules/discussions/scripts/leaderboard_writeups.py \
  vesuvius-challenge-surface-detection --top-k 3 --preview --pretty

Hackathon Writeups

python3 skills/kaggle/modules/competitions/hackathons/scripts/list_writeups.py \
  --competition kaggle-measuring-agi --array

python3 skills/kaggle/modules/competitions/hackathons/scripts/fetch_writeup.py \
  --writeup-id 71617

Benchmark CLI

kaggle b init -y
kaggle b t push my-task -f task.py --wait 600
kaggle b t run my-task -m gemini-2.5-pro --wait

All wrappers that emit Kaggle-supplied text wrap that text in <untrusted-content source="..." tool="..."> markers so agents treat external content as data rather than instructions. The guard is enforced by tests/security/test_untrusted_content_wrappers.py.

Architecture

The skill is organized around workflow modules:

Module	Purpose
setup	Account setup, token storage, credential checks, network checks
competitions	Competition pages, landscape reports, submissions, hackathons
datasets	Dataset download and publish flows
models	Model download and publish flows
notebooks	Notebook publish, execution, polling, and output download
discussions	Forums, resource topics, and solution writeup discovery
benchmarks	Benchmark CLI workflows and MCP endpoint notes
badges	API-first badge earning workflows with manual fallbacks
references	Cross-cutting CLI, MCP, and platform references

When installed as a Claude Code plugin, the bundled .mcp.json configures the Kaggle MCP server. The live inventory was verified on 2026-07-03 with 70 tools; see the MCP reference for status notes and role-gated endpoints.

Distribution Status

The public skill name and plugin name are both kaggle.

This repo includes:

• .codex-plugin/plugin.json for Codex.
• .agents/plugins/marketplace.json for Codex repo marketplace installs.
• .claude-plugin/plugin.json for Claude Code.
• .claude-plugin/marketplace.json for in-repo Claude marketplace metadata.

Current status:

• kaggle-skill is self-hosted and installable from this repository and from third-party skill indexes such as skills.sh and ClawHub.
• This project is independent and unofficial. It is not affiliated with, endorsed by, or sponsored by Kaggle or Google.
• Claude plugin-directory submission is the first official-listing target. Anthropic Verified is a separate discretionary review goal to pursue after directory acceptance and usage evidence.
• Codex curated listing depends on OpenAI's official publishing or partner review path. The repo marketplace remains the supported Codex install path until a curated listing is accepted.
• This repository does not claim Claude official, Anthropic Verified, or OpenAI-curated status unless those default catalogs list it.

The plugin selector remains kaggle@shepsci for compatibility with existing installs. If a reviewer requires a less first-party-looking identifier, use the distribution packets to evaluate a future rename such as kaggle-workflows.

The bundled .mcp.json configures Kaggle's remote MCP endpoint with a user-provided bearer token from KAGGLE_API_TOKEN. That is documented as a review consideration in the Claude and Codex distribution packets.

Security

Security claims are backed by tests in tests/security/ and tests/manifest/.

Property	Guard
No dynamic eval, exec, compile, or __import__ in scripts	tests/security/test_no_dynamic_eval.py
Credentials are not echoed to stdout, stderr, or logs	tests/security/test_no_credential_leakage.py
Kaggle-supplied text is wrapped as untrusted content	tests/security/test_untrusted_content_wrappers.py
Zip extraction blocks path traversal	tests/security/test_zip_slip_protection.py
Dataset slugs are validated before shell use	tests/security/test_dataset_slug_validation.py
SessionStart hook avoids auto-installing packages or sourcing CWD .env	tests/security/test_session_start_hook_safety.py
MCP config uses HTTPS plus env-var token substitution	tests/manifest/test_mcp_json_valid.py

Report security issues through SECURITY.md. General support and distribution questions can be filed as GitHub issues.

Network egress is limited to Kaggle, Google storage, PyPI, and GitHub domains in .claude/settings.json.

Compatibility

Platform	Status
Claude Code	Tested
OpenClaw	Tested
Antigravity CLI (agy)	Tested
Gemini CLI (legacy)	Tested
Codex	Tested
Hermes	Compatible
Cursor	Compatible
GitHub Copilot	Compatible
Cline	Compatible
Amp	Compatible
35+ agents via skills.sh	Compatible

License And Privacy

MIT license. See LICENSE.

This skill collects no data. Credentials and processing remain local; see PRIVACY.md.