HWP

What this skill does

.hwp 문서를 읽어 JSON / Markdown / HTML로 변환하고, 이미지 추출이나 배치 처리를 수행한다.
환경이 Windows + 한글(HWP) 프로그램 설치 + 직접 제어가 필요한 작업이면 hwp-mcp를 선택하고, 그 외에는 기본값으로 @ohah/hwpjs를 사용한다.

When to use

"이 HWP 파일을 Markdown으로 바꿔줘"
"한글 문서에서 이미지만 뽑아줘"
"폴더 안 HWP를 한 번에 JSON으로 변환해줘"
"윈도우에서 한글 프로그램을 직접 조작해서 표 채워줘"

When not to use

원본이 .hwpx, .docx, .pdf 인 경우
Windows가 아니거나 한글 프로그램이 없는데 직접 편집 자동화를 요구하는 경우
OCR이나 스캔 PDF 복구가 필요한 경우

Prerequisites

공통 변환 경로: Node.js 18+
직접 제어 경로: Windows + 한글(HWP) 프로그램 설치 + Python 3.7+
출력 경로 쓰기 권한

Inputs

원본 .hwp 파일 경로 또는 폴더 경로
원하는 출력 형식: json, markdown, html
출력 파일/디렉터리 경로
이미지 포함/추출 여부
배치 처리 여부
직접 제어가 필요한지 여부

Routing policy

Default: `@ohah/hwpjs`

다음 조건 중 하나라도 맞으면 @ohah/hwpjs를 기본값으로 사용한다.

macOS / Linux / CI 환경
Windows여도 한글 프로그램 설치 여부를 확신할 수 없음
읽기 / 변환 / 이미지 추출 / 배치 처리 중심 작업

Windows direct-control path: `hwp-mcp`

다음 조건을 모두 만족할 때만 hwp-mcp를 선택한다.

운영체제가 Windows
한글(HWP) 프로그램이 실제로 설치되어 있음
문서 생성, 텍스트 삽입, 표 채우기, 저장 같은 실행 중인 한글 프로그램 직접 제어가 필요함

직접 제어 조건이 불분명하면 추측하지 말고 @ohah/hwpjs로 처리 가능한 범위부터 진행한다.

Workflow

0. Detect the environment first

node -p "process.platform"

결과가 win32가 아니면 @ohah/hwpjs
결과가 win32여도 한글 프로그램 직접 제어가 확인되지 않으면 @ohah/hwpjs
win32 이고 한글 프로그램이 실제로 설치되어 있으며 직접 조작이 필요하면 hwp-mcp

1. Install the chosen backend when missing

`@ohah/hwpjs`

npm install -g @ohah/hwpjs
export NODE_PATH="$(npm root -g)"

`hwp-mcp`

git clone https://github.com/jkf87/hwp-mcp.git
cd hwp-mcp
pip install -r requirements.txt

hwp-mcp는 Windows와 한글 프로그램 설치가 전제다. 이 전제가 깨지면 억지로 진행하지 말고 @ohah/hwpjs로 되돌린다.

2. Prefer `@ohah/hwpjs` for conversions and extraction

JSON 변환

hwpjs to-json document.hwp -o output.json --pretty

Markdown 변환

hwpjs to-markdown document.hwp -o output.md --include-images

--include-images 는 이미지를 별도 파일로 떨구지 않고 Markdown 안에 base64 data: URI로 인라인한다. 이미지를 파일로 따로 저장해야 하면 다음처럼 --images-dir 를 사용한다.

hwpjs to-markdown document.hwp -o output.md --images-dir ./images

HTML 변환

hwpjs to-html document.hwp -o output.html

이미지 추출

hwpjs extract-images document.hwp -o ./images

배치 처리

hwpjs batch ./documents -o ./output --format json --recursive

배치 출력 형식은 로컬 설치 버전의 hwpjs batch --help 를 확인해 맞춘다.

3. Use `hwp-mcp` only for live HWP control on Windows

Claude/Codex MCP 설정에 hwp_mcp_stdio_server.py 를 등록한 뒤 다음 종류의 작업에 사용한다.

새 문서 생성
텍스트 삽입
표 생성 / 채우기
저장
여러 편집 명령을 묶은 배치 작업

직접 제어 예시는 다음 범주에 한정한다.

보고서 템플릿 채우기
표 데이터 입력
정해진 서식 문서 생성

4. Verify outputs after every run

JSON: 파일 생성 여부와 최상위 구조 확인
Markdown: 본문 생성 여부와 data: URI / base64 이미지 인라인 포함 여부 확인 (--include-images 사용 시)
Markdown: 이미지 파일 분리가 목적이면 --images-dir 출력 디렉터리에 실제 파일이 생겼는지 확인
HTML: 파일 생성 후 브라우저 렌더링 가능 여부 확인
이미지 추출: 출력 디렉터리에 파일이 실제로 생겼는지 확인
배치 처리: 입력 개수와 출력 개수가 대략 맞는지 확인

Done when

요청한 형식의 결과물이 생성되어 있다
이미지 요청이 있으면 추출 파일 또는 Markdown 안 data: URI 인라인 결과가 확인되어 있다
배치 요청이면 처리 범위와 실패 건수가 정리되어 있다
Windows 직접 제어 작업이면 어떤 조작을 수행했는지 남아 있다

Failure modes

손상된 .hwp 파일
전역 hwpjs 미설치
Windows가 아니어서 hwp-mcp를 사용할 수 없음
한글 프로그램 미설치 또는 자동화 연결 실패
출력 디렉터리 권한 부족

Notes

기본 선택지는 언제나 @ohah/hwpjs다.
hwp-mcp는 Windows + 한글 설치 환경에서만 직접 제어용으로 사용한다.
직접 제어가 실패해도 읽기/변환 작업으로 충분하면 @ohah/hwpjs 경로로 축소해 완료한다.

hwp

HWP