Skip to content

shepsci/kaggle-skill / skills/kaggle

kaggle

Flagged

Unified Kaggle skill. Use when the user explicitly mentions Kaggle, kaggle.com, a Kaggle URL, Kaggle competitions, Kaggle datasets/models/notebooks, Kaggle forums/discussions/writeups, Kaggle benchmarks, hackathons hosted on Kaggle, Kaggle badges, or Kaggle account setup. Do not use for generic ML, GPU/TPU, notebook, dataset, benchmark, or data-science tasks unless the user clearly ties them to Kaggle.

FileKindSize
SKILL.mdskill md10.3 KB
modules/README.mdmarkdown2.3 KB
modules/badges/README.mdmarkdown1.6 KB
modules/badges/references/badge-catalog.mdmarkdown6.6 KB
modules/badges/scripts/badge_registry.pyscript8.5 KB
modules/badges/scripts/badge_tracker.pyscript4.1 KB
modules/badges/scripts/orchestrator.pyscript5.3 KB
modules/badges/scripts/phase_1_instant_api.pyscript24.0 KB
modules/badges/scripts/phase_2_competition.pyscript13.5 KB
modules/badges/scripts/phase_3_pipeline.pyscript11.7 KB
modules/badges/scripts/phase_4_browser.pyscript2.2 KB
modules/badges/scripts/phase_5_streaks.pyscript5.6 KB
modules/badges/scripts/templates/README_dataset.mdmarkdown573 B
modules/badges/scripts/templates/dataset-metadata.jsonconfig871 B
modules/badges/scripts/templates/kernel-metadata.jsonconfig412 B
modules/badges/scripts/templates/model-instance-metadata.jsonconfig253 B
modules/badges/scripts/templates/model-metadata.jsonconfig355 B
modules/badges/scripts/templates/python_notebook.ipynbother1.3 KB
modules/badges/scripts/templates/r_notebook.ipynbother1.1 KB
modules/badges/scripts/templates/submission_titanic.csvother2.8 KB
modules/badges/scripts/templates/utility_script.pyscript802 B
modules/badges/scripts/utils.pyscript3.9 KB
modules/benchmarks/README.mdmarkdown1.2 KB
modules/benchmarks/references/benchmark-endpoints.mdmarkdown1.6 KB
modules/benchmarks/references/benchmarks-cli.mdmarkdown4.4 KB
modules/competitions/README.mdmarkdown5.8 KB
modules/competitions/hackathons/README.mdmarkdown2.9 KB
modules/competitions/hackathons/references/episode-endpoints.mdmarkdown2.2 KB
modules/competitions/hackathons/references/hackathon-endpoints.mdmarkdown4.6 KB
modules/competitions/hackathons/scripts/fetch_writeup.pyexecutablescript10.5 KB
modules/competitions/hackathons/scripts/hackathon_overview.pyexecutablescript1.5 KB
modules/competitions/hackathons/scripts/list_writeups.pyexecutablescript9.9 KB
modules/competitions/references/competition-categories.mdmarkdown2.1 KB
modules/competitions/references/competition-operations.mdmarkdown5.7 KB
modules/competitions/references/competition-overview.mdmarkdown3.9 KB
modules/competitions/references/competition-research.mdmarkdown3.0 KB
modules/competitions/scripts/competition_brief.pyscript5.4 KB
modules/competitions/scripts/competition_details.pyscript8.2 KB
modules/competitions/scripts/competition_download.pyscript5.1 KB
modules/competitions/scripts/competition_episodes.pyscript9.2 KB
modules/competitions/scripts/competition_leaderboard.pyscript12.3 KB
modules/competitions/scripts/competition_ledger.pyscript3.3 KB
modules/competitions/scripts/competition_pages.pyexecutablescript1.7 KB
modules/competitions/scripts/competition_status.pyscript9.0 KB
modules/competitions/scripts/competition_submit.pyscript8.9 KB
modules/competitions/scripts/competition_validate.pyscript14.2 KB
modules/competitions/scripts/competition_watch.pyscript5.9 KB
modules/competitions/scripts/list_competitions.pyscript13.3 KB
modules/datasets/README.mdmarkdown2.1 KB
modules/datasets/references/kagglehub-datasets.mdmarkdown2.6 KB
modules/datasets/scripts/dataset_download.pyscript4.1 KB
modules/datasets/scripts/dataset_publish.pyscript5.5 KB
modules/discussions/README.mdmarkdown2.1 KB
modules/discussions/references/writeups.mdmarkdown5.8 KB
modules/discussions/scripts/forums.pyscript22.0 KB
modules/discussions/scripts/leaderboard_writeups.pyscript24.8 KB
modules/models/README.mdmarkdown2.6 KB
modules/models/references/kagglehub-models.mdmarkdown1.7 KB
modules/models/scripts/model_download.pyscript4.5 KB
modules/models/scripts/model_publish.pyscript8.7 KB
modules/notebooks/README.mdmarkdown2.6 KB
modules/notebooks/scripts/notebook_push.pyscript5.7 KB
modules/notebooks/scripts/notebook_run.pyscript2.8 KB
modules/notebooks/scripts/notebook_wait.pyscript3.7 KB
modules/references/README.mdmarkdown454 B
modules/references/cli-reference.mdmarkdown13.4 KB
modules/references/kaggle-knowledge.mdmarkdown7.6 KB
modules/references/mcp-reference.mdmarkdown18.9 KB
modules/setup/README.mdmarkdown3.0 KB
modules/setup/references/kaggle-setup.mdmarkdown6.7 KB
modules/setup/scripts/check_all_credentials.pyscript5.7 KB
modules/setup/scripts/doctor.pyscript10.2 KB
modules/setup/scripts/save_credentials.pyscript3.9 KB
scripts/kaggle_skill.pyscript11.5 KB
shared/__init__.pyscript0 B
shared/competition.pyscript20.0 KB
shared/credentials.pyscript9.6 KB
shared/hub.pyscript2.9 KB
shared/kaggle_cli.pyscript20.7 KB
shared/ledger.pyscript3.6 KB
shared/mcp_client.pyscript11.6 KB
shared/net.pyscript6.9 KB
shared/notebook.pyscript4.4 KB
shared/preflight.pyscript5.1 KB
shared/safe_extract.pyscript2.7 KB
shared/script.pyscript11.2 KB
shared/text.pyscript10.5 KB
shared/untrusted.pyscript7.6 KB

