name: agentic-kaggle-skill description: Kaggle-first end-to-end competition workflow for scored submissions. Use when Codex must run Kaggle or competitive ML workflows through scored submission, including code competitions, validation, metrics, policy-safe public notebook/discussion intel, tabular/text/image modeling, tuning, ensembling/stacking, proactive multi-notebook architectures, producer notebooks that train models and export private Kaggle artifact datasets, downstream consumer notebooks, Kaggle GPU offload, kagglehub access, hidden-test debugging, and public score retrieval.

Agentic Kaggle Skill

Operating Loop

Treat every competition as a validation problem first and a modeling problem second. The default target platform is Kaggle, so prefer Kaggle-native notebooks/scripts, datasets, model artifacts, competition submissions, and score receipts. For code competitions, assume the final notebook/kernel will be rerun by Kaggle against hidden data unless the competition docs prove otherwise.

1. Read the competition page, classify the submission mode as classic file submission or code/notebook scoring, then inspect the rules, data-use terms, sharing policy, data dictionary, metric, submission format, train/test construction hints, and leakage warnings.
2. If live competition intelligence tools are available, inspect top public open notebook solutions and relevant discussion activity before major architecture choices; treat them as clues, not authority.
3. Identify the task type: binary, multiclass, multilabel, regression, ranking, image, segmentation, text, time series, grouped entities, or a hybrid.
4. Design folds before feature engineering or modeling. Prefer a fold column saved into the training data so every experiment uses the same comparison surface.
5. Build the simplest metric-correct baseline and produce out-of-fold (OOF) predictions plus a valid submission.
6. Proactively plan a stronger architecture once the baseline is trustworthy: diverse model families, feature/embedding producers, augmentation/pseudo-label/distillation stages, calibration/postprocessing, and an ensemble or stacker.
7. Iterate with validation gates: test one meaningful change at a time when possible, but launch several independent producer notebooks in parallel when they create diverse artifacts that can be compared by OOF score or ensemble diversity.
8. Offload heavy training, inference, embedding generation, image/text experiments, or memory-risky jobs to Kaggle notebooks/scripts when local compute may OOM or take too long.
9. For sophisticated architectures, split work into a small Kaggle pipeline: run several independent producer notebooks/scripts first, save each useful producer output as a private Kaggle dataset, then run one consumer notebook/script that attaches those datasets and creates the final OOF/test/submission outputs. When a producer trains a model, its checkpoint, tokenizer/config, fold metadata, OOF/test predictions, and manifest should be exported as a Kaggle dataset; downstream notebooks load the model from /kaggle/input/....
10. Submit the final submission-producing artifact to Kaggle for scoring and retrieve the resulting submission status/score.
11. If Kaggle returns a code-competition error or vague scoring failure, enter the debugging loop: retrieve available logs, classify likely failure mode, patch defensively, rerun the final kernel, resubmit, and repeat until scored or concretely blocked.
12. Track local CV, remote Kaggle run status, Kaggle submission score, public LB, private-risk notes, seed, code version, data version, and artifact paths for every run.
13. Ensemble only with OOF predictions generated without in-fold leakage.

Resource Map

• Read references/method-map.md for the neutral workflow map behind the skill.
• Read references/information-sharing-policy.md before publishing competition code, notebooks, datasets, models, artifacts, or reports outside the active team or workspace.
• Read references/competition-intel.md when a Kaggle competition slug, URL, title, public leaderboard context, open solutions, or discussion activity may inform the approach.
• Read references/cross-validation-and-metrics.md when choosing folds, metrics, thresholds, or leakage checks.
• Read references/tabular-workflow.md for categorical variables, feature engineering, selection, and hyperparameter tuning.
• Read references/image-text-workflow.md for image, segmentation, and NLP competition approaches.
• Read references/kaggle-code-competition-pipeline.md when the target is a Kaggle code competition, hidden rerun, final notebook scoring flow, or model artifact handoff between producer and consumer notebooks.
• Read references/advanced-notebook-architecture.md when a stronger solution may need multiple model families, staged feature/embedding/model producers, pseudo-labeling, distillation, postprocessing, blending, stacking, or parallel Kaggle GPU notebooks.
• Read references/kaggle-offload.md when local runs are heavy, GPU is useful, Kaggle data access is needed, or remote notebook results must be collected.
• Read references/kaggle-pipeline-datasets.md when using multiple Kaggle notebooks, intermediate datasets, notebook output sources, or kagglehub.
• Read references/submission-endgame.md before stopping work; this skill is not done until Kaggle scoring has been attempted and the result has been collected or a concrete blocker is documented.
• Read references/code-competition-debugging.md when a Kaggle code competition submission fails, times out, OOMs, produces no score, or reports a vague hidden-run/scoring error.
• Read references/ensembling-and-reproducibility.md for project layout, OOF artifacts, stacking, blending, and repeatability.
• Read references/research/ or examples/ only when the user asks for historical case studies, Hermes-era patterns, or concrete competition lessons from this repository.
• Run scripts/scaffold_competition.py to create a competition workspace.
• Run scripts/make_folds.py to add a fold column to a training CSV.
• Run scripts/prepare_kaggle_kernel.py to create a Kaggle kernel folder with metadata and retrievable experiment logs.
• Run scripts/prepare_kaggle_dataset.py to create metadata and commands for versioned intermediate artifact datasets.

