AI에게 한글 문서 작업을 부탁할 때 사용하는 HWP·HWPX 통합 스킬입니다.
문서 읽기, 기존 파일 수정, 서식 채우기, 템플릿 재사용, PDF 미리보기를 하나의 hwp 스킬로 제공합니다. Codex, Claude Code, OpenClaw 등 SKILL.md 형식의 스킬을 사용하는 에이전트에 설치할 수 있습니다.
특정 사용자, 회사, 문서, 봇 계정에 종속되지 않습니다. 자신의 문서와 에이전트 환경에 맞춰 사용할 수 있습니다.
- 할 수 있는 일
- 설치 전 준비
- 설치
- 처음 사용하기
- 요청 예시
- 서식을 유지하는 방식
- PDF 내보내기
- 업데이트와 기존 스킬 정리
- 문제 해결
- 직접 스크립트 실행하기
- 개발과 검증
- 구성과 라이선스
| 작업 | 사용 예시 |
|---|---|
| 문서 읽기·구조 분석 | 본문 추출, 표와 셀 병합 상태 확인 |
| 기존 문서 수정 | 날짜·이름·문구 변경, 담당 내용 일치 여부 확인 |
| 표 편집 | 셀 내용 수정, 행·열 추가, 셀 병합·분할, 정렬·테두리 조정 |
| 글자·문단 서식 | 글꼴·크기·굵기, 문단 간격, 줄 간격 조정 |
| 페이지 배치 | 제목이 페이지 끝에 혼자 남는 문제, 다음 페이지의 제목 간격 조정 |
| 문서 생성·서식 채우기 | 새 문서 작성, 기존 신청서의 대응하는 칸에 내용 입력 |
| 템플릿 재사용 | 프로젝트별 서식 저장, 목록 확인, 새 문서에 재사용 |
| 문서 요소 편집 | 이미지·도장·서명·차트·수식·머리말·꼬리말 관련 작업 |
| PDF 미리보기 | 수정한 페이지의 줄바꿈·표·간격 확인 |
.hwp와 .hwpx는 내부 구조가 다릅니다. 파일에 맞는 편집 경로를 선택하며, 모든 기능이 두 형식에서 똑같이 지원되는 것은 아닙니다. 세부 지원 범위는 스킬 지침과 연결된 연산 문서에서 확인할 수 있습니다.
문서 비교, Markdown 변환, Windows 한컴 자동화 등은 필요에 따라 대체 도구를 사용합니다. 기본 설치에 모든 대체 도구를 설치할 필요는 없습니다.
| 항목 | 필요한 경우 |
|---|---|
| 스킬을 지원하는 AI 에이전트 | AI에게 자연어로 문서 작업을 요청할 때 |
| Git | Git으로 저장소를 복제하거나 업데이트할 때. ZIP 설치에는 불필요 |
| Python 3.9 이상 | 설치 스크립트와 일부 문서 도구를 실행할 때 |
| Node.js 18 이상 | 기본 문서 분석·편집 스크립트를 실행할 때 |
| Node.js 22 이상 + Chrome/Chromium | 포함된 PDF 미리보기 내보내기를 사용할 때 |
핵심 Node.js 라이브러리는 저장소에 포함되어 있어, 일반 사용자는 npm install을 실행할 필요가 없습니다.
Windows의 Python 실행 명령이 python3이 아니라 python 또는 py -3이라면 아래 설치 명령에서 그 부분만 바꾸세요. 원본 한컴 앱을 통한 작업이나 별도 변환 도구에는 해당 도구의 설치·접근 권한이 추가로 필요합니다.
터미널에서 다음 명령을 실행합니다.
git clone https://github.com/nathankim0/easy-hwp.git
cd easy-hwp
python3 scripts/install.py기본 설치 위치는 ~/.codex/skills/hwp입니다. ~는 현재 사용자의 홈 폴더를 뜻합니다.
설치가 끝나면 새 에이전트 세션을 시작하세요. 에이전트가 해당 스킬 폴더를 탐색할 수 있어야 합니다.
Git을 사용하지 않으려면 릴리스 페이지에서 easy-hwp-v2.0.0.zip을 내려받아 압축을 풀고, 해당 폴더에서 python3 scripts/install.py를 실행하세요.
저장소를 복제한 뒤 easy-hwp 폴더에서 원하는 설치 명령을 실행합니다.
# Claude Code
python3 scripts/install.py --dest ~/.claude/skills/hwp
# OpenClaw
python3 scripts/install.py --dest ~/.openclaw/skills/hwp사용 중인 런타임에 별도 스킬 디렉터리가 있다면 --dest에 그 경로를 지정하세요. 공백이 있는 경로는 따옴표로 감쌉니다.
python3 scripts/install.py --dest "/원하는 경로/skills/hwp"Claude Code 안에서 아래 명령을 실행합니다.
/plugin marketplace add nathankim0/easy-hwp
/plugin install easy-hwp@easy-hwp
직접 복사하는 설치 방식과 플러그인 설치 방식 중 하나를 선택하세요. 같은 런타임에 두 방식으로 설치하면 동일한 스킬이 중복 발견될 수 있습니다.
기존 폴더가 있으면 설치 스크립트는 교체를 중단합니다. 업데이트하려면 --replace를 붙입니다.
python3 scripts/install.py --replace이전 설치는 ~/.local/share/easy-hwp/backups/<시각>/hwp에 백업됩니다. 백업 경로는 실행 결과에도 표시됩니다. 교체 대상은 지정한 스킬 폴더이며, 작업 중인 사용자 문서를 교체하는 명령이 아닙니다.
- 설치 후 새 에이전트 세션을 시작합니다.
- 작업할 HWP 또는 HWPX 파일을 첨부하거나, 에이전트가 접근할 수 있는 파일 경로를 알려줍니다.
- 기준 파일, 수정할 내용, 결과 파일 이름을 함께 요청합니다.
- 결과 문서를 열어 수정한 부분과 페이지 배치를 확인합니다.
처음에는 아래처럼 요청하면 됩니다.
첨부한 계획안.hwp를 기준으로 수정해줘.
행사 날짜를 2027. 5. 10.으로 바꾸고, 제목의 연도도 2027년으로 바꿔줘.
표 구조와 나머지 내용은 유지해줘.
결과는 계획안_수정.hwp로 저장하고, 수정한 페이지의 서식도 확인해줘.
여러 파일을 함께 주는 경우에는 어느 파일이 수정 대상인지 명확히 적으면 좋습니다.
현재안.hwp를 수정 대상으로 사용해줘.
지난해안.hwp는 활동 설명만 참고해줘.
지난해 날짜나 담당자는 가져오지 말고, 현재안의 표와 서식은 유지해줘.
별도의 /hwp-analyze, /hwp-fill, /hwp-template 스킬을 설치할 필요 없이 통합 hwp 스킬에서 요청할 수 있습니다.
현재 일정표의 준비 일정과 본 행사 일정을 모두 1주 뒤로 옮겨줘.
요일도 확인해줘. 다른 맥락의 날짜는 그대로 유지해줘.
찬양 인도 담당만 김민준으로 바꾸고, 특송 담당은 유지해줘.
본문과 봉사 담당표가 서로 일치하는지도 확인해줘.
표의 바깥 테두리와 내부 선을 같은 검정 실선 두께로 통일해줘.
셀 배경색과 병합 구조는 유지하고, 셀 내용을 수직 가운데 정렬해줘.
본문 글꼴을 하나로 통일하되 제목과 표 머리글의 굵기는 유지해줘.
‘준비 사항’ 제목이 앞 페이지 마지막에 혼자 남아 있어.
제목과 내용을 다음 페이지로 함께 넘기고, 제목 위에 적당한 여백을 줘.
앞뒤 페이지에 빈 페이지가 생기지 않았는지 확인해줘.
신청서.hwpx에 내용.md를 대응하는 항목별로 입력해줘.
셀 병합과 글자 서식은 유지해줘.
대응하는 칸이 불분명한 항목은 임의로 넣지 말고 알려줘.
결과는 신청서_작성.hwpx로 저장해줘.
비공개 프로필에서 주민등록번호·연락처·계좌 등을 가져오는 작업에는 secure-fill 경로를 사용합니다. 프로필 원문을 대화에 출력하지 않고 내부에서 읽어 채우며, 확인 결과는 마스킹합니다. 결과 문서에는 입력한 개인정보가 포함됩니다.
수정 작업은 최신 승인 파일을 기준으로 필요한 부분만 변경합니다. 이름 하나를 바꾼다고 해당 인물의 모든 업무를 자동으로 다른 사람에게 넘기거나, 미정인 날짜를 임의로 확정하지 않습니다.
반복 편집에서 발생하기 쉬운 문제도 다음과 같이 다룹니다.
| 문제 | 처리 방식 |
|---|---|
| 새 이름이나 줄바꿈이 옛 위치에 표시됨 | 변경한 문단의 저장된 줄 배치 정보를 비워 다시 배치하도록 함 |
| 셀 분할 후 데이터 칸이 머리글 색으로 바뀜 | 분할 대상 셀의 서식을 상속 |
| 제목을 넘겼더니 빈 페이지가 생김 | 페이지 나눔과 간격을 함께 처리하고 반복 적용 시 중복 방지 |
| 본문의 두 항목이 한 줄로 이어짐 | 필요하면 실제 문단으로 분리 |
| 글자나 표 선의 크기 단위를 혼동함 | pt, mm, HWPUNIT을 구분해서 적용 |
| 한글 파일 경로 중간에 줄바꿈이 들어감 | 실제 파일 경로를 확인하고 CR/LF가 포함된 경로는 거부 |
| 여러 편집 중 일부가 실패함 | 임시 복사본에서 편집하고, 실패하면 기존 출력 파일 보존 |
줄바꿈을 넣어도 셀 높이가 부족하면 글자가 잘릴 수 있습니다. 수정한 표는 셀 높이, 정렬, 병합 상태까지 함께 확인합니다.
저장 성공과 서식 검증은 별개입니다. 텍스트와 표 구조를 다시 읽고, 변경한 페이지와 앞뒤 페이지를 시각적으로 확인하는 절차를 포함합니다. 복잡한 문서는 한컴 앱에서도 확인하는 것이 좋습니다.
수정한 문서를 PDF로도 만들어줘.
표 테두리, 줄바꿈, 제목 위치를 확인하고 HWP와 PDF를 함께 저장해줘.
두 가지 경로가 있습니다.
| 경로 | 특징 |
|---|---|
| 원본 한컴 앱의 PDF 내보내기 | 원본 앱에서 보이는 서식을 확인하고 내보낼 때 우선 사용 |
포함된 render-pdf.mjs |
한컴 앱 없이 로컬 브라우저와 미리보기 엔진으로 PDF 생성 |
포함된 도구의 PDF는 이미지 기반입니다. 텍스트 검색·선택·복사를 제공하지 않으며, 한컴 앱과 글꼴이나 페이지 배치가 다를 수 있습니다. 원본과 같은 출력이 필요한 제출 문서는 한컴 앱의 결과를 확인하세요.
브라우저 실행 파일이 자동 탐색되지 않으면 HWP_BROWSER를 설정합니다.
# macOS / Linux: 실제 설치 경로로 바꾸세요.
export HWP_BROWSER="/실제/브라우저/실행파일"# Windows PowerShell: 실제 설치 경로로 바꾸세요.
$env:HWP_BROWSER = "C:\실제\브라우저\chrome.exe"파일 전송은 사용하는 에이전트의 기존 첨부·메신저 기능으로 처리합니다. easy-hwp에는 봇 토큰이나 수신자 정보가 포함되어 있지 않습니다. 전송을 요청했다면 실제 전달 결과까지 확인하도록 안내합니다.
직접 설치한 경우, 복제한 저장소에서 업데이트한 뒤 다시 설치합니다.
cd easy-hwp
git pull --ff-only
python3 scripts/install.py --replace기본 위치 외에 설치했다면 처음과 같은 --dest를 지정하세요. 여러 런타임에 복사 설치했다면 각 설치본을 업데이트해야 합니다. 플러그인으로 설치했다면 해당 런타임의 플러그인 업데이트 기능을 사용하세요.
ZIP으로 설치했다면 새 릴리스 ZIP을 내려받아 압축을 풀고, 그 폴더에서 같은 설치 명령에 --replace를 붙여 실행하세요. 버전별 변경 사항은 패치노트에서 확인할 수 있습니다.
기존 hwp, rhwp-edit 등 전용 스킬과 함께 설치되어 있다면 기능과 탐색 경로를 확인한 뒤 중복 설치본을 정리하세요. 이 프로젝트에는 통합 진입점 하나만 있습니다. 설치 스크립트가 다른 이름의 스킬을 자동 삭제하지는 않습니다.
| 증상 | 확인할 것 |
|---|---|
| 에이전트가 스킬을 찾지 못함 | --dest가 해당 런타임의 탐색 경로인지 확인하고 새 세션 시작 |
destination exists |
기존 설치를 교체할 경우 --replace 사용 |
node 또는 Python 명령을 찾지 못함 |
실행 파일 설치와 PATH 확인. Windows는 python 또는 py -3도 확인 |
PDF에서 WebSocket 관련 오류 |
Node.js 22 이상인지 node --version으로 확인 |
| 브라우저를 찾지 못함 | Chrome/Chromium 설치와 HWP_BROWSER의 실행 파일 경로 확인 |
| 파일을 찾지 못함 | 실제 파일명·경로 확인. 공백은 따옴표로 감싸고 파일명에 줄바꿈을 넣지 않기 |
| 셀 내용이 잘리거나 줄이 겹침 | 줄바꿈, 셀 높이, 문단 간격 확인 후 다시 렌더링 |
| PDF와 한컴에서 모양이 다름 | 사용한 글꼴과 미리보기 엔진의 차이 확인. 최종 제출용은 한컴에서 확인 |
| 병합·행 추가 후 엉뚱한 칸이 바뀜 | 구조 변경 후 표를 다시 분석해 좌표 갱신 |
| 특정 편집이 지원되지 않음 | 파일 형식과 연산 지원 범위 확인. 지원되지 않는 작업을 완료로 간주하지 않기 |
일반 사용자는 AI에게 요청하면 됩니다. 직접 연산을 실행하려면 저장소 루트에서 스킬 폴더로 이동합니다. 아래 파일 경로는 자신의 파일 경로로 바꾸세요.
cd plugins/easy-hwp/skills/hwp
# 본문을 Markdown으로 확인
node scripts/extract_text.js --format markdown "/문서/계획안.hwp"
# 표 위치와 셀 내용을 JSON으로 확인
node scripts/extract_text.js --inspect --with-cell-text "/문서/계획안.hwp"
# 연산 파일에 적힌 순서대로 수정
node scripts/edit.mjs "/문서/계획안.hwp" "/문서/계획안_수정.hwp" operations.json
# 수정본의 PDF 미리보기 생성
node scripts/render-pdf.mjs "/문서/계획안_수정.hwp" "/문서/계획안_수정.pdf"operations.json은 연산 배열입니다. 예를 들어 바이너리 HWP의 한 셀에 두 줄의 내용을 넣으려면 다음과 같이 작성합니다.
[
{
"type": "set_cell_text",
"section": 0,
"para": 4,
"control": 0,
"row": 1,
"col": 1,
"text": "첫 줄\n둘째 줄"
}
]위 좌표는 예시입니다. 반드시 자신의 문서를 분석한 결과로 바꾸세요. HWP 분석 결과의 sec, para, ctrl은 연산의 section, para, control에 대응합니다. 좌표는 0부터 시작합니다. HWPX 연산은 별도 지원 문서를 확인하세요.
셀 병합·분할처럼 구조가 달라지는 연산 후에는 다시 분석해야 합니다. 입력과 출력의 확장자는 유지해야 하며, 편집 명령은 파일 형식 변환을 대신하지 않습니다. 출력 파일은 연산과 재읽기에 성공한 뒤 교체되므로, 최종본으로 사용하기 전 시각 검증도 수행하세요.
저장소 루트에서 실행합니다.
node tests/regression.mjs회귀 테스트는 임시 폴더에 합성 문서를 만들고 다음을 확인합니다.
- 셀 줄바꿈 후 오래된 줄 배치 정보가 남지 않는지
- 셀 분할 시 대상 셀의 스타일을 이어받는지
- 물리적인 테두리 두께가 올바른 값으로 변환되는지
- 본문 문단 분리와 반복적인 제목 페이지 배치가 정상인지
- pt 단위와 문단 배치 플래그가 올바르게 적용되는지
- 실패한 편집이 입력 파일이나 기존 출력 파일을 손상시키지 않는지
- 줄바꿈이 포함된 파일 경로를 거부하는지
실제 사용자 문서나 개인정보는 테스트에 사용하지 않습니다. 이 테스트가 모든 한컴 문서의 호환성을 보장하는 것은 아닙니다. 표·서식·페이지 배치 관련 변경은 렌더링한 페이지도 확인하세요.
easy-hwp/
├── README.md 사용자 안내
├── scripts/install.py 설치·백업 교체
├── tests/regression.mjs 합성 문서 회귀 테스트
└── plugins/easy-hwp/skills/hwp/
├── SKILL.md 에이전트 작업 지침
├── scripts/ 분석·편집·미리보기 도구
├── references/ 기능별 상세 문서
└── themes/ 문서 스타일 참고 자료
더 자세한 기능별 문서:
- 스킬 사용 지침
- 편집 연산과 보안 서식 채우기
- HWPX 편집 연산
- 서식·페이지 배치와 파일 전달 검증
- 신청서·Windows 한컴·템플릿
- kordoc를 이용한 분석·비교·변환
- 대체 텍스트 편집 CLI
프로젝트는 MIT 라이선스로 배포합니다. 통합한 구성 요소의 출처는 NOTICE, 포함된 외부 라이브러리의 라이선스는 vendor 안내에서 확인할 수 있습니다.