modules/competitions/scripts/competition_submit.py

View on GitHub
#!/usr/bin/env python3
"""Submit to a Kaggle competition: a dry run first, and a record of what was sent.

    competition_submit.py titanic ./submission.csv -m "baseline"           dry run
    competition_submit.py titanic ./submission.csv -m "baseline" --yes     submit
    competition_submit.py <competition> --notebook me/my-notebook --version 12 -m "v12" --yes

Without --yes nothing is submitted. The dry run prints what would be sent, how
many submissions are left today, and whether this exact file was sent before.
Check the file itself with the validate command.

A submission uses one of the day's slots, and on some competitions a
submission that errors still uses it. Get the user's go-ahead first.

A real submission adds one line to ./.kaggle-skill/ledger.jsonl: the time, the
file's size and SHA-256 (or the notebook and its version), the message, and
the score you expect if you give --expect. The watch command adds the score
Kaggle reports. The ledger is a local file; nothing in it is sent anywhere.
"""

from __future__ import annotations

import argparse
import sys
from pathlib import Path

SCRIPT_DIR = Path(__file__).resolve().parent
SKILL_ROOT = SCRIPT_DIR.parents[2]
sys.path.insert(0, str(SKILL_ROOT))
sys.path.insert(0, str(SCRIPT_DIR))

import competition_validate  # noqa: E402

from shared import (  # noqa: E402
    competition,
    credentials,
    kaggle_cli,
    ledger,
    mcp_client,
    script,
    text,
)

DEFAULT_MESSAGE = "Submitted with kaggle-skill"


def already_sent(slug: str, sha256: str) -> dict | None:
    """The ledger's record of this exact file for this competition, if any."""
    for row in reversed(ledger.submissions(slug)):
        if row.get("sha256") == sha256:
            return row
    return None