Default Kaggle Procedure

Start with the metric and validation:

• Reproduce the competition metric locally, including clipping, transforms, averaging mode, thresholds, and sample weights.
• Check whether the competition allows public code, external data, pretrained weights, generated artifacts, and public repositories before sharing anything outside the team.
• Classify the Kaggle submission path early. If it is a code competition or notebook-scored workflow, design the final consumer notebook as the scoring artifact from the start.
• Use kaggle-competition-intel MCP tools when available: top_open_solutions for score-ranked plus latest high-vote notebooks, and competition_discussions for top-voted plus recently active discussion topics before choosing expensive baselines.
• Choose folds to match the hidden test distribution. Use stratification for classification, binned stratification for regression, group splits for repeated entities, time-aware splits for temporal data, and multilabel-aware splits when label co-occurrence matters.
• Save OOF predictions for every model. OOF files are the currency for error analysis, threshold tuning, blending, and stacking.
• Compare mean fold score and fold variance, not only the best fold.
• Treat a public LB jump that disagrees with CV as a validation question before treating it as a modeling victory.

Then build baselines in this order:

1. Metric-only or constant baseline to verify scoring and submission format.
2. Fast classical baseline: LightGBM/CatBoost/XGBoost for tabular, TF-IDF plus linear model for text, pretrained backbone for images.
3. Strong baseline with stable folds, clean artifacts, and OOF predictions.
4. Feature/model experiments with run logs and one primary metric.
5. Ensembling or stacking after several diverse, individually validated models exist.

Do not wait for the user to explicitly ask for sophistication when the competition warrants it. After a stable baseline, propose and execute a stronger staged architecture if public solutions, discussion intel, data modality, metric pressure, or CV plateau suggests that a single notebook/model will underperform. Keep the architecture gated by OOF evidence, artifact manifests, and final Kaggle scoring.

When a run is likely to exceed local RAM/VRAM, require a GPU/TPU, or needs Kaggle-only data mounts, prepare a Kaggle kernel run instead of forcing it locally. The remote run must emit experiment_log.json, metrics.jsonl, and an artifact manifest so results can be retrieved and interpreted after kaggle kernels output.

When the solution has multiple heavy stages, keep the remote graph shallow and inspectable:

• Use fewer than five independent producer notebooks/scripts per wave.
• Give each producer a single responsibility such as feature generation, embedding extraction, fold training, checkpoint training, model distillation, or inference.
• For code competitions, prefer producer notebooks that train models/checkpoints and export them as private Kaggle datasets; the final consumer should attach those datasets, load models from /kaggle/input/..., and perform hidden-test-safe inference.
• Save producer notebook outputs as versioned private Kaggle datasets for durable reuse and as stable inputs to downstream notebooks; use direct kernel_sources only for short-lived chains where durability/versioning is unnecessary.
• Run one final consumer notebook/script that attaches the produced datasets, reads their artifacts, writes the final OOF, test predictions, blend/stack report, and submission, then submit that final artifact/kernel to Kaggle for scoring.
• Use kagglehub inside Python when it is more convenient to download datasets, competition files, notebook outputs, or upload dataset versions programmatically.

Definition Of Done

Do not stop at a plan, scaffold, trained model, notebook run, downloaded output, or local validation score. Continue until one of these is true:

• A competition submission has been sent to Kaggle, Kaggle has processed it, and the public score or submission status has been retrieved and recorded.
• A code-competition final notebook/kernel has consumed all required producer artifacts, has been submitted with its kernel/version reference, and the resulting submission status/score has been retrieved and recorded.
• A concrete external blocker prevents scoring: missing Kaggle credentials, rules not accepted, quota exhausted after retry attempts, competition closed, scoring disabled, required manual UI-only action, unavailable kernel version, or Kaggle service failure. Record the exact blocker and the next command/action needed.

Validation Choices

Use this quick mapping:

• Balanced classification: StratifiedKFold.
• Imbalanced classification: stratified folds plus metric-sensitive thresholding or class weights.
• Regression: KFold for ordinary targets, binned stratified folds for skewed or multimodal targets.
• Same user, patient, product, session, document, or image source appears multiple times: GroupKFold or stratified group splitting.
• Ordered events or forecasting: time split, expanding-window validation, or competition-specific period split.
• Images from same subject or scene: group by subject/scene before augmentation.
• Text with duplicated sources, authors, questions, products, or prompts: group by source key.
• Tiny data: repeated folds or more folds, but keep the final model selection discipline strict.

Modeling Priorities

• For tabular competitions, prefer tree boosting first unless the data is mostly sparse text or high-cardinality categorical interactions. Add CatBoost when categorical columns are central.
• For linear models and neural networks, scale numeric features and encode categoricals carefully.
• For tree models, start with label/count/frequency encodings and sensible missing values; scaling is usually unnecessary.
• For target encoding, always compute encodings out-of-fold, with smoothing and no validation-row target visibility.
• For image tasks, get dataset, transforms, labels, masks, and metric correct before changing architecture.
• For text tasks, keep a TF-IDF baseline even when using transformers; it is fast, interpretable, and often blends well.
• For hyperparameter search, tune only after folds and baselines are trustworthy. Search learning rate, depth/leaves, regularization, sampling, and number of estimators with early stopping.

Competition Hygiene

• Keep raw data read-only.
• Keep competition data, private datasets, model checkpoints, downloaded outputs, submissions, credentials, and data-derived artifacts out of public Git repositories unless the competition rules and artifact licenses explicitly allow public redistribution.
• Put all experiment-changing values in config or command-line args.
• Seed Python, NumPy, framework, and model libraries when possible.
• Save model files, OOF predictions, test predictions, fold scores, feature lists, and submission files with run IDs.
• For Kaggle-offloaded jobs, write retrievable logs and artifacts into the notebook working directory, including run ID, git commit, config, fold, metric, hardware, elapsed time, OOM notes, and output file paths.
• For multi-notebook pipelines, maintain a pipeline manifest with producer kernel refs, produced dataset refs, dataset versions, artifact schemas, metrics, and the final consumer run ID.
• Keep producer datasets, kernels, and model artifacts private by default. Make them public only after verifying the target competition rules, data license, third-party IP, and user intent.
• Record submission message, submission command or kernel/version, Kaggle submission timestamp, status, public score if available, and any error returned by Kaggle.
• For vague code-competition failures, record the observed status, available logs, suspected failure class, patch attempted, and next retry command.
• Never train a stacker on in-sample base predictions.
• Never select features, target encoders, scalers, thresholds, or augmentations using validation targets outside the fold boundary.
• Prefer scripts for repeatable training and notebooks for exploration and plots.

Useful Commands

Create a competition skeleton:

python3 <skill-dir>/scripts/scaffold_competition.py --root .

Create stratified folds:

python3 <skill-dir>/scripts/make_folds.py \
  --input input/train.csv \
  --output input/train_folds.csv \
  --target target \
  --strategy stratified \
  --n-splits 5

Create grouped folds:

python3 <skill-dir>/scripts/make_folds.py \
  --input input/train.csv \
  --output input/train_folds.csv \
  --target target \
  --group-col patient_id \
  --strategy group

Prepare a Kaggle GPU kernel experiment folder:

python3 <skill-dir>/scripts/prepare_kaggle_kernel.py \
  --output kaggle_kernels/exp_lgbm_gpu \
  --username kaggle-user \
  --slug exp-lgbm-gpu \
  --title "exp lgbm gpu" \
  --competition playground-series-sample \
  --accelerator NvidiaTeslaT4

Prepare a private Kaggle dataset folder for intermediate artifacts:

python3 <skill-dir>/scripts/prepare_kaggle_dataset.py \
  --output kaggle_datasets/exp_features_v1 \
  --username kaggle-user \
  --slug exp-features-v1 \
  --title "exp features v1" \
  --description "OOF-safe feature artifacts for experiment exp_features_v1"

Prepare a private Kaggle dataset folder for trained model artifacts:

python3 <skill-dir>/scripts/prepare_kaggle_dataset.py \
  --output kaggle_datasets/exp_model_v1 \
  --username kaggle-user \
  --slug exp-model-v1 \
  --title "exp model v1" \
  --description "Trained model artifacts for experiment exp_model_v1" \
  --artifact-kind model

