hwpx-skill
A skill that creates and edits HWPX documents, converts HWP, and builds official letters and reports from a JSON spec
- 304 ★ on the repository
- Last commit
Extended access
Why this level
- The agent runs Python scripts and, on Windows, PowerShell with `-ExecutionPolicy Bypass` to talk to Hancom Office
- The `--break-system-packages` flag in the install command writes packages into the system Python
- The skill reads and rebuilds documents, which may hold official and personal data
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/hwpx-skillDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The agent runs Python scripts and, on Windows, PowerShell with `-ExecutionPolicy Bypass` to talk to Hancom Office
- The `--break-system-packages` flag in the install command writes packages into the system Python
- The skill reads and rebuilds documents, which may hold official and personal data
This is third-party code. Review the repository files before installing.
What it does
hwpx-skill works with the formats of Korea's Hancom office suite: HWP and HWPX. The skill for Claude and Codex reads and extracts text, edits existing documents, fills templates and creates new files that can then be edited in Hancom Office. New official letters, short and planning reports and general documents are built by `python scripts/one_shot.py spec.json --report quality.json`: a versioned JSON spec passes a quality check and is saved only after it. Ready examples run with the `--example` flag, for example `--example official-letter`. HWP is converted to HWPX first. If Hancom Office is installed on Windows, its engine does it through `scripts/convert_hwp_hancom.ps1`, otherwise a fallback converter `python3 scripts/convert_hwp.py input.hwp -o output.hwpx` runs on Node.js 18 or newer with a pinned rhwp WASM runtime. The original stays untouched. For forms there is a map-based replacement (`scripts/fill_hwpx.py`) with a key preflight and a leftovers check (`scripts/map_preflight.py`). Other scenarios: a standard draft document on the Korean Ministry of the Interior and Safety form with an automatic style check (`scripts/gonmun.py`, `scripts/gonmun_lint.py`), a press release on a government template, student worksheets from K-Teacher HTML (`scripts/html2hwpx.py`) and a pair of task sheet and answer sheet. For page review, `render_hwpx.py` renders PDF and PNG through Hancom. The skill supports Codex and the gpt-6-astra model but does not switch to it on its own.
Who it is for. Staff of Korean institutions, teachers and technical writers who need an agent to prepare HWPX documents: official letters, reports, forms and worksheets.
Good fit when
- An official document or report in HWPX is built from a JSON spec with a quality check
- A .hwp file has to be turned into .hwpx, read or edited without losing the original
- Values go into a form template and no old words may remain in the result (`map_preflight.py residue`)
- A document must follow ministry rules: the draft document form with an automatic check
- K-Teacher worksheets must become editable HWPX documents
Not a fit when
- You need DOCX or PDF: the skill works only with Hancom formats
- A complex layout with shading and shapes must match the original exactly: they can differ after conversion
- You need a guarantee of equal quality across different models: the README explicitly declines to give one
Example request
Convert `input.hwp` to HWPX without touching the original and build a short HWPX report from a JSON specLimitations
- The skill is built for Korean Hancom documents and covers no other formats.
- Fast HWP conversion goes through Hancom Office on Windows. Without it a fallback path on Node.js 18 or newer is used.
- After conversion from HWP, table shading, complex shapes, spacing and page breaks can change: keep an important document next to the original and review it in Hancom.
- Static checks, opening in Hancom and page review count as different things, and equal quality across models is not claimed.
How to disable. The skill lives among the agent's skills and is removed by deleting its folder. The installed packages `python-hwpx` and `lxml` are removed with `pip uninstall python-hwpx lxml`.
FAQ
How do I create an HWPX document with the skill?
Write a JSON spec, with type `official-letter`, `brief-report`, `plan-report` or `markdown`, and run `python scripts/one_shot.py spec.json --report quality.json`. `python scripts/one_shot.py --example official-letter` runs a trial example.
How do I open an HWP file?
Convert it to HWPX first: on Windows with Hancom Office use `scripts/convert_hwp_hancom.ps1`, otherwise `python3 scripts/convert_hwp.py input.hwp -o output.hwpx`. The original stays untouched.
Is Hancom Office required?
No, but it speeds up conversion and is needed to review pages. Without it, HWP is converted by the fallback path on Node.js 18 or newer.
How does this skill differ from claw-hwp?
claw-hwp reads, creates and edits documents without Hancom and without conversion. hwpx-skill adds building from a JSON spec with a quality check, ministry forms and HWP conversion through the Hancom engine.
How do I fill values into a ready template?
Dump the keys with `python3 scripts/map_preflight.py dump base.hwpx`, check the map with `check`, then run `python3 scripts/fill_hwpx.py replace base.hwpx out.hwpx --map map.json`. The `residue` command looks for leftovers of old words in the result.
Discussion
No questions or reviews yet.
Related
SkillsA skill that reads, creates and edits Korean hwp and hwpx documents from the agent, with no Hancom Office and no conversion
CLI and MCP server that turn Korean HWP and HWPX, PDF and Office files into Markdown and fill forms from templates
A skill that typesets resumes, one-pagers, letters, reports and slides from templates into PDF, PNG and PPTX and checks the result before delivery
A document pipeline skill: anything to markdown, markdown to clean html and publisher-grade docx, and html back to markdown
16 ready skills for Cursor, Claude Code and Codex: theses, PDF and Office, draw.io diagrams, project documentation
An MCP server and four skills for WPS Office: spreadsheets, documents and presentations edited from Claude Code and Cursor in plain language
README in short
The Korean README starts with a description of the skill and a block on quick generation from a JSON spec. Then come Codex and gpt-6-astra support, a replacement gate for forms, a table of eleven workflows from A to K, dependencies and quick recipes: HWP conversion, a document from Markdown, K-Teacher worksheets, a ministry form, a press release and a planning document.
README badge
Original SKILL.md
--- name: hwpx description: "한글 HWP/HWPX 파일의 변환·읽기·편집과 편집 가능한 .hwpx 문서 생성. 한글 파일, HWP 변환, HWPX 공문·보고서·계획서·활동지, 기존 한글 양식 채우기 요청에 사용한다." --- # 편집 가능한 고품질 한글 문서 모델은 요구 이해와 원고 구성에 집중하고, 코드는 입력 계약·자원·내용 보존·파일 저장을 검증한다. 같은 명세의 재현성과 서로 다른 모델의 결과 일관성은 별개다. 실제 모델 비교 없이 후자를 보장하지 않는다. 아스트라(Astra, `gpt-6-astra`)를 사용하는 Codex 환경을 지원한다. 집필·도식 설계·검토에 사용자 지정 모델과 추론 설정을 유지하며, 사용자 요청 없이 Astra로 전환하거나 추가 모델을 호출하지 않는다. Astra와 Luna 모두 같은 입력 계약·검사 경로를 사용한다. ## 새 문서 1. 사용자 요청의 사실·필수 조건·미확정 사항을 정리한다. 기관명·연도·장소·문서번호 등을 추측하지 않는다. - 문서에 필요하지만 미정인 사실과, 요청상 생략하는 항목은 다르다. 일반 지식 보고서에 기관·작성일을 쓰지 않는다는 이유만으로 unknowns나 초안 표시를 만들지 않는다. 2. 아래 문서 유형을 고르고 실행 가능한 예시와 스키마를 확인한다. 3. 기본 문서는 v1 Markdown/공문 JSON을 사용한다. 사실 계약·표 도식·기관별 표현이 필요하면 v2의 의미 블록을 사용한다. 모델이 XML이나 셀 좌표를 작성할 필요는 없다. - 공문 키는 예시의 `기관명`, `수신`, `제목`, `발신명의`, `body`를 그대로 사용한다. 영문 별칭을 추측하지 않는다. - 절차도·흐름도·추진체계도 요청은 `diagram` 블록과 `visual-elements.md`로 연결한다. 단계가 나열된 일반 데이터 표만으로 도식 요청을 충족했다고 판단하지 않는다. 4. 명세를 파일로 저장해 한 번 빌드한다. `ok`, `published`, `draft`, 미수행 검사 상태를 확인한다. 5. 완성본은 가능한 경우 실제 한컴 페이지를 렌더하고 육안 검토한다. 정적 통과, 한컴 열림, 렌더 성공, 시각 검토를 같은 것으로 취급하지 않는다. 아래 명령은 **이 SKILL.md가 있는 디렉터리**를 기준으로 한다. 다른 작업 디렉터리에서는 스크립트 경로를 해당 스킬의 절대 경로로 바꾼다. 특정 환경변수가 자동 설정된다고 가정하지 않는다. ```text python scripts/one_shot.py --example official-letter python scripts/one_shot.py --example diagram python scripts/one_shot.py --schema python scripts/one_shot.py /absolute/path/spec.json --report /absolute/path/quality.json ``` 명세의 상대 경로는 명세 파일 위치 기준이며, `source` 원고 속 그림 경로는 원고 위치 기준이다. 출력은 .hwpx여야 한다. 명세·원고·그림·출력·리포트가 충돌하면 사전에 거부한다. | 유형 | 입력과 용도 | |---|---| | `official-letter` | `document` 객체. 시행 공문·기안문, 붙임 안내·결재 필드 | | `brief-report` | Markdown 또는 v2 블록. 결재선·제목 띠가 있는 요약보고 | | `plan-report` | Markdown 또는 v2 블록. 장 배너·선택적 표지가 있는 계획·검토보고 | | `research-plan` | 연구학교 연구계획서 완본(28쪽, 표지·실태분석·SWOT·추진체계도 도식·실행계획 표). `scripts/research_plan.py`로 복제·생성 | | `markdown` | 범용 보고서·회의록·제안서. `template` 스타일 선택 가능 |