def file_check(slug: str, path: Path, sample: str | None) -> tuple[str, str]:
    """Run validate's checks for the dry run. Returns ``(detail line, state)``.

    The checks themselves are printed in a block: they quote column names and
    ids. The detail line is the skill's own words only.
    """
    checks, sample_name, why = competition_validate.check_against_sample(slug, path, sample)
    if checks is None:
        return f"not run: {why}. Add --sample PATH to check against a file", "not run"
    competition_validate.print_checks(slug, str(path), sample_name, checks)
    failed = sum(1 for passed, _ in checks if passed is False)
    warned = sum(1 for passed, _ in checks if passed is None)
    if failed:
        return f"{failed} of {len(checks)} FAILED (above): Kaggle may reject the file", "failed"
    if warned:
        return f"passed, with {warned} warning(s) to read above", "warned"
    return f"all {len(checks)} passed", "passed"


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(
        description="Submit to a Kaggle competition: a dry run first, and a record of what "
        "was sent.",
        epilog="Uses a daily submission slot. Needs the Kaggle CLI and a credential to submit.",
    )
    script.add_competition(parser, "file?", "message?")
    parser.add_argument("-m", "--message", dest="message_opt", help="What this submission is")
    parser.add_argument(
        "--notebook",
        metavar="OWNER/NAME",
        help="Code competition: submit this notebook's output instead of a local file",
    )
    parser.add_argument("--version", type=script.positive_int, help="With --notebook: its version")
    parser.add_argument(
        "--expect",
        type=float,
        metavar="SCORE",
        help="The score you expect, for the ledger. The watch command reports the gap",
    )
    parser.add_argument(
        "--sample",
        metavar="PATH",
        help="The sample submission to check the file against (default: found or downloaded)",
    )
    script.add_yes(parser)
    args = script.parse(parser, argv)
    slug, file_name, message = script.positionals(parser, args, "file?", "message?")
    message = args.message_opt or message or DEFAULT_MESSAGE

    details: list[tuple[str, str]] = [("competition", slug)]
    record: dict = {"event": "submit", "competition": slug, "message": message}
    if args.notebook:
        if not script.is_handle(args.notebook, 2):
            parser.error("--notebook takes owner/name")
        if not args.version:
            parser.error("--notebook needs --version: the notebook version to submit")
        file_name = file_name or "submission.csv"
        record.update(notebook=args.notebook, version=args.version, file=file_name)
        details += [
            ("notebook", f"{args.notebook}, version {args.version}"),
            ("output file", file_name),
        ]
        cli_args = ["--file", file_name, "--kernel", args.notebook, "--version", str(args.version)]
    else:
        if not file_name:
            parser.error("give the submission file, or --notebook with --version")
        path = Path(file_name)
        if not path.is_file():
            return script.fail(f"the submission file was not found: {file_name}", script.EXIT_USAGE)
        facts = ledger.file_facts(path)
        record.update(facts)
        details += [
            ("file", f"{file_name} ({text.human_size(facts['bytes'])})"),
            ("sha256", facts["sha256"][:16]),
        ]
        cli_args = ["--file", file_name]
    details.append(("message", message))
    if args.expect is not None:
        record["expected"] = args.expect
        details.append(("expected", f"{args.expect:g}"))

    credentials.load_configured_env_file()
    checked = ""
    if not args.notebook and Path(file_name).suffix.lower() == ".csv":
        # The same checks as validate, so one command shows the file and the plan.
        line, checked = file_check(slug, Path(file_name), args.sample)
        details.append(("file check", line))
        record["file_check"] = checked
    # What the competition takes. The call is public; a failure only skips the checks.
    facts_result = competition.fetch_facts(slug, token="")
    info = (
        competition.facts(slug, facts_result.data)
        if facts_result.ok and isinstance(facts_result.data, dict)
        else None
    )
    blockers: list[str] = []
    if info:
        if info["submissions_disabled"]:
            blockers.append("submissions to this competition are closed")
        if info["notebook_only"] and not args.notebook:
            blockers.append(
                "this is a code competition: it takes a notebook version "
                "(--notebook OWNER/NAME --version N), not a local file"
            )
        deadline = text.parse_time(info.get("deadline"))
        if deadline is not None and deadline < text.now_utc():
            script.warn(f"the deadline passed: {text.when(info['deadline'])}")

    limits = competition.submission_limits(slug) if credentials.resolve() else None
    if limits is not None:
        cost = f"1 of the {limits['numAllowedNow']} submissions left today"
        if int(limits["numAllowedNow"]) <= 0:
            script.warn("Kaggle reports no submissions left today")
    elif info and info.get("max_daily_submissions"):
        cost = f"1 of {info['max_daily_submissions']} submissions a day"
    else:
        cost = "one daily submission slot"

    earlier = already_sent(slug, record["sha256"]) if "sha256" in record else None
    if earlier:
        script.warn(
            f"this exact file was already submitted on {earlier.get('time')} "
            f"(score: {earlier.get('public_score') or 'not recorded'})"
        )
    for blocker in blockers:
        print(f"error: {blocker}", file=sys.stderr)

    gate = script.write_gate(
        args.yes,
        action="submit to a competition",
        details=details,
        cost=cost,
        blocked=bool(blockers),
    )
    if gate is not None:
        if blockers:
            return script.EXIT_USAGE
        return gate

    if not kaggle_cli.installed():
        return script.missing_package("kaggle", "submitting")
    if credentials.resolve() is None:
        return script.no_credential("submitting")

    # --message=VALUE keeps a message that starts with "-" from being read as an option.
    status = kaggle_cli.run_wrapped(
        ["competitions", "submit", slug, *cli_args, f"--message={message}"],
        tool="competitions.submit",
    )
    if status != 0:
        return status

    # The newest submission is the one just made. Its id ties the score to this record.
    rows, _ = competition.fetch_submissions(slug, mcp_client.resolve_token(), limit=1)
    if rows:
        record["ref"] = rows[0]["ref"]
    ref = f" as submission {record['ref']}" if "ref" in record else ""
    try:
        print(f"Submitted{ref}. Recorded in {ledger.append(record)}.")
    except OSError as exc:
        # The submission went through; only the local record is missing.
        print(f"Submitted{ref}.")
        script.warn(f"the submission was not recorded in the ledger: {exc}")
    print(f"Wait for the score with: watch {slug}")
    return script.EXIT_OK


if __name__ == "__main__":
    sys.exit(main())
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall