Menú
문서 파일(HWP, HWPX, PDF, XLSX, DOCX, PPTX, PPT, XLS, DOC, ODF)을 Markdown으로 변환합니다. 스캔 PDF는 OCR 자동 실행, 이미지는 Claude 멀티모달로 해석합니다.
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
| name | parse-doc |
| description | 문서 파일(HWP, HWPX, PDF, XLSX, DOCX, PPTX, PPT, XLS, DOC, ODF)을 Markdown으로 변환합니다. 스캔 PDF는 OCR 자동 실행, 이미지는 Claude 멀티모달로 해석합니다. |
| when_to_use | hwp 읽어줘, pdf 변환해줘, 엑셀 내용 보여줘, 문서를 마크다운으로. 외부용 재작성은 rewrite-external. |
| allowed-tools | Read, Write, Bash, Glob |
.local.claude/docs/original/에 있는 문서를 Markdown으로 변환하여 .local.claude/docs/parsed/에 저장한다.
내부적으로 kordoc(HWP/HWPX/PDF/XLSX/DOCX)과 python-pptx(PPTX/PPT)를 사용하지만, 사용자는 파일 확장자만 신경 쓰면 된다.
| 데이터 | 경로 | 필수/선택 | 부재 시 동작 |
|---|---|---|---|
| 프로젝트 컨텍스트 | CLAUDE.md | 선택 | 일반 가정으로 진행, [프로젝트 규칙 미확인] 태그 |
| 봇 인덱스 | bot/INDEX.md 또는 .local.claude/ONBOARDING.md | 선택 | 디렉터리 Glob 으로 fallback |
| 비즈니스 규칙 | .local.claude/biz-rules.md | 선택 | 일반 SW 관점으로만 진행 (Tier 1) |
| 모듈 상세 | .local.claude/modules/{name}.md | 선택 | 코드 Grep 직접 fallback |
| 원본 디렉터리 | .local.claude/docs/original/ | 필수 | "원본 없음. original/ 에 파일 배치 후 재시도" 안내 후 종료 |
| 파서 도구 | pptx2md.py, pdf_images.py, Tesseract | 선택 | 미설치 시 "미지원" + 설치 가이드 제공 |
| OCR 언어팩 | Tesseract kor / eng 팩 | 선택 | 미설치 시 OCR 생략, 이미지 텍스트 인식 불가 |
| 질문 | 담당 | 이 스킬에서 |
|---|---|---|
| "바이너리, 외부 문서(HWP/PDF/XLSX 등)를 Markdown 으로 변환" | 이 스킬 | ✓ 핵심 (포맷 변환까지) |
| "변환된 문서에서 지식 추출과 지식 베이스 반영" | /absorb | 다루지 않음 (parse-doc 산출물을 absorb 입력으로 사용) |
| "parsed/ 누적 문서 흡수 확인, 아카이브, 만료 관리" | /garden | 다루지 않음 (수명 관리는 garden) |
| "사람용/AI용 이중 문서 분리와 재구성" | /dualize-docs | 다루지 않음 (이 스킬은 원본을 Markdown 으로 변환하는 것까지만) |
.local.claude/docs/
├── original/ ← 원본 파일을 여기에 놓기
└── parsed/ ← 파싱된 Markdown 출력
| 입력 | 동작 |
|---|---|
/parse-doc 파일명.hwp | original/ 내 해당 파일을 파싱 |
/parse-doc 파일명.pptx | 동일 |
/parse-doc *.pdf | original/ 내 모든 PDF 파싱 |
/parse-doc (인자 없음) | original/ 내 미파싱 파일 전체 자동 파싱 |
/parse-doc list | original/과 parsed/ 현황 표시 |
[1M 활용] 다음을 단일 메시지에서 병렬로 호출:
- Bash 병렬:
ls .local.claude/docs/original/,ls .local.claude/docs/parsed/,which tesseract/which npx/py --version등 파서 도구 가용성 확인, 각 파일 확장자별 파싱 명령(kordoc / pptx2md / officeparser) 을 여러 파일에 대해 동시 실행- Read: 이미 파싱된
.local.claude/docs/parsed/*.md목록을 병렬로 확인(스킵 판단)- Glob: 인자가 패턴(
ls .local.claude/docs/original/
인자가 있으면 해당 파일만, 없으면 전체 파일 대상.
| 확장자 | 파서 | 명령어 |
|---|---|---|
.hwp | kordoc | npx kordoc "{파일}" -o "{출력}.md" --silent |
.hwpx | kordoc | 동일 |
.pdf | kordoc | 동일 |
.xlsx | kordoc | 동일 |
.docx | kordoc | 동일 |
.pptx | python-pptx | py .claude/skills/parse-doc/pptx2md.py "{파일}" "{출력}.md" |
.xls | xlrd | py .claude/skills/parse-doc/xls2md.py "{파일}" "{출력}.md" |
.ppt | officeParser | npx officeparser "{파일}" --toText=true > "{출력}.md" |
.doc | officeParser | 동일 |
.odt/.odp/.ods | officeParser | 동일 |
출력 파일명: 원본 파일명에서 확장자만 .md로 변경.
예: 회의록.hwp 는 회의록.md 로.
각 파일에 대해:
# 파일 존재 확인
FILE=".local.claude/docs/original/{파일명}"
if [ ! -f "$FILE" ]; then
echo "파일을 찾을 수 없습니다: $FILE"
exit 1
fi
# 확장자 추출
EXT="${FILE##*.}"
BASENAME=$(basename "$FILE" ".$EXT")
OUTPUT=".local.claude/docs/parsed/${BASENAME}.md"
# 이미 파싱된 파일은 스킵 (강제 재파싱은 --force)
if [ -f "$OUTPUT" ]; then
echo "이미 파싱됨: $OUTPUT (재파싱하려면 삭제 후 재실행)"
fi
# 확장자별 라우팅
case "$EXT" in
hwp|hwpx|xlsx|docx)
npx kordoc "$FILE" -o "$OUTPUT" --silent
;;
pdf)
npx kordoc "$FILE" -o "$OUTPUT" --silent
# 스캔 PDF 감지: kordoc 결과가 빈 텍스트면 OCR 시도
if [ ! -s "$OUTPUT" ] || [ "$(wc -c < "$OUTPUT")" -lt 50 ]; then
echo "[WARN] 텍스트가 거의 없음 — 스캔 PDF로 판단, OCR 시도..."
py .claude/skills/parse-doc/ocr_pdf.py "$FILE" "$OUTPUT"
fi
# PDF 이미지 추출 (텍스트 파싱과 별도)
py .claude/skills/parse-doc/pdf_images.py "$FILE" ".local.claude/docs/parsed/images"
;;
pptx)
py .claude/skills/parse-doc/pptx2md.py "$FILE" "$OUTPUT"
;;
xls)
py .claude/skills/parse-doc/xls2md.py "$FILE" "$OUTPUT"
;;
ppt|doc|odt|odp|ods)
npx officeparser "$FILE" --toText=true > "$OUTPUT"
;;
txt|csv|json|xml|md)
echo "텍스트 파일 — Read 도구로 직접 읽기 가능. 파싱 불필요."
;;
png|jpg|jpeg|gif|bmp|tiff)
echo "이미지 파일 — Read 도구로 읽으면 Claude 멀티모달로 해석 가능."
;;
*)
echo "미지원: .$EXT"
;;
esac
파싱 불가능하거나 실패한 파일이 있으면, 왜 안 되는지 + 대안 2가지(변환/라이브러리 설치)를 안내한다.
| 확장자 | 상태 | 비고 |
|---|---|---|
.ppt | [OK] 지원 | officeParser (텍스트 추출 수준) |
.doc | [OK] 지원 | officeParser |
.xls | [OK] 지원 | xlrd 로 Markdown 테이블 변환 |
.odt/.odp/.ods | [OK] 지원 | officeParser |
.txt/.csv/.json/.xml | 파싱 불필요 | Read 도구로 직접 읽기 안내 |
이미지(.png/.jpg) | 파싱 불필요 | Read 도구로 읽으면 Claude 멀티모달 해석 안내 |
| 실패 원인 | 증상 | 대안 1: 변환 | 대안 2: 라이브러리 |
|---|---|---|---|
| 암호화된 HWP | kordoc 에러 또는 빈 출력 | 암호 해제 후 재저장 | kordoc 배포용 복호화 시도, 실패 시 원본 작성자에게 요청 |
| 스캔 PDF (이미지 PDF) | 빈 문자열 또는 깨진 텍스트 | Adobe Acrobat에서 OCR 적용 후 재저장 | 아래 Tesseract 설치 가이드 참조 |
| 대용량 PDF (100MB+) | 타임아웃 | 페이지 분할: npx kordoc 파일.pdf --pages 1-20 | 없음 |
| PPTX 차트/SmartArt | 해당 요소만 텍스트 미추출 | 없음 | 차트는 이미지로 추출되므로 Claude 멀티모달 해석으로 대체 |
| HWP/HWPX 이미지 | kordoc이 이미지 미추출 | HWP를 PDF로 변환 후 pdf_images.py로 추출 | 한컴오피스에서 PDF로 내보낸 뒤 kordoc(텍스트) + pdf_images.py(이미지) |
스캔 PDF나 이미지 파일의 텍스트 추출이 필요할 때:
winget install UB-Mannheim.TesseractOCRtessdata/kor.traineddata 수동 추가winget install poppler 또는 GitHub에서 다운로드 후 PATH 추가py -m pip install pytesseract pdf2image (이미 설치됨)대안 2(라이브러리)를 사용자가 선택하면, 설치 명령을 안내하고 스킬 라우팅 테이블에 추가할지 제안한다.
| 포맷 | 추출 도구 | 실행 |
|---|---|---|
| PPTX | pptx2md.py (python-pptx) | 텍스트 파싱과 동시에 자동 추출 |
| pdf_images.py (PyMuPDF) | kordoc 파싱 후 별도 실행: py .claude/skills/parse-doc/pdf_images.py "{파일}" ".local.claude/docs/parsed/images" | |
| HWP/HWPX | 없음 | 현재 추출 도구 없음 (미지원) |
PDF 이미지 추출 시 5KB 미만 소형 이미지(아이콘, 장식)는 자동 스킵.
파싱 완료 후 parsed/images/에 이미지가 있으면:
> **[이미지 해석]** 시스템 아키텍처 다이어그램. 클라이언트에서 API Gateway 를 거쳐 마이크로서비스 3개(인증, 주문, 재고), 그 뒤 PostgreSQL DB 로 이어지는 구조.
파싱 완료 후:
파싱 완료:
| 파일 | 파서 | 결과 | 크기 |
|------|------|------|------|
| 회의록.hwp | kordoc | [OK] 회의록.md | 2.3KB |
| 발표자료.pptx | officeParser | [OK] 발표자료.md | 5.1KB |
파싱된 파일은 `.local.claude/docs/parsed/`에 저장되었습니다.
내용을 확인하려면 Read로 직접 읽으세요.
echo "=== original/ ==="
ls -la .local.claude/docs/original/
echo "=== parsed/ ==="
ls -la .local.claude/docs/parsed/
미파싱 파일 표시:
| 원본 파일 | 파싱 상태 |
|----------|----------|
| 회의록.hwp | [OK] parsed/회의록.md |
| 발표자료.pptx | [FAIL] 미파싱 |
original/ 디렉터리의 모든 파일을 스캔하여:
파싱 완료 후, 문서 성격에 따라 다음 작업을 안내한다:
| 문서 성격 | 판단 기준 (파일명/내용 키워드) | 안내 |
|---|---|---|
| 요구사항/RFP/제안요청 | "요구", "RFP", "제안", "사양", "규격" | /daily-todos에 할 일 추출, 또는 .local.claude/projects/에 PRD 초안 생성 |
| 회의록/미팅노트 | "회의", "미팅", "minutes", "논의" | 요약 + 액션 아이템 추출을 제안 |
| 규격서/기술문서 | "spec", "규격", "표준", "기술" | /biz-rules에 관련 규칙 추출 반영 검토 |
| 고객사 자료 | 고객사명 (.local.claude/customers/ 파일명 매칭) | .local.claude/customers/{고객사}.md 업데이트 검토 |
| 기타 | 없음 | "파싱 완료. 이 문서로 무엇을 하시겠습니까?" |
안내는 제안만 한다. 자동 실행하지 않음.
| 산출물 | 임계 1 (알림) | 임계 2 (분리) |
|---|---|---|
parsed/{file}.md (변환 결과) | 500줄 | 원본 페이지, 시트, 섹션 단위로 분할 출력 (예: {file}-part1.md) |
parsed/images/ 누적 | 50개 | 문서별 하위 디렉터리(parsed/images/{문서명}/)로 그룹화 |
parsed/ 산출물은 즉시 자동 로드 대상이 아니므로(@ 미사용) 임계는 가독성과 후속 흡수 효율 기준. 대용량 PDF(100MB+ / 200페이지+)는 pages 분할로 변환 자체를 나눈다 (검증 시나리오 참조). 누적 정리와 아카이브는 /garden 위임.
.local.claude/docs/original/에 위치해야 함공통 3블록(빈 / 부분 / 풀 데이터)은 CONTRACT 6-1절 참조.
[의존성 부재] Tesseract / pptx2md / 기타 변환 도구 미설치
which tesseract / pptx2md --version 실패[환경/규모] PDF 200페이지 이상
pages 파라미터 분할 권장 + timeout 경고 표시, 부분 처리 후 병합 전략 안내