Hwpx Skill — AI skill for Claude Code

hwpx-skill

[](https://github.com/jkf87/hwpx-skill/stargazers) [](https://github.com/jkf87/hwpx-skill/releases) [](LICENSE)

HWP/HWPX 문서 변환·생성·읽기·편집을 위한 Claude 스킬. Windows에서는 설치된 한컴오피스 저장 엔진으로 HWP를 빠르게 HWPX로 바꾼 뒤 후속 작업을 이어간다.

⭐ **이 스킬이 도움이 되셨다면 [GitHub에서 Star](https://github.com/jkf87/hwpx-skill)를 눌러주세요!** 한글 문서 자동화가 필요한 다른 분들에게도 닿을 수 있게 도와주세요.

치환 게이트 (v1.10.0)

레퍼런스 양식을 복제해 문구를 바꿀 때는 `scripts/map_preflight.py` 로 사전검증하고, 산출물은 원본과 대조해 잔재가 없는지 확인한다.

python3 scripts/map_preflight.py dump    base.hwpx          # 키를 문서에서 뽑기
python3 scripts/map_preflight.py check   base.hwpx --map map.json
python3 scripts/fill_hwpx.py    replace  base.hwpx out.hwpx --map map.json
python3 scripts/map_preflight.py residue out.hwpx --against base.hwpx

`replace` 는 못 찾은 키가 하나라도 있으면 실패한다(`--allow-unmatched` 로 해제).

기능

워크플로우	설명
A	마크다운/텍스트/URL → HWPX 문서 생성
B	템플릿 플레이스홀더 치환
C	기존 HWPX 문서 편집 (unpack → 수정 → pack)
D	레퍼런스 HWPX 기반 새 문서 생성
E	HWPX 텍스트 읽기/추출
F	양식 복제 (테이블/이미지/스타일 100% 보존)
G	행정안전부 표준 기안문(별지 제1호서식) 생성 + 작성법 자동 검수 (2025 행정업무운영 편람)
H	HWP → HWPX 변환(Windows 한컴 COM 우선, rhwp WASM 폴백) 후 읽기·편집
I	문제지 1장 + 답안지 1장 HWPX 생성
J	서식 보존 양식 필드 채우기
K	K-Teacher 학생 활동지 HTML → 편집 가능한 HWPX

설치

# 기본 의존성
pip install python-hwpx lxml --break-system-packages

# HWP→HWPX 변환 (워크플로우 H)
# Windows 우선 경로: 한컴오피스 한글 + HwpAutomation 파일 경로 보안 모듈
# 폴백 경로: Node.js 18+, rhwp WASM 런타임은 저장소에 고정·포함

빠른 시작

HWP → HWPX 변환

Windows에 한컴오피스 한글이 설치되어 있으면 실제 한글 저장 엔진을 우선 사용한다. 한 프로세스를 재사용해 폴더 안의 `.hwp`를 빠르게 일괄 변환하며 원본은 그대로 둔다.

# 파일 하나
powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  "scripts/convert_hwp_