HWP/HWPX 문서 통합 스킬 - 한글 문서 자동화 에이전트

노션 AI에서 HWP/HWPX 문서 생성·변환·읽기·양식 채우기를 처리하는 스크립트 기반 에이전트 스킬 소개입니다.

Agent-Skill

1000쌤

Jun 28, 2026

원작자 및 라이선스

이 노션 스킬은 아래 오픈소스 Claude 스킬을 노션용으로 수정·재배포한 파생물입니다. 모두 자유로운 수정·재배포가 허용되며(고지 유지 조건), 원작자분들께 감사를 전합니다.

원작 스킬: jkf87 / hwpx-skill — MIT 라이선스
HWP→HWPX 변환 엔진: jkf87 / hwp2hwpx-python-refactor — Apache-2.0 라이선스
양식 채우기 설계 참고: chrisryugj / kordoc — MIT 라이선스

📌

한글 문서 작업을 노션 AI 안에서 자동화하고 싶다면, HWPX 스킬이 필요합니다.

HWP/HWPX 문서는 일반 텍스트와 달리 ZIP 패키지와 XML 구조를 함께 다뤄야 합니다. 이 스킬은 한글 문서 생성, 변환, 읽기, 양식 채우기, 공문·기안문 작성까지 스크립트 기반으로 처리하도록 정리한 에이전트 스킬입니다.

이 글에서 다루는 내용 ⏳ 읽기 4분

HWPX 문서 작업이 일반 글쓰기와 다른 이유
이 스킬로 처리할 수 있는 작업
ZIP 패키지 방식으로 스킬을 관리하는 이유
스킬 복제 후 사용하는 방법

🔗

스킬 페이지 복제하기

아래 링크를 열어 스킬 페이지를 복제한 뒤, 내 워크스페이스의 SKILLS 데이터베이스나 원하는 위치에 보관해두면 됩니다.

HWP/HWPX 문서 통합 스킬 복제하기

HWPX 문서 작업은 왜 스크립트가 필요할까?

한글 문서 작업은 겉으로 보기에는 문장과 표를 다루는 일처럼 보이지만, 실제 .hwpx 파일은 여러 XML 파일이 묶인 구조입니다. 그래서 단순히 AI가 본문을 잘 쓴다고 해서 바로 안정적인 한글 파일이 만들어지는 것은 아닙니다.

문서 구조가 조금만 깨져도 파일이 열리지 않거나, 빈 페이지로 보이거나, 표와 서식이 망가질 수 있습니다. 특히 공문, 기안문, 신청서, 보고서처럼 형식이 중요한 문서는 결과물이 실제 한컴오피스에서 열리고 유지되는지가 핵심입니다.

그래서 이 스킬은 LLM이 임의로 XML을 작성하는 방식이 아니라, 정해진 스크립트를 우선 사용하도록 구성했습니다.

이 스킬로 할 수 있는 일

HWP/HWPX 문서 통합 스킬은 다음 작업을 처리하도록 설계했습니다.

HWP 파일을 HWPX로 변환하기
HWPX 파일 읽기와 텍스트 추출
마크다운·텍스트를 HWPX 문서로 변환하기
기존 HWPX 문서 일부 수정하기
신청서·양식의 빈칸 채우기
공문·기안문 작성 및 형식 검수
보고서·회의록·제안서 형태의 한글 문서 만들기
문제지와 답안지 형태의 문서 생성하기

핵심은 요청을 먼저 분류하는 것입니다. .hwp 파일이면 HWPX 변환부터 시작하고, .hwpx 파일이면 문서 구조를 먼저 확인합니다. 텍스트나 마크다운만 주어진 경우에는 새 문서 생성 흐름을 따릅니다.

스킬은 어떻게 작동할까?

이 스킬은 크게 세 단계로 움직입니다.

1. 입력 유형 확인

먼저 사용자가 제공한 파일과 요청을 확인합니다.

.hwp 파일인지
.hwpx 파일인지
텍스트·마크다운인지
공문·기안문처럼 형식 검수가 필요한 문서인지
기존 양식의 빈칸을 채우는 작업인지

입력 유형에 따라 적용해야 할 스크립트와 검수 기준이 달라집니다.

