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

shared/text.py

View on GitHub
"""Turn Kaggle content into text that is cheap to read.

Kaggle stores a competition page as Markdown or, for older competitions, as
HTML. ``to_text`` leaves Markdown as it is, apart from ``<br>`` line breaks,
and turns an HTML page into Markdown-like text: headings, lists, links, code
and tables survive, the tags do not.

Nothing here makes text safe to follow. The result is still written by a
competition host or a participant, and callers print it inside an
untrusted-content block.
"""

from __future__ import annotations

import re
from datetime import datetime, timedelta, timezone
from html.parser import HTMLParser

KAGGLE_BASE = "https://www.kaggle.com"

_BLOCK_CLOSE_RE = re.compile(r"</(p|div|h[1-6]|ul|ol|li|table|tr|td|th|pre)\s*>", re.IGNORECASE)
_MARKDOWN_LINE_RE = re.compile(r"^(#{1,6}\s?\S|[-*+] \S|\d+\. \S)", re.MULTILINE)
_BR_RE = re.compile(r"[ \t]*<br\s*/?>[ \t]*\n?", re.IGNORECASE)
_BLANK_LINES_RE = re.compile(r"\n{3,}")
_SPACE_RE = re.compile(r"[ \t\r\f\v\n]+")

_SKIPPED = {"script", "style", "noscript", "template", "head", "title", "svg", "math"}
_BLOCKS = {
    "p",
    "div",
    "section",
    "article",
    "header",
    "footer",
    "main",
    "aside",
    "figure",
    "figcaption",
    "blockquote",
    "ul",
    "ol",
    "table",
    "details",
    "summary",
    "form",
    "dl",
    "dt",
    "dd",
}
_HEADINGS = {"h1": 1, "h2": 2, "h3": 3, "h4": 4, "h5": 5, "h6": 6}
_LINK_SCHEMES = ("http://", "https://", "mailto:")


def is_html(content: str) -> bool:
    """True when the content is an HTML page and not Markdown with a few tags in it."""
    if len(_BLOCK_CLOSE_RE.findall(content)) < 2:
        return False
    return content.lstrip().startswith("<") or not _MARKDOWN_LINE_RE.search(content)


class _Converter(HTMLParser):
    def __init__(self, base_url: str) -> None:
        super().__init__(convert_charrefs=True)
        self.base_url = base_url
        self.out: list[str] = []
        self.skip_depth = 0
        self.pre_depth = 0
        self.lists: list[list] = []  # [kind, next number]
        self.links: list[tuple[int, str]] = []

    # -- output helpers ------------------------------------------------------

    def _emit(self, text: str) -> None:
        if text:
            self.out.append(text)

    def _break(self, lines: int = 2) -> None:
        self.out.append("\n" * lines)

    def _mark(self, marker: str) -> None:
        """Emphasis markers, except inside a code block, where they would be shown."""
        if not self.pre_depth:
            self.out.append(marker)

    def _href(self, attrs: list[tuple[str, str | None]]) -> str:
        href = (dict(attrs).get("href") or "").strip()
        if href.startswith("/") and not href.startswith("//"):
            return self.base_url + href
        return href if href.lower().startswith(_LINK_SCHEMES) else ""

    # -- parser callbacks ----------------------------------------------------

    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
        if tag in _SKIPPED:
            self.skip_depth += 1
            return
        if self.skip_depth:
            return
        if tag in _HEADINGS:
            self._break()
            self._emit("#" * _HEADINGS[tag] + " ")
        elif tag in _BLOCKS:
            self._break()
            if tag in ("ul", "ol"):
                self.lists.append([tag, 1])
        elif tag == "br":
            self._break(1)
        elif tag == "hr":
            self._break()
            self._emit("---")
            self._break()
        elif tag == "li":
            self._break(1)
            indent = "  " * max(len(self.lists) - 1, 0)
            if self.lists and self.lists[-1][0] == "ol":
                self._emit(f"{indent}{self.lists[-1][1]}. ")
                self.lists[-1][1] += 1
            else:
                self._emit(f"{indent}- ")
        elif tag == "pre":
            self.pre_depth += 1
            self._break()
            self._emit("```\n")
        elif tag == "code":
            if not self.pre_depth:
                self._emit("`")
        elif tag in ("strong", "b"):
            self._mark("**")
        elif tag in ("em", "i"):
            self._mark("*")
        elif tag == "a":
            self.links.append((len(self.out), self._href(attrs)))
        elif tag == "img":
            alt = (dict(attrs).get("alt") or "").strip()
            if alt:
                self._emit(f"[image: {alt}]")
        elif tag == "tr":
            self._break(1)
            self._emit("| ")

    def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
        self.handle_starttag(tag, attrs)
        if tag in _SKIPPED:
            self.handle_endtag(tag)

    def handle_endtag(self, tag: str) -> None:
        if tag in _SKIPPED:
            self.skip_depth = max(self.skip_depth - 1, 0)
            return
        if self.skip_depth:
            return
        if tag in _HEADINGS:
            self._break()
        elif tag in _BLOCKS:
            if tag in ("ul", "ol") and self.lists:
                self.lists.pop()
            self._break()
        elif tag == "pre":
            self.pre_depth = max(self.pre_depth - 1, 0)
            self._emit("\n```")
            self._break()
        elif tag == "code":
            if not self.pre_depth:
                self._emit("`")
        elif tag in ("strong", "b"):
            self._mark("**")
        elif tag in ("em", "i"):
            self._mark("*")
        elif tag == "a" and self.links:
            start, href = self.links.pop()
            label = "".join(self.out[start:]).strip()
            del self.out[start:]
            if href and label and label != href:
                self._emit(f"[{label}]({href})")
            else:
                self._emit(label or href)
        elif tag in ("td", "th"):
            self._emit(" | ")

    def handle_data(self, data: str) -> None:
        if self.skip_depth:
            return
        if self.pre_depth:
            self._emit(data)
            return
        text = _SPACE_RE.sub(" ", data)
        if text == " " and (not self.out or self.out[-1].endswith(("\n", " "))):
            return
        if self.out and self.out[-1].endswith("\n"):
            text = text.lstrip(" ")
        self._emit(text)