Agentic Kaggle Skill

智能体驱动的 Kaggle Skill

Distilled from real Kaggle competition experience 提炼自真实 Kaggle 竞赛实践

Including: RL Game AI | Audio Classification | LLM Reasoning | Multi-stage debugging journeys 包括：强化学习游戏 AI | 音频分类 | LLM 推理 | 多阶段调试实践

Supported Agents / 支持的智能体

Canonical Skill Identity / 统一 Skill 名称

This repository keeps one canonical skill identity:

本仓库使用一个统一的 skill 名称：

name: agentic-kaggle-skill

The skill is written in the open agent skills format so it can be used by multiple agents. Codex-specific metadata lives in agents/openai.yaml; Hermes users can consume the same root SKILL.md and bundled resources.

该 skill 使用开放 agent skill 格式编写，可被多个智能体使用。Codex 专属元数据放在 agents/openai.yaml；Hermes 用户可以直接使用根目录的 SKILL.md 以及配套的 references/ 和 scripts/。

What It Does / 这个 Skill 能做什么

Transform Kaggle work from scattered manual iteration into an agent-assisted competition loop:

将 Kaggle 工作从零散的手动试错转为智能体辅助的竞赛闭环：

Core capabilities:

核心能力：

• Read Kaggle rules, data terms, metric, submission format, and scoring mode before modeling. 建模前先阅读竞赛规则、数据条款、指标、提交格式和评分模式。
• Build metric-correct baselines with stable folds and out-of-fold predictions. 构建指标正确、fold 稳定、带 OOF 预测的 baseline。
• Use public notebook and discussion intelligence as scouting signals, not copied source. 将公开 notebook 和讨论作为侦察信号，而不是直接复制来源。
• Offload heavy work to Kaggle notebooks/scripts when local compute is insufficient. 本地算力不足时，将重任务转移到 Kaggle notebook/script。
• Support staged producer/consumer notebook pipelines with private artifact datasets. 支持带私有 artifact dataset 的多阶段生产者/消费者 notebook 流水线。
• Handle code-competition hidden rerun failures, vague scoring errors, timeouts, and OOMs. 处理代码竞赛隐藏重跑失败、模糊评分错误、超时和 OOM。
• Track reproducibility artifacts, run logs, score receipts, and ensemble evidence. 记录可复现 artifact、运行日志、提交回执和集成证据。
• Continue toward a scored Kaggle submission or record a concrete blocker. 持续推进到 Kaggle 得分提交，或记录明确阻塞原因。

Install / 安装

Codex

Install as a user-level Codex skill:

作为用户级 Codex skill 安装：

mkdir -p ~/.agents/skills
git clone https://github.com/FrankS-IntelLab/agentic-kaggle-skill.git \
  ~/.agents/skills/agentic-kaggle-skill

Restart Codex if the skill does not appear immediately. Invoke it explicitly with:

如果 skill 没有立即出现，请重启 Codex。可以这样显式调用：

Use $agentic-kaggle-skill to help me start this Kaggle competition.

For repo-scoped development, place or symlink this folder under a repository's .agents/skills/ directory:

如果只想在某个仓库中启用，可以把该目录放到或软链接到仓库的 .agents/skills/：

mkdir -p .agents/skills
ln -s /path/to/agentic-kaggle-skill .agents/skills/agentic-kaggle-skill

Hermes

Install the whole skill folder so references and scripts are available:

安装完整 skill 目录，确保 references 和 scripts 都可用：

mkdir -p ~/.hermes/skills/data-science
git clone https://github.com/FrankS-IntelLab/agentic-kaggle-skill.git \
  ~/.hermes/skills/data-science/agentic-kaggle

Then ask Hermes to use the agentic Kaggle skill for competition work.

然后让 Hermes 使用 agentic Kaggle skill 来处理竞赛任务。

Helper Script Dependencies / 辅助脚本依赖

Most scripts use only the Python standard library. scripts/make_folds.py requires pandas and numpy; scikit-learn is recommended for standard splitters.

大部分脚本只依赖 Python 标准库。scripts/make_folds.py 需要 pandas 和 numpy；推荐安装 scikit-learn 以使用标准切分器。

python3 -m pip install -r requirements.txt

Repository Layout / 仓库结构