2. 작업 유형별 스크립트 실행

문서 생성, 변환, 텍스트 추출, 양식 복제, 필드 채우기 등 작업별로 정해진 스크립트를 실행합니다. 이 과정에서 AI는 문서 구조를 임의로 뜯어고치지 않고, 스킬에 포함된 절차를 기준으로 움직입니다.

이 방식은 결과를 안정적으로 반복해야 하는 작업에 특히 유리합니다. 같은 입력에 대해 같은 방식으로 처리되기 때문에, 매번 다른 형태의 문서가 나오는 문제를 줄일 수 있습니다.

3. 최종 검수

HWPX 파일은 만들어졌다고 끝이 아닙니다. 실제로 열릴 수 있는지, 필수 구조가 유지되는지, 표와 이미지가 손상되지 않았는지 확인해야 합니다.

이 스킬은 결과물을 전달하기 전 검수 단계를 반드시 거치도록 설계했습니다. 문서 자동화에서 가장 중요한 부분은 생성 자체보다 깨지지 않는 결과물을 만드는 것이기 때문입니다.

왜 ZIP으로 첨부했을까?

스크립트 기반 스킬은 본문 지침만으로는 충분하지 않습니다. 실제로 실행할 .py 파일, 템플릿, 검증 스크립트, 참고 자료가 함께 있어야 합니다. 그러나 노션은 개별 스크립트 파일 업로드를 지원하지 않기에 zip으로 묶어 데이터베이스에 수록하였습니다. 실제 동작은 zip파일 압축 해제 → 스크립트 실행 순으로 이루어집니다.

스킬 본문은 실행 절차를 설명합니다.
ZIP 파일은 실제 실행에 필요한 스크립트와 레퍼런스를 담습니다.
에이전트는 본문을 읽고, 첨부 패키지의 스크립트를 확인한 뒤 작업을 수행합니다.

이렇게 분리해두면 스킬 본문이 지나치게 길어지지 않고, 스크립트 파일도 한 번에 관리할 수 있습니다.

사용 방법

1. 스킬 복제

상단의 복제 링크를 열어 스킬 페이지를 내 워크스페이스로 복제합니다. 복제 후에는 본문과 첨부 ZIP 파일이 함께 있는지 확인해주세요.

2. 노션 AI에 스킬 멘션

한글 문서 작업이 필요한 페이지나 파일을 열고, 노션 AI에게 스킬을 멘션해 요청합니다.

예시:

@[SKILL]_hwpx-skill_한컴HWPX문서통합 멘션한 스킬을 이용해서

이 HWPX 양식의 빈칸을 채워줘
이 HWP 파일을 HWPX로 변환하고 내용 요약해줘
공문 형식으로 기안문 만들어줘

3. 결과 파일 확인

생성·변환·편집된 파일은 반드시 열림 여부와 구조 검수를 거친 뒤 사용하는 것이 좋습니다. 특히 학교 행정 문서나 외부 제출 문서는 최종 확인을 한 번 더 해주세요.

이런 분께 추천합니다

한글 문서 양식을 자주 작성하는 교사
공문·기안문·보고서 초안을 반복해서 만드는 분
HWP/HWPX 파일을 읽고 정리하는 작업이 많은 분
한글 문서 자동화를 노션 AI 안에서 처리하고 싶은 분
단순 글쓰기보다 실제 파일 생성까지 이어지는 에이전트 스킬이 필요한 분

정리

HWP/HWPX 문서 통합 스킬은 노션 AI를 글쓰기 도구에서 실제 문서 처리 에이전트로 확장하기 위한 예시입니다.

AI는 요청을 이해하고 작업 흐름을 판단합니다. 스크립트는 문서 구조를 안정적으로 처리합니다. 이 둘을 스킬로 묶어두면, 복잡한 한글 문서 작업도 반복 가능한 절차로 만들 수 있습니다.

HWPX 문서를 자주 다룬다면, 이 스킬을 복제해두고 필요한 작업마다 멘션해서 사용해보세요.

그리드 기반 PPT 생성 하네스 스킬 - 24 아키타입 PPT 자동화 노션 갤러리 커버 자동 생성 웹앱 - Notion Gallery Cover 사용법