한컴오피스 HWPX 문서를 AI 코딩 에이전트에서 다룰 수 있게 해주는 스킬입니다.
python-hwpx API를 쓰면 버그가 많아서, XML을 직접 건드리는 방식을 택했습니다. 덕분에 기존 문서의 서식이나 구조를 거의 그대로 유지하면서 내용만 갈아끼울 수 있습니다.
원본 HWPX 파일을 넣으면 스타일, 표 구조, 셀 병합, 여백까지 분석해서 구조를 보존한 채 내용만 바꿔줍니다. 원본이 없으면 공문, 보고서 같은 내장 템플릿으로 새 문서를 만들 수도 있고요. 다 만들고 나면 page_guard.py가 원본 대비 페이지 수가 달라졌는지 자동으로 잡아냅니다.
OWPML 표준 XML을 직접 다루기 때문에 charPr, paraPr 단위로 서식을 제어할 수 있습니다. Claude Code, Cursor, Codex CLI에서 모두 동작합니다.
이 저장소에는 Claude Code, Codex, Gemini CLI, Cursor 네 가지 호스트 모두를 위한 플러그인 매니페스트가 포함되어 있습니다. 각 도구의 기본 플러그인 설치 방법을 사용하면 됩니다.
git clone https://github.com/fucking-hwp/hwpxskill.git
/plugin install hwpx
또는 로컬에서 바로 사용하려면:
# 이 프로젝트에서만 cp -r hwpxskill/.claude-plugin .claude-plugin # 어디서든 (전역) cp -r hwpxskill ~/.claude-plugin/hwpx
cursor.com/marketplace/publish 에 제출되어 있습니다.
로컬에서 바로 쓰려면:
cp -r hwpxskill/.cursor-plugin .cursor-plugin
.agents/plugins/marketplace.json 기반으로 Codex 플러그인 설정에 추가하면 됩니다.
gemini extensions install https://github.com/fucking-hwp/hwpxskill
로컬에서 테스트할 때:
gemini extensions link ./hwpxskill
아래 명령은 모두 저장소 루트(hwpxskill/)에서 실행합니다.
템플릿 골라서 바로 생성. 원본 파일 없을 때 씁니다.
python3 skills/hwpx/scripts/build_hwpx.py --template gonmun --output result.hwpx
HWPX를 풀고, XML 고치고, 다시 묶습니다.
python3 skills/hwpx/scripts/office/unpack.py document.hwpx ./unpacked/
# XML 수정
python3 skills/hwpx/scripts/office/pack.py ./unpacked/ edited.hwpx문서에서 텍스트만 뽑습니다. 표도 포함되고, 마크다운으로도 뽑을 수 있습니다.
python3 skills/hwpx/scripts/text_extract.py document.hwpx --format markdown
ZIP 구조, XML 유효성, mimetype 위치 같은 걸 점검합니다.
python3 skills/hwpx/scripts/validate.py result.hwpx
이게 핵심입니다. 원본 문서를 분석해서 스타일과 구조를 통째로 가져온 뒤, 내용만 갈아끼웁니다. HWPX 파일을 첨부하면 이 흐름이 자동으로 돌아갑니다.
# 분석 python3 skills/hwpx/scripts/analyze_template.py reference.hwpx \ --extract-header /tmp/ref_header.xml \ --extract-section /tmp/ref_section.xml # 빌드 python3 skills/hwpx/scripts/build_hwpx.py \ --header /tmp/ref_header.xml \ --section /tmp/new_section0.xml \ --output result.hwpx # 검증 + 페이지 가드 python3 skills/hwpx/scripts/validate.py result.hwpx python3 skills/hwpx/scripts/page_guard.py --reference reference.hwpx --output result.hwpx
| 템플릿 | 용도 | 특징 |
|---|---|---|
| base | 기본 골격 | 최소 스타일, 빈 문서 시작점 |
| gonmun | 공문서 | 기관명, 수신처, 시행일자, 연락처 |
| report | 보고서 | 섹션 헤더, 들여쓰기, 체크박스 |
| minutes | 회의록 | 섹션 라벨, 테두리 구분 |
| proposal | 제안서 | 색상 헤더, 번호 뱃지 |
- Python 3.10 이상
- lxml (
pip install lxml) - 가상환경 권장
| 스크립트 | 하는 일 |
|---|---|
build_hwpx.py |
템플릿 + XML 조합해서 HWPX 생성 |
analyze_template.py |
레퍼런스 HWPX 분석 |
office/unpack.py |
HWPX를 디렉토리로 풀기 |
office/pack.py |
디렉토리를 HWPX로 묶기 |
validate.py |
HWPX 구조 검증 |
page_guard.py |
원본 대비 페이지 수 변동 감지 |
text_extract.py |
텍스트 추출 |
스타일 ID 체계, XML 구조 규칙, 템플릿별 charPr/paraPr 매핑 같은 건 SKILL.md에 다 정리되어 있습니다.