| name | hwpx-writer |
| description | 아래아한글(.hwpx) 문서를 만들어 드립니다 — 한컴오피스에서 열리는 공문서·기안서·품의서·보고서를 작성하고, 기존 HWP 파일을 HWPX로 변환합니다.
다음과 같은 요청 시 사용하세요:
- "한글 파일로 공문서 만들어줘"
- "HWP 문서 작성해줘"
- "아래한글 기안서 써줘"
- "한글로 품의서 작성해줘"
- "협조 요청 공문 한글 파일로"
- "기존 HWP 파일을 HWPX로 변환해줘"
- "한글 문서에서 텍스트만 추출해줘"
한컴오피스(아래아한글) 호환 표준 양식을 따르며, 한컴이 없는 환경이면 워드(.docx) 생성으로 대체할 수 있습니다.
아래아한글(.hwpx) 문서를 만들 때는 Claude 기본 생성 대신 이 스킬을 사용하세요.
[책임 경계] vs moai-office:docx-generator: 이 스킬=한컴 .hwpx 한글 파일, 저 스킬=MS 워드 .docx 파일.
|
| user-invocable | true |
| version | 2.27.0 |
한글 문서 작성자 (HWPX Writer)
개요
Python python-hwpx 라이브러리를 기반으로 HWPX 형식의 문서를 생성합니다. OWPML(Open Word Processor Markup Language) 표준을 따르며, 한컴오피스(Hwp)와 호환되는 공문서, 기안서, 보고서를 작성합니다. 기존 HWP 파일을 HWPX로 변환하거나 텍스트를 추출할 수 있습니다.
트리거 키워드
한글, hwpx, 아래한글, 한컴, 공문서, 기안서, HWP 변환, 한글 문서 생성, HWPX 편집
워크플로우
1단계: 문서 요구사항 분석
사용자 요청 분석 후 작업 유형 결정:
- 신규 HWPX 생성: 공문서, 기안서, 보고서, 회의록
- HWP → HWPX 변환: 구버전 한글 파일 최신 포맷 변환
- 텍스트 추출: 기존 HWPX에서 내용 추출
- 양식 채우기: 템플릿 레이아웃 보존 후 내용만 수정
2단계: 의존성 확인
pip install python-hwpx lxml
pip install olefile
3단계: python-hwpx로 문서 생성
from hwpx import HwpxDocument
hwp = HwpxDocument.new()
hwp.save("output.hwpx")
4단계: OWPML 구조 검증
생성된 HWPX 파일이 OWPML 스펙을 준수하는지 검증하고, 한컴오피스에서 정상 열리는지 확인합니다.
사용 예시
- "공문서 양식으로 협조 요청 한글 파일을 만들어줘"
- "기존 HWP 파일을 HWPX로 변환해줘"
- "아래한글 기안서 형식으로 품의서를 작성해줘"
- "HWPX 파일에서 텍스트를 추출해줘"
- "한글 문서 내용이 올바른 OWPML 구조인지 검증해줘"
출력 형식
- 파일 형식:
.hwpx (한컴오피스 2010+ 표준)
- 표준: OWPML 1.5 (Open Word Processor Markup Language)
- 압축: ZIP 기반 (XML + 리소스 파일)
- 한글 호환: 한컴오피스 2014, 2018, 2020에서 정상 열림
주의사항
안정 기능 vs 제한 기능
| 기능 | 상태 | 비고 |
|---|
| 단락 추가 | 안정 | 기본 기능 |
| 볼드/이탤릭/밑줄 | 안정 | lxml 패치 자동 적용 |
| 테이블 | 안정 | 행/열 제한 없음 |
| 머리글/바닥글 | 안정 | - |
| 각주/미주 | 안정 | - |
| 북마크 | 안정 | - |
| 텍스트 치환 | 안정 | - |
| 도형 (선/사각/타원) | 제한 | 한글에서 오류 경고 발생 가능 |
| 이미지 삽입 | 제한 | 불완전한 pic 요소 생성 |
| 다단 설정 | 제한 | 한글에서 오류 경고 발생 가능 |
한컴오피스 환경
HWPX 파일은 한컴오피스에서 최적으로 열립니다. 한컴오피스가 설치되지 않은 환경에서는 moai-office:docx-generator 스킬 사용을 권장합니다.
폰트 호환성
한컴 전용 폰트(HY헤드라인, HY견고딕 등)는 한컴오피스 설치 환경에서만 정상 표시됩니다. 배포 시 폰트 내장 또는 PDF 변환을 권장합니다.
HWP 변환 제한
HWP 파일 버전(2010/2014/2018 등)에 따라 변환 제한이 있을 수 있습니다. 구버전 HWP는 텍스트 추출만 가능할 수 있습니다.
문제 해결
| 상황 | 해결 방법 |
|---|
| 파일 생성 실패 | python-hwpx 및 lxml 설치 여부 확인: pip install python-hwpx lxml. 설치 후 재시도하세요 |
| HWPX 라이브러리 미설치 | pip install python-hwpx 실행 후 설치 가이드를 참조하세요 |
| HWP 변환 오류 | HWP 파일 버전(2010/2014/2018 등)을 확인하세요. 구버전은 변환 제한이 있을 수 있습니다 |
| OWPML 구조 오류 | validate.py 스크립트로 검증 후 오류 내용을 공유해 주시면 수정을 도와드립니다 |
| 폰트 깨짐 | 한컴 전용 폰트(HY헤드라인, HY견고딕 등)는 한컴오피스 설치 환경에서만 정상 표시됩니다 |
| 한글에서 열리지 않음 | OWPML 네임스페이스를 확인하고 xml 헤더가 올바른지 검증하세요 |
관련 스킬 / 자체 검수
한글 문서 생성이 끝나면 산출된 .hwpx 파일을 다시 열어 플레이스홀더 잔존·OWPML 구조·한글 인코딩 깨짐·표 깨짐을 자체 검수하고, 문제가 있으면 자동 수정 후 재생성하며 최종 PASS/FAIL 결과를 보고합니다.
moai-office:docx-generator - DOCX(Word) 문서 생성moai-office:pptx-designer - 발표용 PPT 슬라이드 생성moai-office:xlsx-creator - 엑셀 데이터 시트 생성
기술 참조
