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 s