agentic-kaggle-skill/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── references/
│   ├── method-map.md
│   ├── information-sharing-policy.md
│   ├── competition-intel.md
│   ├── cross-validation-and-metrics.md
│   ├── tabular-workflow.md
│   ├── image-text-workflow.md
│   ├── kaggle-code-competition-pipeline.md
│   ├── advanced-notebook-architecture.md
│   ├── kaggle-offload.md
│   ├── kaggle-pipeline-datasets.md
│   ├── submission-endgame.md
│   ├── code-competition-debugging.md
│   ├── ensembling-and-reproducibility.md
│   └── research/
├── scripts/
│   ├── scaffold_competition.py
│   ├── make_folds.py
│   ├── prepare_kaggle_kernel.py
│   └── prepare_kaggle_dataset.py
├── examples/
│   ├── rl-game-case-study.md
│   └── audio-classification-case-study.md
├── requirements.txt
├── README.md
└── LICENSE

Case Studies / 案例研究

RL Strategy Game Competition / 强化学习策略游戏竞赛

Full case study / 完整案例

Audio Classification Competition / 音频分类竞赛

Full case study / 完整案例

Design Notes / 设计说明

SKILL.md is the canonical entry point. It stays concise and tells the agent which reference file to load for each Kaggle workflow.

SKILL.md 是统一入口，保持简洁，并告诉智能体在不同 Kaggle 工作流中应该加载哪个参考文件。

agents/openai.yaml is Codex-facing UI metadata. It does not fork the workflow; it only improves how the skill appears and is invoked in Codex.

agents/openai.yaml 是面向 Codex 的 UI 元数据，不分叉工作流，只改善该 skill 在 Codex 中的展示与调用体验。

references/ contains detailed workflow guidance loaded only when relevant. The references/research/ folder preserves earlier Hermes-era lessons, troubleshooting notes, automation patterns, and case-specific insights.

references/ 存放按需加载的详细流程说明。references/research/ 保留早期 Hermes 阶段的经验、故障排除、自动化模式和具体案例洞察。

scripts/ contains repeatable utilities for scaffolding a Kaggle project, making folds, preparing Kaggle kernels, and preparing private Kaggle artifact datasets.

scripts/ 存放可复用工具，用于创建 Kaggle 项目骨架、生成 folds、准备 Kaggle kernels，以及准备私有 Kaggle artifact datasets。

Attribution And Safety / 归属与安全

This skill is source-agnostic. It packages general competitive ML and Kaggle workflow procedures rather than copying named public notebooks, books, or papers.

该 skill 是 source-agnostic 的。它封装的是通用竞赛机器学习和 Kaggle 工作流流程，而不是复制某个公开 notebook、书籍或论文。

When using public notebooks or discussions during an active competition, treat them as scouting signals. Do not copy code, text, model artifacts, generated features, or data-derived outputs without checking the competition rules, data license, third-party license obligations, and attribution requirements.

在进行中的竞赛中使用公开 notebook 或讨论时，应将其视作侦察信号。不要在未检查竞赛规则、数据许可、第三方许可证义务和归属要求前复制代码、文本、模型 artifact、生成特征或数据派生输出。

Development / 开发维护

Keep the public identity aligned everywhere:

请保持所有位置的公开名称一致：

agentic-kaggle-skill

When updating the skill:

更新 skill 时：

1. Keep the canonical workflow in SKILL.md. 将统一工作流保留在 SKILL.md。
2. Put detailed procedure in references/. 将详细流程放入 references/。
3. Put deterministic helpers in scripts/. 将确定性辅助工具放入 scripts/。
4. Regenerate or update agents/openai.yaml when the skill name, scope, or default prompt changes. 当 skill 名称、范围或默认 prompt 变化时，更新 agents/openai.yaml。
5. Validate the skill metadata before release. 发布前验证 skill 元数据。

Why Star This Repo? / 为什么 Star？

• Battle-tested patterns from real competitions. 来自真实竞赛的实战模式。
• Bilingual documentation for English and Chinese users. 面向英文与中文用户的双语文档。
• Practical troubleshooting for common Kaggle issues. 覆盖常见 Kaggle 问题的实用故障排除。
• Codex-ready organization with Hermes compatibility. Codex-ready 的组织方式，同时兼容 Hermes。
• Case studies with concrete competition lessons. 带有具体竞赛经验的案例研究。

Contributing / 贡献

Found a new pattern or solved a tricky error?

发现了新模式或解决了棘手错误？

1. Fork the repo. Fork 仓库。
2. Add your insight to references/research/, references/, or examples/. 将你的洞察添加到 references/research/、references/ 或 examples/。
3. Submit a pull request. 提交 PR。

License / 许可证

MIT. See LICENSE.

MIT。见 LICENSE。

**Made by [Frank S (IntelLab)](http