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_episodes.py

View on GitHub
#!/usr/bin/env python3
"""The games a simulation submission has played, and one game's replay or log.

    competition_episodes.py 56699264                      list the submission's episodes
    competition_episodes.py --replay 117015562            save a replay
    competition_episodes.py --logs 117015562 --agent 0    save your agent's log, print its end

The list reads `list_submission_episodes` on the Kaggle MCP server and needs a
credential. Replays and logs are files: they are downloaded with the Kaggle
CLI into --out (default ./downloads/episodes) and are not printed in full.
A log is available only for your own agent.

Team names are written by participants, so the list is printed inside an
untrusted-content block.
"""

from __future__ import annotations

import argparse
import json
import sys
from collections import Counter
from pathlib import Path

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

from shared import credentials, kaggle_cli, mcp_client, script, text, untrusted  # noqa: E402

SOURCE = "kaggle-mcp"
TOOL = "list_submission_episodes"
DEFAULT_OUT = "downloads/episodes"


def episode_row(episode: dict, submission_id: int) -> dict:
    """One episode from the point of view of ``submission_id``."""
    agents = [a for a in episode.get("agents") or [] if isinstance(a, dict)]
    mine = next((a for a in agents if a.get("submission_id") == submission_id), None)
    others = [a for a in agents if a is not mine]
    kind = str(episode.get("type") or "").replace("EPISODE_TYPE_", "").lower()
    return {
        "id": episode.get("id"),
        "type": kind,
        "state": str(episode.get("state") or "").lower(),
        "ended": episode.get("end_time"),
        "agent_index": int(mine.get("index") or 0) if mine else None,
        "reward": mine.get("reward") if mine else None,
        "opponents": [
            {"team": a.get("team_name") or "", "reward": a.get("reward")} for a in others
        ],
    }


def summarize(rows: list[dict]) -> dict:
    rewards = [r["reward"] for r in rows if isinstance(r["reward"], (int, float))]
    ahead = 0
    compared = 0
    for row in rows:
        theirs = [o["reward"] for o in row["opponents"] if isinstance(o["reward"], (int, float))]
        if isinstance(row["reward"], (int, float)) and theirs:
            compared += 1
            ahead += row["reward"] > max(theirs)
    return {
        "episodes": len(rows),
        "by_type": dict(Counter(row["type"] for row in rows)),
        "by_state": dict(Counter(row["state"] for row in rows)),
        "mean_reward": sum(rewards) / len(rewards) if rewards else None,
        "higher_reward_than_every_opponent": ahead,
        "compared": compared,
    }


def list_episodes(submission_id: int, args: argparse.Namespace) -> int:
    token = mcp_client.resolve_token()
    if not token:
        return script.no_credential("the episode list")
    result = mcp_client.request(TOOL, {"submissionId": submission_id}, token=token, timeout=120)
    if not result.ok or not isinstance(result.data, dict):
        return result.fail(submission=submission_id)
    episodes = [e for e in result.data.get("episodes") or [] if isinstance(e, dict)]
    rows = [episode_row(e, submission_id) for e in episodes]
    rows.sort(key=lambda r: str(r["ended"] or ""), reverse=True)
    summary = summarize(rows)
    shown = rows[: args.limit]

    attrs = {"source": SOURCE, "tool": TOOL, "submission": submission_id}
    if args.json:
        untrusted.emit_json({"summary": summary, "episodes": shown}, **attrs)
        return script.EXIT_OK
    with untrusted.Block(**attrs) as block:
        kinds = ", ".join(f"{n} {kind}" for kind, n in sorted(summary["by_type"].items()))
        states = ", ".join(f"{n} {state}" for state, n in sorted(summary["by_state"].items()))
        block.write(f"{len(rows)} episodes of submission {submission_id}: {kinds}; {states}")
        if summary["mean_reward"] is not None:
            block.write(
                f"  mean reward {summary['mean_reward']:.6g}; higher than every opponent in "
                f"{summary['higher_reward_than_every_opponent']} of {summary['compared']}"
            )
        if shown:
            block.write(f"  latest {len(shown)}:")
            block.write(
                f"  {'episode':>10}  {'ended (UTC)':<16}  {'seat':>4}  {'reward':>10}  opponents"
            )
        for row in shown:
            moment = text.parse_time(row["ended"])
            ended = moment.strftime("%Y-%m-%d %H:%M") if moment else "-"
            seat = "-" if row["agent_index"] is None else str(row["agent_index"])
            rivals = "; ".join(
                f"{text.shorten(o['team'], 30)} {o['reward']}" for o in row["opponents"]
            )
            block.write(
                f"  {row['id']:>10}  {ended:<16}  {seat:>4}  {str(row['reward']):>10}  {rivals}"
            )
    if len(rows) > len(shown):
        print(f"Showing {len(shown)} of {len(rows)}. Add --limit {len(rows)} for all of them.")
    if shown:
        first = shown[0]
        seat = first["agent_index"] if first["agent_index"] is not None else 0
        print(
            f"Save a game with --replay EPISODE, or your agent's log with --logs EPISODE "
            f"--agent SEAT (for the latest: --logs {first['id']} --agent {seat})."
        )
    return script.EXIT_OK