def _tidy(text: str) -> str:
    lines = [line.rstrip() for line in text.replace("\r\n", "\n").replace("\r", "\n").split("\n")]
    return _BLANK_LINES_RE.sub("\n\n", "\n".join(lines)).strip()


def html_to_text(content: str, base_url: str = KAGGLE_BASE) -> str:
    """Convert an HTML fragment to Markdown-like text."""
    converter = _Converter(base_url)
    converter.feed(content)
    converter.close()
    return _tidy("".join(converter.out))


def to_text(content: str, base_url: str = KAGGLE_BASE) -> str:
    """Readable text for a page that may be HTML or Markdown."""
    if not content:
        return ""
    if is_html(content):
        return html_to_text(content, base_url)
    return _tidy(_BR_RE.sub("\n", content))


def collapse(text: str) -> str:
    """The text on one line, with single spaces."""
    return _SPACE_RE.sub(" ", text or "").strip()


_IMAGE_RE = re.compile(r"!\[[^\]]*\]\([^)]*\)")
_LINK_RE = re.compile(r"\[([^\]]+)\]\([^)]*\)")
_EMPHASIS_RE = re.compile(r"(\*\*|__|`)")


def plain(text: str) -> str:
    """Markdown read as plain words: images dropped, links as their text, no ** or `."""
    text = _IMAGE_RE.sub("", text)
    text = _LINK_RE.sub(r"\1", text)
    return _EMPHASIS_RE.sub("", text)


def shorten(text: str, limit: int) -> str:
    """Cut ``text`` to ``limit`` characters, ending with an ellipsis when cut."""
    text = text or ""
    if limit <= 0 or len(text) <= limit:
        return text
    return text[: max(limit - 1, 0)].rstrip() + "…"


def human_size(size: int | float | str | None) -> str:
    """A byte count as ``512 B``, ``3.2 KB``, ``1.5 GB``."""
    try:
        value = float(size)  # type: ignore[arg-type]
    except (TypeError, ValueError):
        return "?"
    for unit in ("B", "KB", "MB", "GB", "TB"):
        if abs(value) < 1000 or unit == "TB":
            return f"{value:.0f} {unit}" if unit == "B" else f"{value:.1f} {unit}"
        value /= 1000
    return "?"


def absolute_url(url: str | None, base_url: str = KAGGLE_BASE) -> str:
    """A Kaggle URL with its host: ``/competitions/x`` becomes ``https://www.kaggle.com/...``."""
    url = (url or "").strip()
    if not url or url.lower().startswith(("http://", "https://")):
        return url
    return base_url + (url if url.startswith("/") else "/" + url)


# -- time -------------------------------------------------------------------

_FRACTION_RE = re.compile(r"\.(\d+)")


def parse_time(value: object) -> datetime | None:
    """Parse the timestamps Kaggle returns: ``2026-10-22T23:59:00Z``, with or
    without fractional seconds (up to nine digits) and with or without a zone.
    A value without a zone is taken as UTC. Returns None for anything else."""
    if isinstance(value, datetime):
        return value if value.tzinfo else value.replace(tzinfo=timezone.utc)
    if not isinstance(value, str) or not value.strip():
        return None
    text = value.strip().replace("Z", "+00:00")
    # datetime.fromisoformat accepts at most six fractional digits.
    text = _FRACTION_RE.sub(lambda m: "." + m.group(1)[:6].ljust(6, "0"), text, count=1)
    try:
        parsed = datetime.fromisoformat(text)
    except ValueError:
        return None
    return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)


def now_utc() -> datetime:
    return datetime.now(timezone.utc)


def span(delta: timedelta) -> str:
    """A duration in its two largest units: ``20 d 3 h``, ``3 h 12 min``, ``45 s``."""
    seconds = int(abs(delta.total_seconds()))
    days, rest = divmod(seconds, 86400)
    hours, rest = divmod(rest, 3600)
    minutes, secs = divmod(rest, 60)
    if days:
        return f"{days} d {hours} h"
    if hours:
        return f"{hours} h {minutes} min"
    if minutes:
        return f"{minutes} min"
    return f"{secs} s"


def when(value: object, now: datetime | None = None) -> str:
    """A timestamp with its distance from now: ``2026-10-22 23:59 UTC (in 20 d 3 h)``."""
    moment = parse_time(value)
    if moment is None:
        return str(value) if value else "not given"
    now = now or now_utc()
    stamp = moment.astimezone(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
    distance = span(moment - now)
    return f"{stamp} (in {distance})" if moment > now else f"{stamp} ({distance} ago)"


def day(value: object) -> str:
    """The date part of a timestamp, or ``-``."""
    moment = parse_time(value)
    return moment.astimezone(timezone.utc).strftime("%Y-%m-%d") if moment else "-"
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