한글 파일로 내기

기관에 내는 문서는 아직 한글(HWP·HWPX) 파일을 원할 때가 많습니다. 앞 절까지 만든 계획서·제안서는 HTML이라, 인쇄하면 PDF가 되지만 한글 파일은 아닙니다. 이 절에서는 md-to-hwpx Skill로 같은 내용을 한글에서 여는 HWPX 파일로 만듭니다.

위니브가 이 Skill을 만든 과정

md-to-hwpx는 3월에 제가 Claude와 함께 만든 Skill입니다. 한글 파일을 다루는 프로그램과 설명 문서를 한 폴더에 모아 두고 이렇게 시작했습니다.

이 폴더에 있는 파일들은 mcp 파일들이야. skill을 만들기 위한 md 문서도 작성이 되어 있어.
이 문서를 기반으로 md 파일을 hwpx 파일로 전환하는 skill을 만들어줘.

처음 만든 파일은 한글에서 열리지 않았습니다. 그때 보낸 말입니다.

아니, 한글이 무한반복 도는데? 열리질 않아. 내가 준 파일 참고해서 만든거 맞지?
아주 민감한 파일이라 엄격하게 다뤄야해.

Claude가 제가 준 파일의 구조에 다시 맞춘 뒤에야 "이번에는 잘 열려!"가 나왔습니다. 그다음은 기능을 하나씩 더했습니다. 표가 깨지면 한글에서 1칸, 2×2, 3×3 표를 직접 만들어 견본으로 주었고, 굵게·기울임이 표시되지 않을 때도 한글로 견본 파일을 만들어 주었습니다.

이때 제가 한 일은 코드를 읽는 것이 아니었습니다. 한글에서 열어 보고, 무엇이 이상한지 말하고, 정답이 될 견본 파일을 만들어 주는 일이었습니다. 그 경험이 SKILL.md에 "참고 문서의 추측이 아니라 실제 한글 출력물의 XML 구조가 유일한 정답이다", "값 하나만 틀려도 한글이 무한 로딩한다"는 규칙으로 남았습니다.

받을 Skill과 안에 든 것

md-to-hwpx/
├── SKILL.md                   지원하는 마크다운, 작업 순서, 주의사항
├── scripts/md_to_hwpx.py      마크다운을 HWPX로 바꾸는 프로그램
└── references/hwpx-format.md  HWPX 파일 구조 자료(기능을 늘릴 때 본다)

• 되는 것: 제목(1~6단계), 문단, 글머리표·번호 목록, 굵게·기울임, 표(칸 안의 굵게·기울임 포함).
• 안 되는 것: 코드 블록, 인용문, 그림. 회사 서식(색 띠, 대제목 상자, 쪽 번호, 목차)도 옮기지 않습니다. 단순한 한글 문서를 만듭니다.

이 Skill은 회사 정보가 없어 『Claude Skill 에센셜』에서 이미 공개한 판과 같습니다. 바꾼 것은 Skill 설명(description)을 200자 안으로 줄인 것 하나입니다.

준비물

• md-to-hwpx.zip을 올립니다.
• 4장 1절의 사업계획서 대화. 대화를 닫았다면 받은 계획서 HTML을 새 대화에 첨부합니다.

요청하기

계획서를 만든 대화에 이어서 붙여 넣습니다.

방금 만든 사업계획서를 한글 파일(HWPX)로도 만들어 줘. 표는 표로 살려 줘.

Claude는 계획서 내용을 먼저 마크다운으로 옮겨 적고(사업계획서.md), 그 파일을 Skill의 프로그램으로 HWPX로 바꿨습니다. 답에는 이런 말이 붙었습니다.

• 표 5개(사업 개요, 시간표, 멘토·강사, 추진 일정, 소요 예산)가 모두 한글 표로 들어갔다. 다만 한글 프로그램에서 직접 열어 보지는 못했으니 열어서 확인해 달라.
• HTML의 세 줄 띠, 로마자 대제목 상자, 쪽 번호, 목차는 옮겨지지 않는다. 회사 표준 서식 그대로 내려면 HTML에서 PDF로 저장한 쪽이 낫다.
• 변환기가 표 칸 안의 줄바꿈을 지원하지 않아 산출 내역은 '/'로 이어 썼다.

Claude가 '열어 보지 못했다'고 한 곳은 사람이 엽니다. 저는 받은 파일을 한글 2022에서 열었습니다.

결과

파일은 바로 열렸고 표 5개도 그대로였습니다. 그런데 두 군데가 이상했습니다.