def download(kind: str, episode: int, agent: int, out: Path, tail: int) -> int:
    """Download a replay or a log with the Kaggle CLI and describe the file."""
    if not kaggle_cli.installed():
        return script.missing_package("kaggle", "downloading a replay or a log")
    if credentials.resolve() is None:
        return script.no_credential("downloading a replay or a log")
    out.mkdir(parents=True, exist_ok=True)
    if kind == "replay":
        cli_args = ["competitions", "replay", str(episode), "--path", str(out), "--quiet"]
        target = out / f"episode-{episode}-replay.json"
    else:
        cli_args = ["competitions", "logs", str(episode), str(agent), "--path", str(out)]
        cli_args.append("--quiet")
        target = out / f"episode-{episode}-agent-{agent}-logs.json"
    result = kaggle_cli.run(cli_args, timeout=600)
    if result.returncode != 0 or not target.is_file():
        print(f"error: the {kind} could not be downloaded", file=sys.stderr)
        if (result.stdout + result.stderr).strip():
            untrusted.emit_text(
                result.stdout + result.stderr,
                source="kaggle-cli",
                tool=f"competitions.{kind}",
                stream="stderr",
                file=sys.stderr,
            )
        return kaggle_cli.exit_code(result) or script.EXIT_FAILED

    size = target.stat().st_size
    print(f"Saved {target} ({text.human_size(size)}).")
    content = target.read_text(encoding="utf-8", errors="replace")
    if kind == "replay":
        try:
            data = json.loads(content)
        except ValueError:
            return script.EXIT_OK
        if isinstance(data, dict):
            steps = data.get("steps")
            facts = [f"{len(steps):,} steps"] if isinstance(steps, list) else []
            facts.append("keys: " + ", ".join(sorted(str(k) for k in data)[:12]))
            # Key names come from the file, which Kaggle built from the agents' moves.
            untrusted.emit_text("; ".join(facts), source="kaggle-cli", tool="competitions.replay")
    elif tail:
        lines = content.splitlines() or [content]
        shown = "\n".join(lines[-tail:])[-4000:]
        # An agent's log holds whatever the agent printed.
        untrusted.emit_text(shown, source="kaggle-cli", tool="competitions.logs", episode=episode)
    return script.EXIT_OK


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(
        description="The games a simulation submission has played, and one game's replay or log.",
        epilog="Needs a Kaggle credential. Replays and logs also need the Kaggle CLI.",
    )
    parser.add_argument("submission", nargs="?", type=int, help="Submission id: list its episodes")
    parser.add_argument("--replay", type=int, metavar="EPISODE", help="Save this episode's replay")
    parser.add_argument("--logs", type=int, metavar="EPISODE", help="Save your agent's log")
    parser.add_argument(
        "--agent",
        type=int,
        default=0,
        metavar="SEAT",
        help="With --logs: your agent's seat in that game, the list's seat column (default: 0)",
    )
    parser.add_argument(
        "--out", default=DEFAULT_OUT, metavar="DIR", help=f"Where to save (default: {DEFAULT_OUT})"
    )
    parser.add_argument(
        "--tail", type=int, default=40, metavar="N", help="With --logs: print the last N lines"
    )
    script.add_limit(parser, 10, "episodes")
    script.add_json(parser)
    args = parser.parse_args(argv)

    chosen = [x for x in (args.submission, args.replay, args.logs) if x is not None]
    if len(chosen) != 1:
        parser.error("give a submission id, or --replay EPISODE, or --logs EPISODE")

    credentials.load_configured_env_file()
    if args.replay is not None:
        return download("replay", args.replay, 0, Path(args.out), 0)
    if args.logs is not None:
        return download("logs", args.logs, args.agent, Path(args.out), args.tail)
    return list_episodes(args.submission, args)


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