v2.0.0 to v2.0.0

---

name: excel2md

description: >

.xlsx 엑셀 파일 읽기/변환 전문 스킬. JSON/마크다운 변환, 임베디드 이미지 자동 추출,

시트별 파일 생성, 데이터 타입 감지, 병합 셀/멀티 헤더 처리.

".xlsx", "엑셀", "excel", "스프레드시트" 요청에 실행.

triggers:

- "excel"

- "엑셀"

- "xlsx"

- "스프레드시트"

- "spreadsheet"

auto_apply: false

license: MIT

metadata:

version: "2.0.0"

---

# Excel to JSON/Markdown

엑셀 파일을 구조화된 JSON 또는 마크다운으로 변환합니다.

임베디드 이미지도 자동 추출하여 해당 행에 매핑합니다.

## Quick Start

```

/excel2md report.xlsx # JSON (기본)

/excel2md report.xlsx --format md # 마크다운

/excel2md data.xlsx --sheet "매출현황" # 특정 시트

/excel2md data.xlsx --output ./docs # 출력 디렉토리

/excel2md data.xlsx --no-images # 이미지 제외

```

---

## Step 0: 구조 분석 (First Actions)

변환 전 엑셀 파일의 구조를 먼저 파악합니다.

```python

import openpyxl

wb = openpyxl.load_workbook('data.xlsx', data_only=True)

for sheet_name in wb.sheetnames:

ws = wb[sheet_name]

print(f"\n=== {sheet_name} ===")

print(f" 크기: {ws.max_row}행 × {ws.max_column}열")

print(f" 병합 셀: {len(ws.merged_cells.ranges)}개")

# 헤더 자동 감지 (문자열 비율 기반)

for row_idx in range(1, min(6, ws.max_row + 1)):

row = [ws.cell(row_idx, c).value for c in range(1, ws.max_column + 1)]

str_ratio = sum(1 for v in row if isinstance(v, str)) / max(len(row), 1)

marker = " ← 헤더 후보" if str_ratio > 0.7 else ""

print(f" 행 {row_idx}: {row[:5]}...{marker}")

```

### 구조 분석 출력 예시

```

=== Sheet1 ===

크기: 150행 × 8열

병합 셀: 3개

행 1: ['번호', '이름', '부서', '직급', '입사일']... ← 헤더 후보

행 2: [1, '김철수', '개발팀', '대리', datetime(2020,3,1)]...

=== 매출현황 ===

크기: 50행 × 12열

병합 셀: 12개 (그룹 헤더)

행 1: ['', '', '2025년', None, None, '2026년']... ← 그룹 헤더

행 2: ['지역', '담당자', '1Q', '2Q', '3Q', '1Q']... ← 실제 헤더

```

---

## Step 1: 데이터 타입 감지 + 변환

### 타입별 처리 규칙

| 엑셀 타입 | JSON 출력 | MD 출력 |

|-----------|-----------|---------|

| 문자열 | `"text"` | text |

| 정수 | `123` | 123 |

| 소수 | `3.14` | 3.14 |

| 날짜 | `"2026-04-16"` (ISO 8601) | 2026-04-16 |

| 불리언 | `true/false` | Yes/No |

| 수식 | 계산 결과값 (data_only) | 계산 결과값 |

| 빈 셀 | `null` | (공백) |

| 하이퍼링크 | `{"text": "클릭", "url": "https://..."}` | [클릭](https://...) |

| 통화 | `{"value": 15000, "format": "₩#,##0"}` | ₩15,000 |

| 퍼센트 | `{"value": 0.15, "format": "0.00%"}` | 15.00% |

### 병합 셀 처리

병합된 셀은 첫 번째 셀의 값을 모든 병합 범위에 전파합니다.

### 멀티 헤더 (그룹 헤더) 처리

```

행 1: | | 2025년 | | 2026년 | |

행 2: | 지역 | 1Q | 2Q | 1Q | 2Q |

→ 컬럼명: "지역", "2025년_1Q", "2025년_2Q", "2026년_1Q", "2026년_2Q"

```

---

## Step 2: 이미지 추출

xlsx는 ZIP 아카이브이며, 내부 XML을 파싱하여 이미지를 추출합니다:

1. `xl/worksheets/_rels/sheet*.xml.rels` → 시트→드로잉 매핑

2. `xl/drawings/_rels/drawing*.xml.rels` → rId→미디어 파일 매핑

3. `xl/drawings/drawing*.xml` → 앵커에서 row/col + rId 추출

4. `xl/media/*` → 이미지 바이너리 추출

**Fallback**: 드로잉 매핑 실패 시 media 폴더 전체 추출 (위치 없음 → "기타" 섹션 배치).

---

## Step 3: 출력

### JSON 구조

```json

{

"source": "report.xlsx",

"sheet": "Sheet1",

"row_count": 150,

"headers": ["번호", "이름", "부서", "직급", "입사일"],

"column_types": ["int", "str", "str", "str", "date"],

"rows": [

{"번호": 1, "이름": "김철수", "부서": "개발팀", "직급": "대리", "입사일": "2020-03-01"}

],

"images": [

{"filename": "image1.png", "row": 1, "col": 0}

],

"metadata": {

"merged_cells": 3,

"has_formulas": true

}

}

```

### Markdown 구조

```markdown

# Sheet1

> Source: report.xlsx | Rows: 150 | Images: 5

| 번호 | 이름 | 부서 | 직급 | 입사일 |

|------|------|------|------|--------|

| 1 | 김철수 | 개발팀 | 대리 | 2020-03-01 |

## 첨부 이미지

### 행 1


```

---

## 특수 케이스 처리

| 케이스 | 처리 |

|--------|------|

| 파이프(`\|`) 포함 셀 | MD에서만 이스케이프 |

| 시트명 특수문자 | 안전한 파일명으로 변환 (`/` → `_`) |

| 이미지 없는 xlsx | 텍스트만 변환 |

| twoCellAnchor + oneCellAnchor | 두 앵커 타입 모두 지원 |

| 1000행 이상 대용량 | 청크 처리 |

| 빈 시트 | 건너뛰기 + 경고 |

---

## 요구사항

```bash

pip install openpyxl

```

## 옵션

| 옵션 | 단축 | 설명 |

|------|------|------|

| `--format` | | `json`(기본) 또는 `md` |

| `--sheet` | `-s` | 특정 시트만 |

| `--output` | `-o` | 출력 디렉토리 |

| `--overwrite` | `-f` | 덮어쓰기 |

| `--no-images` | | 이미지 제외 |

## Helper Scripts

| 스크립트 | 용도 |

|---------|------|

| `excel2md.py` | 메인 CLI |

| `scripts/excel_parser.py` | openpyxl 파싱 헬퍼 |

## Related Files

| 파일 | 역할 |

|------|------|

| `skills/pdf/SKILL.md` | PDF 변환 |

| `skills/docx/SKILL.md` | Word 문서 변환 |

| `skills/web-to-markdown/SKILL.md` | 웹페이지 변환 |