• 날짜가 '1. 11.'로 나왔습니다. 표지의 '2026. 11.'을 마크다운이 번호 목록('2026번째 항목')으로 읽어 '1.'로 바꾼 것입니다. 줄 맨 앞에 '숫자 + 마침표'가 오면 생기는 일입니다.
• 긴 문장이 한 줄 안에 눌려 글자가 겹쳤습니다. HWPX 파일에는 각 문단이 몇 줄로 나뉘는지 적어 두는 칸(linesegarray)이 있는데, 변환 프로그램이 모든 문단에 '한 줄'이라고 적어 둡니다. 한글은 그 값을 믿고 긴 문장을 한 줄에 욱여넣습니다. 3월에 다른 한글 양식을 채울 때도 "표 안에 한 줄로만 작성이 되어서 글자가 겹침현상이 크게 발생된 것이 보여"라며 다시 시킨 적이 있습니다(5장 1절).

같은 대화에서 이렇게 요청했습니다.

한글에서 열어 보니 긴 문장이 한 줄에 눌려 글자가 겹쳐 보이고, 표지 날짜가 '1. 11.'로 나와.
날짜는 '2026년 11월'로 고치고, 한글이 줄을 다시 나누도록 section0.xml의 linesegarray를 모두 빼고 다시 만들어 줘.

다시 받은 파일을 한글에서 열자 위 그림 아래쪽처럼 한글이 줄을 새로 나눴고 날짜도 바로 나왔습니다. 문서 내용과 표는 그대로입니다. Claude는 "마크다운을 고쳐 다시 변환하면 줄 정보가 다시 생기니 그때도 같은 처리를 해야 한다"고 덧붙였습니다.

두 번째 요청문에 낯선 낱말(section0.xml, linesegarray)이 들어 있지만 외울 필요는 없습니다. 증상을 말하면 Claude가 원인을 찾기도 하지만, 원인을 아는 경우에는 이름을 대 주는 편이 한 번에 맞습니다.

확인할 것

• 한글에서 열립니까? 열리지 않거나 멈추면 파일을 다시 만들어 달라고 하고, 어떤 메시지가 떴는지 그대로 알려 줍니다.
• 표 개수와 칸이 원래 문서와 같습니까? 이 실습이라면 표 5개입니다. 예산 표의 금액이 HTML 계획서와 같은지 봅니다.
• 날짜·번호가 바뀌지 않았습니까? 줄 맨 앞의 '2026. 11.' 같은 날짜는 번호 목록으로 바뀌기 쉽습니다. '2026년 11월'처럼 쓰게 합니다.
• 긴 문장이 한 줄에 눌려 있지 않습니까? 눌려 있으면 위의 두 번째 요청을 합니다.
• 제목 크기와 굵게 표시가 살아 있습니까? 회사 서식(글꼴, 색, 쪽 번호)이 필요하면 한글에서 스타일을 입히거나, 서식은 HTML→PDF 판으로 내고 한글 파일은 발주처가 편집용으로 받게 합니다.

다른 장과 나누는 일

md-to-hwpx는 내용을 받아 새 한글 파일을 만듭니다. 기관이 준 한글 양식의 빈칸을 채우거나 이미 있는 한글 문서를 고치는 일은 11장에서 한글 편집 프로그램(wedocs)을 Claude Desktop에 연결해서 합니다.

우리 회사로 바꾸려면

• 한글이 줄을 다시 나누도록 하는 처리를 매번 요청하기 번거로우면 Skill을 고쳐 둡니다. 저는 같은 파일에서 줄 정보 칸만 뺀 판을 한글 2022에서 열어 표와 문단이 그대로인 것을 확인했습니다. 다른 한글 판에서는 열어 보지 못했으니, 고친 Skill로 만든 파일을 회사에서 쓰는 한글로 꼭 열어 봅니다.

  md-to-hwpx의 scripts/md_to_hwpx.py가 linesegarray를 넣지 않도록 고쳐 줘.
  고친 프로그램으로 표가 있는 시험 문서를 하나 만들어 주고, Skill 폴더를 md-to-hwpx.zip으로 묶어 줘.
  

• 회사 문서의 기본 글꼴·글자 크기를 바꾸고 싶으면 한글에서 그 서식으로 만든 짧은 견본 HWPX를 첨부하고 "이 견본과 같은 글꼴·크기가 나오게 md-to-hwpx를 고쳐 줘. 견본 파일의 header.xml 구조를 그대로 따라야 한다"고 요청합니다. 3월에 이 Skill을 만들 때처럼, 정답 견본을 사람이 한글로 만들어 주는 것이 가장 빠릅니다.