HWP/HWPX 문서 변환·생성·읽기·편집을 위한 Claude 스킬. Windows에서는 설치된 한컴오피스 저장 엔진으로 HWP를 빠르게 HWPX로 바꾼 뒤 후속 작업을 이어간다.
⭐ 이 스킬이 도움이 되셨다면 GitHub에서 Star를 눌러주세요! 한글 문서 자동화가 필요한 다른 분들에게도 닿을 수 있게 도와주세요.
| 워크플로우 | 설명 |
|---|---|
| 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 런타임은 저장소에 고정·포함Windows에 한컴오피스 한글이 설치되어 있으면 실제 한글 저장 엔진을 우선 사용한다.
한 프로세스를 재사용해 폴더 안의 .hwp를 빠르게 일괄 변환하며 원본은 그대로 둔다.
# 파일 하나
powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
"scripts/convert_hwp_hancom.ps1" "input.hwp"
# 폴더 전체를 별도 폴더로 변환
powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
"scripts/convert_hwp_hancom.ps1" "." `
-OutputDirectory ".\converted" -Overwrite한컴 COM 엔진 또는 등록된 파일 경로 보안 모듈을 사용할 수 없으면 Node.js 18+ 기반의 기존 크로스플랫폼 변환기로 폴백한다.
python3 scripts/convert_hwp.py input.hwp -o output.hwpxCOM 변환기는 결과를 임시 HWPX에 저장한 뒤 대상 경로에 교체해 실패 시 기존
출력을 보존한다. 폴더 입력은 .hwp만 정확히 고르며 .hwpx를 재변환하지 않는다.
폴백 변환기는 claw-hwp가 사용하는 @rhwp/core 0.7.10 WASM 런타임을 고정해서
사용한다. 실행 중 pip install이나 Git clone을 하지 않으며 이미지 매니페스트,
원본 크기, 미리보기, 용지·여백과 유효한 줄배치 캐시를 보정한 뒤
check --strict까지 통과한 파일만 출력한다.
.hwp의 읽기·추출·편집을 요청하면 원본을 보존한 별도 HWPX로 자동 변환한 뒤
해당 워크플로우를 계속한다. 사용자가 HWP 형식 유지나 변환 금지를 명시하면 자동
변환하지 않는다. 포맷 차이로 표 음영, 복잡한 도형, 간격과 쪽 나눔이 달라질 수
있으므로 중요한 문서는 원본과 함께 보관하고 한컴에서 시각 점검한다.
import sys
from pathlib import Path
sys.path.insert(0, str(Path("scripts")))
from hwpx_helpers import *
# section0.xml 조립 → build_hwpx.py로 빌드 → fix_namespaces.py 후처리K-Teacher가 실제 출력하는 .doc-header, section.block, data-block-type="student_task", source_card, answer_box, exit_ticket, 자료표와 쪽 나누기를 네이티브 HWPX 표·문단·둥근 글상자로 변환한다. 편집형 2단 제목부, 번호 섹션 레일, 라운드 STEP 과제 카드, 남색 표 머리, 라운드 자료 카드와 출구표를 유지하면서 한글에서 텍스트와 표를 계속 편집할 수 있다.
python3 scripts/html2hwpx.py input.html output.hwpx \
--keep-xml build/html2hwpx중간 산출물은 design-plan.xml → section0.xml 순서이며, 생성 후 네임스페이스 수정·줄배치 캐시 정리·레이아웃 검증까지 자동 실행한다. 지원 HTML과 디자인 매핑은 references/html-to-hwpx.md를 참고한다.
# 샘플 기안문 생성 (두문·본문·결문 + 맑은 고딕 11.5pt)
python3 scripts/gonmun.py --sample --output 기안문.hwpx
# JSON 입력으로 생성
python3 scripts/gonmun.py --input gonmun.json --output 기안문.hwpx
# 작성법 자동 검수 (날짜·시간·금액·붙임·물결표·외국어 병기 등)
python3 scripts/gonmun_lint.py --hwpx 기안문.hwpx --format text# 실제 정부 보도자료 양식(assets/bodojaryo-reference.hwpx)을 복제 — 표·로고·글꼴 100% 보존,
# 본문(□/ㅇ/*)·머리표(보도시점·제목·부제·담당자)만 교체
python3 scripts/bodojaryo.py --sample --output 보도자료.hwpx
python3 scripts/bodojaryo.py --input bodo.json --output 보도자료.hwpx# ⚠️ 계획서 생성 전 제목·목차 포함 여부를 사용자에게 먼저 질문 (PreToolUse 훅 gyehoek_hook.py가 강제)
python3 scripts/gyehoek.py --title "2026년 ○○ 추진계획" --date "2026. 1." --toc --output 계획서.hwpx
python3 scripts/gyehoek.py --no-title --no-toc --output 계획서.hwpx# 분석
python3 scripts/clone_form.py --analyze sample.hwpx
# 복제 + 텍스트 치환
python3 scripts/clone_form.py sample.hwpx output.hwpx --map replacements.json
python3 scripts/fix_namespaces.py output.hwpxscripts/fill_hwpx.py는 kordoc의 fillHwpx 설계에서 가져온 라벨 인식,
self-closing 빈 run 처리, 수정 엔트리만 ZIP 패치하는 보존형 채우기 방식을
Python으로 포팅한 도구다. 신청서·정산서·강사카드처럼 라벨-값 셀이나
체크박스/괄호 빈칸이 있는 서식에 먼저 사용한다.
# 채울 수 있는 필드 분석
python3 scripts/fill_hwpx.py analyze form.hwpx
# values.json 예: {"성명": "홍길동", "연락처": "010-1234-5678"}
python3 scripts/fill_hwpx.py fill form.hwpx output.hwpx --values values.json
# 값 삽입과 비변경 엔트리 보존 검증
python3 scripts/fill_hwpx.py verify output.hwpx --values values.json --original form.hwpx
# 머리말·꼬리말·자동 쪽번호 사후 삽입/제거 (원본 보존, 중복 방지)
python3 scripts/fill_hwpx.py set-header doc.hwpx out.hwpx --text "대외주의" --align center
python3 scripts/fill_hwpx.py set-footer doc.hwpx out.hwpx --text "한국연구재단"
python3 scripts/fill_hwpx.py set-pagenum doc.hwpx out.hwpx --where footer --align center
python3 scripts/fill_hwpx.py remove-header doc.hwpx out.hwpx
# 표 구조/스타일 in-place (셀 배경/테두리·열추가·행삭제·셀병합)
python3 scripts/fill_hwpx.py set-cell doc.hwpx out.hwpx --table 0 --row 0 --col 1 --bg FFE600 --border on
python3 scripts/fill_hwpx.py merge-cells doc.hwpx out.hwpx --table 0 --row 0 --col 0 --row2 0 --col2 2
# 네이티브 수식 삽입 (문법: references/equation-syntax.md)
python3 scripts/fill_hwpx.py add-equation doc.hwpx out.hwpx --after "기준 문구" --script "x^2+y^2=z^2"
# 본문 글자/문단 서식 (굵게·색·크기·정렬·줄간격)
python3 scripts/fill_hwpx.py set-text-style doc.hwpx out.hwpx --after "제목 문구" --bold --color C00000 --size 16
python3 scripts/fill_hwpx.py set-para-style doc.hwpx out.hwpx --after "제목 문구" --align center --line-spacing 180
# 직인/서명 이미지(사용자 제공 PNG)를 기준 문구 위에 떠있게
python3 scripts/fill_hwpx.py place-seal doc.hwpx out.hwpx --image seal.png --anchor "발신명의" --size-mm 20
# 각주·하이퍼링크·책갈피 / 페이지·다단·쪽나누기 / 목록 / 차트
python3 scripts/fill_hwpx.py add-footnote doc.hwpx out.hwpx --after "본문" --text "각주"
python3 scripts/fill_hwpx.py set-page doc.hwpx out.hwpx --orientation landscape --margin-mm 15 --size a4
python3 scripts/fill_hwpx.py set-columns doc.hwpx out.hwpx --count 2 --gap-mm 8
python3 scripts/fill_hwpx.py set-bullet-list doc.hwpx out.hwpx --para 3 --to 6
python3 scripts/fill_hwpx.py insert-chart doc.hwpx out.hwpx --type col --cat cat.json --series series.json
# 문서 테마(제목색·표머리색 일괄) / 도형·글상자 / 이미지 편집
python3 scripts/fill_hwpx.py set-theme doc.hwpx out.hwpx --theme 남색
python3 scripts/fill_hwpx.py insert-textbox doc.hwpx out.hwpx --after "여기" --text "참고" --fill FFF2CC --rounding 24
python3 scripts/fill_hwpx.py list-images doc.hwpx
python3 scripts/fill_hwpx.py resize-image doc.hwpx out.hwpx --index 0 --width-mm 30
# 개인정보(PII) 비경유 양식 채우기 — 값이 stdout/로그/모델 컨텍스트를 안 거침
python3 scripts/secure_fill.py fill form.hwpx out.hwpx --profile profile.json --shred-profile
# 한컴 열림 위험 신호까지 엄격 점검
python3 scripts/fill_hwpx.py check output.hwpx --strictpython3 scripts/fix_namespaces.py output.hwpx
python3 scripts/finalize_hwpx.py output.hwpx --strip-linesegarray --layout
python3 scripts/validate.py output.hwpx --layout
# Windows + Hancom Office only
python3 scripts/validate.py output.hwpx --hancomfinalize_hwpx.py removes stale hp:linesegarray layout caches after XML
text replacement and reports likely layout risks, including long single
paragraphs in table cells, short row heights for dense cells, and body text
that lost visible indentation after headings.
python3 scripts/text_extract.py doc.hwpx
python3 scripts/text_extract.py doc.hwpx --format markdownpython3 scripts/build_problem_answer_sheet.py \
--input-json lesson.json \
--output lesson-sheet.hwpx
python3 scripts/validate.py lesson-sheet.hwpxlesson.json에는 제목, 단원, 장면/문항 요약, 예시 답안을 넣는다. 결과물은 1쪽 문제지, 2쪽 답안지 구조로 만들어진다.
hwpx-skill/
├── SKILL.md # 스킬 전체 문서 (Decision Tree, 워크플로우, 규칙)
├── scripts/
│ ├── hwpx_helpers.py # 헬퍼 라이브러리 (배너/섹션바/이미지/빌드)
│ ├── convert_hwp.py # HWP→HWPX 변환
│ ├── convert_hwp_hancom.ps1 # Windows 한컴 COM 고속·일괄 변환
│ ├── build_hwpx.py # 템플릿+XML → .hwpx 조립
│ ├── fix_namespaces.py # 네임스페이스 후처리 (필수)
│ ├── clone_form.py # 양식 복제
│ ├── md2hwpx.py # 마크다운→HWPX 변환
│ ├── html2hwpx.py # K-Teacher 학생 활동지 HTML→디자인 XML→HWPX
│ ├── gonmun.py # 행정안전부 표준 기안문 생성기
│ ├── gonmun_lint.py # 공문서 작성법 자동 검수기
│ ├── bodojaryo.py # 정부 표준 보도자료 생성기(레퍼런스 복제)
│ ├── gyehoek.py # 공공기관 계획서 생성기(행안부 업무계획 복제)
│ ├── gyehoek_hook.py # PreToolUse 훅 — 계획서 제목/목차 포함 여부 강제 질문
│ ├── analyze_template.py # HWPX 심층 분석
│ ├── verify_hwpx.py # 품질 검증
│ ├── validate.py # 구조 검증
│ ├── finalize_hwpx.py # line cache removal, layout QA, Hancom open test
│ ├── fill_hwpx.py # 보존형 양식 채우기 + 머리말/꼬리말/쪽번호/표구조/수식 in-place
│ ├── secure_fill.py # 개인정보(PII) 비경유 양식 채우기
│ ├── hwpx_guard_hook.py # 배포 전 HWPX strict gate 보조 훅
│ ├── report_placeholder_hook.py # '브라더 공기관' 예시 보고서 전달 차단 훅
│ ├── text_extract.py # 텍스트 추출
│ ├── create_document.py # 문서 생성
│ ├── build_problem_answer_sheet.py # 문제지+답안지 2쪽 생성
│ └── office/ # unpack/pack 유틸리티
├── templates/ # 문서 템플릿
│ ├── base/ # 베이스 skeleton
│ ├── report/ # 보고서
│ ├── gonmun/ # 공문
│ ├── minutes/ # 회의록
│ ├── proposal/ # 제안서
│ └── government/ # 관공서 (컬러 배너/섹션 바)
├── assets/ # 레퍼런스 템플릿
└── references/ # 기술 문서
| 항목 | 한컴 COM | rhwp WASM |
|---|---|---|
| 텍스트·표 | 실제 한글 저장 엔진 | 구조 보존 회귀 테스트 |
| 이미지·도형·컨테이너 | 원본 재현 우선, 시각 점검 필요 | best effort, 시각 점검 필요 |
| 각주/미주·다단·머리말/꼬리말 | 원본 재현 우선, 시각 점검 필요 | best effort, 시각 점검 필요 |
| OLE 객체·수식 | 한컴 지원 범위 | 구조가 남아도 렌더링 보장 안 됨 |
- 모든 빌드 후
fix_namespaces.py필수 실행 .hwp의 변환·읽기·편집은 원본을 보존한 별도 HWPX를 만든 뒤 진행- 양식 복제 시
clone_form.py사용 (XML 직접 조작 금지) - 템플릿 간 스타일 ID 호환 불가 — 해당 템플릿 ID만 사용
mimetype은 첫 ZIP 엔트리,ZIP_STORED- After XML text replacement, remove
hp:linesegarraybefore delivery - For strict templates, split long table-cell prose and increase row height
- Use
validate.py --hancomon Windows when Hancom openability matters - 신청서·서식의 빈 필드 채우기는
fill_hwpx.py analyze → fill → verify → check --strict순서로 처리
- claw-hwp — vendored rhwp 런타임과 변환 호환성 패치 참고
- kordoc — 보존형 HWPX 양식 채우기와 ZIP 패치 설계 참고
- k-teacher-skills — MIT 디자인 팔레트와 카드형 시각 패턴 참고
MIT