모각에서 공유받은 hwpx.skill 패키지를 내 파이프라인에 붙이기
2026.05.25
📒 소개
지피터스 22기 강의자동화 첫 번째 모각에 참석하지 못했습니다.
아쉬움이 컸어요. 강의 준비 파이프라인을 만들어두긴 했지만, 막상 실제 제출 단계에서 걸리는 부분이 있었기 때문입니다.
제가 만든 /lesson-prep 파이프라인은 강의계획서를 Markdown으로 만들고, 교안은 PPTX로 자동 생성하는 흐름이었습니다. 여기까지만 보면 꽤 그럴듯했지만, 현실은 조금 달랐습니다.
학교나 센터에 제출할 때는 여전히 한컴 한글(.hwp/.hwpx) 양식을 요구하는 경우가 많았습니다.
결국 자동화로 만든 Markdown 내용을 다시 열고, 양식에 맞춰 손으로 옮겨 적어야 했습니다.
그때 도로시J 스터디장님이 카톡방에 올려주신 hwpx.skill이 눈에 들어왔습니다.
첫 번째 모각에는 참여하지 못했지만, 스터디 OT 때 hwpx.skill 에 대해서 미리 설명해주시고 모각에서 공유해주신 덕분에 제가 만들던 파이프라인의 빈칸을 채울 수 있겠다는 생각이 들었습니다.
“Markdown으로 만든 강의계획서를 HWP/HWPX 양식으로까지 자동 생성할 수 있지 않을까?”
이 질문에서 이번 작업이 시작됐습니다.
▶️ 진행 방법
1. 바로 코딩하지 않고, 먼저 그림부터 그리기
처음부터 코드를 고치지는 않았습니다.
외부에서 받은 hwpx.skill을 어디에 두고, 기존 파이프라인과 어느 범위까지 연결할지 먼저 정리했습니다.
Claude의 plan mode를 사용해 hwpx.skill 패키지를 분석했고, 다음 두 가지를 먼저 결정했습니다.
설치 위치: 사용자 전역
~/.claude/skills/다른 프로젝트에서도 재사용할 수 있도록 하기 위해서입니다.
연동 범위: 강의계획서만
교안은 이미 PPTX가 본체였기 때문에 제외했습니다.
이 단계가 생각보다 중요했습니다.
바로 코딩부터 시작했다면 “어디까지 자동화할 것인가?”라는 기준이 흐려졌을 것 같습니다.
2. 환경을 먼저 맞추기
작업을 진행하려고 보니 Python 환경부터 필요했습니다.
그래서 Windows에서 Python을 설치하고, 필요한 패키지를 한 번에 준비했습니다.
winget install Python.Python.3.12
pip install python-hwpx lxml pyhwp olefile six
그리고 hwpx.skill 압축을 아래 위치에 풀었습니다.
~/.claude/skills/hwpx/
이제 목표는 단순했습니다.
기존 파이프라인이 만든 강의계획서 Markdown을 읽고
제출용 한글 양식에 맞춰
사람이 손으로 옮긴 것처럼 자연스러운
.hwpx파일을 만드는 것
하지만 실제 작업은 단순하지 않았습니다 😅
3. 첫 번째 시도: Markdown을 그냥 HWPX로 바꾸기
처음에는 Markdown을 단순히 .hwpx로 변환해봤습니다.
파일은 만들어졌고, 열리기도 했습니다.
그런데 문제가 있었습니다.
요구하는 양식과 맞지 않음
표 구조가 다름
제출용 문서라기보다는 변환 결과물에 가까움
자동화는 됐지만, 실무에서 바로 쓰기는 어려웠습니다.
“파일이 생성된다”와 “제출 가능한 문서가 된다”는 전혀 다른 문제였습니다.
4. 두 번째 시도: 양식에 직접 채워 넣기
이번에는 빈 .hwp 양식을 기준으로 삼았습니다.
양식 안의 표 셀을 찾아서 텍스트를 채워 넣는 방식이었습니다.
처음에는 잘 되는 것처럼 보였습니다.
하지만 열어보니 “프로그램명” 옆 셀만 채워지고, 나머지는 비어 있었습니다.
원인을 찾아보니 일부 셀에는 텍스트 노드인 <hp:t>가 없었습니다.
즉, 겉보기에는 빈칸이지만, 프로그램 입장에서는 “텍스트를 넣을 자리”가 명확하지 않았던 것입니다.
이때부터 한컴 문서가 단순한 텍스트 파일이 아니라는 걸 실감했습니다.
5. 세 번째 시도: 실제 작성된 문서를 레퍼런스로 삼기
빈 양식만 보고는 한계가 있었습니다.
그래서 실제로 사람이 내용을 채워 넣은 레퍼런스 .hwp 파일을 분석했습니다.
그 문서에서 정확한 셀 스타일과 구조를 가져오자, 드디어 내용이 들어가기 시작했습니다.
그런데 또 다른 문제가 생겼습니다.
글자가 겹쳐 보였습니다.
처음에는 셀 높이 문제라고 생각했지만, 원인은 따로 있었습니다.
빈 셀에 남아 있던 라인 좌표 정보가 그대로 유지되면서 새 텍스트와 충돌하고 있었습니다.
해결 방법은 <hp:linesegarray>를 전부 제거하는 것이었습니다.
문제: 기존 빈 셀의 linesegarray 정보가 남아 글자 겹침 발생
해결: 셀 안의 <hp:linesegarray> 전수 제거
이걸 고치고 나니 글자 겹침 문제가 사라졌습니다.
6. 네 번째 시도: 표가 다음 페이지로 밀려나는 문제
글자 겹침을 해결하니 이번에는 페이지 배치 문제가 나타났습니다.
첫 페이지에는 제목만 있고, 정작 중요한 표는 두 번째 페이지로 밀려났습니다.
문서를 열자마자 “아, 이건 제출하기 어렵겠다”는 생각이 들었습니다.
원인은 표의 페이지 나눔 설정이었습니다.
pageBreak="TABLE" → pageBreak="CELL"
표 전체를 한 덩어리로 넘기지 않고, 셀 단위로 자연스럽게 이어지도록 바꾸자 페이지 밀림 문제가 해결됐습니다.
7. 다섯 번째 시도: 셀 높이 자동 계산하기
이제 파일도 열리고, 표도 제자리에 있고, 글자도 겹치지 않았습니다.
하지만 아직 사람이 만든 문서처럼 보이진 않았습니다.
셀 안의 내용이 너무 답답해 보이거나, 반대로 표가 페이지 중간에서 어색하게 끝나는 문제가 있었습니다.
그래서 콘텐츠 줄 수를 기준으로 셀 높이를 자동 계산하도록 바꿨습니다.
기본 높이: 1줄 기준 약 12mm
추가 줄: 줄당 약 6mm씩 증가
이 조정 이후에는 문서가 훨씬 자연스러워졌습니다.
드디어 “자동 생성 문서”가 아니라 “제출 가능한 문서”에 가까워졌습니다.
8. 재사용 가능한 CLI 도구로 묶기
한 번 성공했다고 끝내면 다음 강의 때 또 같은 고생을 하게 됩니다.
그래서 이번에 찾은 보정 로직을 모두 하나의 CLI 도구로 묶었습니다.
templates/fill_lesson_form.py
이 도구 안에는 다음 로직이 들어갔습니다.
헤더 단축
표 분할
셀 높이 자동 계산
<hp:linesegarray>제거강의계획서 JSON 데이터 반영
이제 다음 강의부터는 JSON 파일 하나만 바꾸면 같은 양식의 HWPX 강의계획서를 만들 수 있게 됐습니다.
{
"program_name": "예시 강의명",
"target": "수강 대상",
"goal": "강의 목표",
"sessions": [
{
"title": "1회차 주제",
"content": "주요 내용"
}
]
}
그리고 /lesson-prep 스킬에도 이 도구를 자동 호출하는 단계를 추가했습니다.
9. GitHub 비공개 저장소에 백업하기
마지막으로 파이프라인 전체를 GitHub 비공개 저장소에 백업했습니다.
자동화가 한 번 성공해도, 로컬 PC에만 있으면 불안했습니다.
다른 PC에서도 같은 흐름을 재현할 수 있어야 했습니다.
진행한 작업은 다음과 같습니다.
git init
git add .
git commit -m "Initial lesson-prep pipeline"
gh repo create --private --source=. --push
이후 .gitignore를 정리했습니다.
node_modules/
__pycache__/
*.pyc
package-lock.json
그리고 hwpx.skill은 skills/ 폴더로 옮겨 구조를 정리했습니다.
git mv hwpx.skill skills/hwpx.skill
skills/README.md도 추가해 어떤 skill을 왜 넣었는지 설명했습니다.
이렇게 해두니 나중에 다시 봐도 파이프라인 구조를 이해하기 쉬웠습니다.
🎁 결과와 배운 점
결과: Markdown에서 HWPX까지 이어지는 흐름 완성
이번 작업을 통해 강의 1건의 한글 강의계획서를 자동 생성할 수 있었습니다.
결과물은 다음과 같았습니다.
약 1.1MB 크기의
.hwpx파일 생성한컴 한글에서 바로 열림
사람이 손으로 만든 것과 거의 동일한 양식
다음 강의부터는 JSON 파일 하나만 바꾸면 재사용 가능
전체 파이프라인은 GitHub 비공개 저장소에 백업 완료
가장 좋았던 점은 “자동화의 마지막 10%”가 채워졌다는 것입니다.
기존에는 Markdown과 PPTX까지는 자동화됐지만, 제출용 한글 문서 앞에서 다시 수작업으로 돌아가야 했습니다.
이번에는 그 병목이 사라졌습니다.
배운 점 1: 못 간 모각도, 공유된 자료 덕분에 이어질 수 있다
첫 번째 누구보다 모각의 중요성과 효용성을 잘 알고 있어서 모각에 참석하지 못한 게 너무 아쉬웠습니다.
하지만 도로시J 스터디장님이 hwpx.skill을 카톡에 공유해주신 덕분에, 제가 만들던 파이프라인과 스터디의 흐름이 연결됐습니다.
그렇지만 스터디 OT에 참여하지 않았다면 hwpx.skill 이 카톡에 공유되어도 잘 몰라서 사용을 못했을 겁니다. 도로시J 스터디장님이 OT에서 미리 알려주셨던 거라 활용할 수 있었습니다.
모각에 참여했다면 더욱 쉽게 활용해 볼 수 있었겠지만 스터디장님의 공유가 저의 작업을 이어가게 만들었습니다.
이번 작업도 혼자 처음부터 만들었다면 훨씬 오래 걸렸을 것 같습니다.
다시 한번 스터디와 모각의 중요성을 느끼게 되었습니다.
배운 점 2: plan mode는 길을 잃지 않게 해준다
외부 skill을 파이프라인에 붙이는 작업은 생각보다 결정할 것이 많았습니다.
어디에 설치할지
어떤 프로젝트에서 쓸지
기존 파이프라인 어디에 끼울지
Markdown, PPTX, HWPX 중 무엇을 자동화 대상으로 삼을지
처음에 plan mode로 그림을 그린 덕분에 중간에 방향을 잃지 않았습니다.
바로 코딩했다면 아마 “일단 되게 만들기”에만 집중하다가, 재사용성과 구조 정리를 놓쳤을 것 같습니다.
배운 점 3: 한 번에 완벽한 코드는 거의 나오지 않는다
이번 작업은 한 번에 성공하지 않았습니다.
Markdown 변환은 됐지만 양식이 맞지 않았고
셀에 텍스트가 일부만 들어갔고
글자가 겹쳤고
표가 다음 페이지로 밀렸고
셀 높이가 어색했습니다
하지만 매번 한컴 한글에서 직접 열어보고, 문제를 확인하고, Claude에게 다시 설명했습니다.
내가 직접 확인한다 → 문제를 설명한다 → Claude가 원인을 추적한다 → 다시 열어본다
이 반복이 생각보다 빠른 길이었습니다.
AI에게 전부 맡기는 방식이 아니라, 제가 결과물을 보고 판단하는 역할을 해야 했습니다.
특히 HWPX처럼 눈으로 봐야 알 수 있는 문서 작업에서는 이 과정이 중요했습니다.
배운 점 4: 패키지 이름 하나도 그냥 넘어가면 안 된다
외부 패키지 이름도 시행착오가 있었습니다.
문서에서는 pyhwp5처럼 보였지만, 실제 PyPI에서는 pyhwp를 설치해야 하는 상황이 있었습니다.
Claude도 처음부터 정확히 맞히지는 못했습니다.
하지만 함께 에러를 보고, 패키지를 추적하고, 실제 설치 가능한 이름을 확인하면서 해결했습니다.
이 과정에서 느낀 건 명확했습니다.
AI는 빠르게 도와주지만, 최종 확인은 결국 내가 해야 한다.
❤️ 도움 받은 글
도로시J 스터디장님이 공유해주신
hwpx.skill기존
/lesson-prep파이프라인 작업 기록Claude Code plan mode와 실행 로그




"Markdown 강의계획서 → HWPX 자동 생성"의 빈칸을 짚으신 부분이 정말 현장 감각이에요. 학교·센터 제출 단계에서 손 작업으로 다시 옮기던 비효율을 정확히 캐치하셨네요. "바로 코딩하지 않고 plan mode로 설치 위치·연동 범위부터 결정"하신 접근이 단단합니다. 노련하신 유징이님 ㅎㅎ