# Kaggle Readme

> Kaggle 레포의 README.md를 자동으로 업데이트. 각 대회별로 trial 히스토리(왜 시도했는지), submission 선택 이유, reflection에서 배운 점을 표 형태로 정리한다. SUBMISSIONS.md, TRIALS.md, reflection.md 파일들을 읽어서 README.md를 생성한다. '캐글 readme 업데이트', 'kaggle readme', 'readme 써줘', 'README 갱신해줘', '대회 정리해줘' 같은 요청 시 반드시 이 스킬을 사용할 것.

- Skill: `kangraemin/kaggle-readme` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kangraemin/kaggle-readme`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kangraemin/kaggle-readme/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kangraemin (https://skillmd.com/u/kangraemin)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kangraemin/kaggle-readme

---


# Kaggle README 업데이트 스킬

Kaggle 레포의 README.md를 현재 실험/제출 현황에 맞게 자동 업데이트한다.

## 실행 순서

### 1. 대회 폴더 탐색

프로젝트 루트에서 대회 폴더들을 찾는다. 각 폴더에 `SUBMISSIONS.md`, `TRIALS.md`가 있으면 Kaggle 대회 폴더다.

### 2. 각 대회별 데이터 수집

- **`SUBMISSIONS.md`**: 제출 이력 (번호, 날짜, best trial, val/public score)
- **`TRIALS.md`**: 실험 이력 (trial 번호, 이름, val score, key changes, Notes)
- **`submissions/sub_NN/reflection.md`**: 제출 후 회고 (왜 잘못됐는지, 다음 가설)

### 3. README.md 작성

아래 구조로 작성한다:

```markdown
# Kaggle 실험 레포

| 폴더 | 대회 | Best Public |
|------|------|-------------|
| ... | ... | ... |

---

## [대회명]

**한 줄 요약**: 무엇을 예측하는 대회인지 (지표 포함)
**핵심 난관**: 이 대회의 근본적인 어려움이 뭔지

### 실험 흐름

| Trial | 왜 시도했나 | 결과 | 다음엔 |
|-------|------------|------|--------|
| 001 이름 | ... | ... | ... |

### 제출 기록

| sub | trial | public | 왜 이 결과가 나왔나 |
|-----|-------|--------|---------------------|
| 01 | ... | X.XX | ... |
```

## 핵심 작성 원칙

**독자는 이 대회를 처음 보는 사람이다.** 전문 용어는 반드시 괄호 안에 설명한다.
- 좋은 예: "직전값 feature (시계열에서 t-1 시점의 값)"
- 나쁜 예: "lag feature 추가"

**표 각 열의 기준:**

| 열 | 무엇을 쓰나 | 핵심 기준 |
|----|------------|----------|
| 왜 시도했나 | 직전 실험에서 생긴 가설 또는 발견한 문제 | "~일 것이다"는 가설로 시작 |
| 결과 | 숫자 + 왜 그 숫자가 나왔는지 한 줄 | 단순 "개선/악화"가 아니라 원인 |
| 다음엔 | 이 실험으로 생긴 새로운 질문 또는 방향 | 읽는 사람이 "그래서 다음엔 뭐가 궁금해졌구나"를 느껴야 함 |

**실패한 시도도 꼭 넣는다.** "외부 데이터 추가 → val 하락. 데이터 분포가 달라서 독이 됐다"처럼 왜 실패했는지가 더 중요한 교훈.

**비슷한 trial은 묶는다.** 같은 방향의 실험 5개를 한 줄로 묶되, 공통 결과와 발견을 쓴다.

**제출 기록의 "왜 이 결과가 나왔나"**: 단순 점수 기록이 아니라 그 점수가 나온 메커니즘을 설명한다.

## 좋은 예시 (ts-forecasting에서)

❌ 나쁜 예:
```
| 002~010 lag feature | AR(1)=0.86 발견 | val 0.89, public 0.00 | val split 문제 |
```

✅ 좋은 예:
```
| 002~010 직전값 feature | "직전값이 다음값을 강하게 예측한다(상관관계 0.86)"는 걸 발견 → 추가하면 점수 오를 것 | val 0.89로 폭등. 그런데 **제출하니 0.0000** | 시험 데이터엔 직전값이 없었다. val에서는 정답지 보며 채점한 꼴 |
```

## 완료 후

README.md 작성 완료 후:
1. git add + commit + push
2. 업데이트된 내용 1줄 보고