kaggle-skills

A toolkit of Claude Code skills, hooks, and scripts that compound your Kaggle knowledge across competitions — designed so every session starts smarter than the last.

What it does

• Skills — slash commands Claude invokes automatically: scaffold a competition, submit safely, run local eval, capture learnings, and more.
• Hooks — auto-inject your accumulated learnings at session start; nudge you to log experiments and review submissions.
• Learning system — a file-based memory that grows with you. Every scar, every validated pattern lives in .learnings/. Future sessions read it automatically.
• Scripts — kln CLI for humans to search, add, and archive learnings from the terminal.

Prerequisites

Tool	Version	Install
Claude Code	latest	npm i -g @anthropic-ai/claude-code
kaggle CLI	≥ 2.0.1	uv tool install --python 3.11 kaggle
uv	latest	`curl -Lsf https://astral.sh/uv/install.sh
Python	≥ 3.11	via uv or system
git	any	system

Kaggle auth: put your API token (a single KGAT_… line) in ~/.kaggle/access_token with mode 600.

chmod 600 ~/.kaggle/access_token

Quick install — let Claude Code do it

Paste this prompt directly into Claude Code. It will clone the toolkit, ask whether you’re adding it to an existing workspace or starting fresh, and set everything up for you.

Set up my Kaggle workspace with kaggle-skills.

Clone the toolkit:
  git clone --depth 1 https://github.com/subarnasaikia/kaggle-skills.git /tmp/kaggle-skills

Then ask me ONE question before doing anything else:
  "Do you have an existing Kaggle workspace directory, or do you want to create a new one?"

  → Existing workspace: ask for the path, then run:
      bash /tmp/kaggle-skills/install.sh <my-path>

  → New workspace: ask where to create it (suggest ~/kaggle as default), then run:
      bash /tmp/kaggle-skills/install.sh <chosen-path>

After the install finishes:
  1. Tell me where my workspace lives and confirm which files were copied.
  2. Add a kaggle-skills section to my global ~/.claude/CLAUDE.md so all future
     sessions know the skills are available:

     ## kaggle-skills
     Workspace: <workspace-path>
     Repo: https://github.com/subarnasaikia/kaggle-skills
     Skills: new-competition, submit-competition, run-local-eval, improve-agent,
             debug-agent, leaderboard-check, eda-audit, ensemble-blend,
             log-experiment, capture-learning, recall-learnings,
             preflight-consult, post-submission-review, retrospect-session.
     Ritual: recall-learnings before any non-trivial move. capture-learning when
             surprised. retrospect-session before closing the laptop.

  3. Ask me: "Do you want to open Claude Code in the workspace now?"

Manual install (terminal)

# HTTPS (no SSH config needed)
git clone --depth 1 https://github.com/subarnasaikia/kaggle-skills.git /tmp/kaggle-skills

# Fresh workspace
bash /tmp/kaggle-skills/install.sh ~/kaggle

# OR — add to an existing workspace
bash /tmp/kaggle-skills/install.sh /path/to/your/existing/kaggle-workspace

The install script will:

1. Verify prerequisites (kaggle CLI, uv, python3, git).
2. Copy .claude/, scripts/, shared/, and template files.
3. Make all scripts executable.
4. Skip files that already exist (safe to re-run).
5. Print what to do next.

Workspace layout after install

your-kaggle-workspace/
├── CLAUDE.md                  # Global rules (loaded by Claude Code automatically)
├── LEARNINGS.md               # Digest of top learnings (auto-updated)
├── .claude/
│   ├── settings.json          # Permissions + hook wiring
│   ├── hooks/
│   │   ├── session-start.sh   # Injects learnings at every session start
│   │   ├── post-kaggle-action.sh  # Post-submit nudge
│   │   └── stop.sh            # End-of-session retro nudge
│   └── skills/                # One folder per skill
├── .learnings/                # One file per learning (grows over time)
├── scripts/
│   └── kln                    # Human CLI for learnings
└── competitions/
    └── <slug>/                # One folder per competition

Skills reference

Core workflow

Skill	What it does
new-competition	Scaffold a full competition folder with README, LOG, gitignore, venv prompt
submit-competition	Pre-flight validate + safe submit with quota check and LOG update
leaderboard-check	Pull leaderboard, compare your best score, show gap to medals
post-submission-review	Poll score, diff vs best, update LOG, capture learning if notable

Agents / simulation

Skill	What it does
run-local-eval	Run kaggle-environments matches, report win rate and time budget
improve-agent	Systematic improvement loop: diagnose → hypothesize → implement → verify
debug-agent	Step through a replay, find the failing turn, print diagnostics

Tabular / ML

Skill	What it does
eda-audit	Structured EDA: target dist, missing values, leakage scan, train/test shift
ensemble-blend	Weighted average or rank average across multiple submission CSVs

Learning system

Skill	What it does
log-experiment	Write hypothesis before running; fill outcome after
capture-learning	Write a durable .learnings/L-*.md learning file
recall-learnings	Surface prior learnings relevant to the current task
preflight-consult	Sanity-check a plan against prior learnings before committing time
retrospect-session	Extract 0-3 learnings at session end, refresh LEARNINGS.md digest

The learning system

session starts → hooks inject top learnings into context
     ↓
Claude does work (plans, experiments, submits)
     ↓
surprise? → capture-learning   experiment? → log-experiment
submit?   → post-submission-review
     ↓
session ends → retrospect-session extracts durable lessons
     ↓
next session starts smarter

Competition templates

competitions/template/ — a fully scaffolded reference folder showing the expected structure and file formats. Use it as a reference when contributing or when new-competition.sh doesn’t fit your needs.

.claude/templates/ — per-competition-type CLAUDE.md starters. Copy the one that matches your competition into competitions/<slug>/CLAUDE.md:

File	Competition type
CLAUDE.tabular.md	Tabular (LightGBM, XGBoost, feature engineering)
CLAUDE.simulation.md	Agent / simulation (kaggle-environments)
CLAUDE.nlp.md	NLP (text classification, generation, ranking)
CLAUDE.cv.md	Computer vision (classification, detection, segmentation)
CLAUDE.notebook.md	Code / notebook competitions (run on Kaggle’s servers)

Shared utilities

Script	What it does
shared/utils/submit.py	Python wrapper around kaggle competitions submit — pre-flight validates file, archives it with a timestamp, appends a row to submissions/LOG.md, then calls the CLI. Usable by both humans and Claude.

# standard usage
python3 shared/utils/submit.py titanic submission.csv "lgbm baseline"

# skip the interactive y/N prompt (e.g. in scripts)
python3 shared/utils/submit.py titanic submission.csv "lgbm baseline" --yes

The script must be run from the workspace root (where competitions/ lives). It reads competitions/<slug>/data/sample_submission.csv for the header check if present.

Contributing

See CONTRIBUTING.md. New skills, bug fixes, and competition-type-specific patterns are all welcome.