From i-hate-hancom
HWPX 한컴문서를 읽고 작성하는 스킬. 한컴문서(HWPX) 파일을 분석하거나, 사용자가 제공한 내용을 바탕으로 한국 정부 공문서 수준의 문서를 생성한다. "한컴", "한글문서", "hwpx", "hwp", "보도자료 작성", "공문서 작성", "한컴으로 만들어줘", "hwpx로 저장", "이 hwpx 파일 읽어줘" 등의 요청이나 .hwpx 파일이 언급될 때 이 스킬을 사용한다. 한컴문서 관련 작업이라면 명시적으로 스킬을 요청하지 않아도 적극적으로 사용할 것.
How this skill is triggered — by the user, by Claude, or both
Slash command
/i-hate-hancom:HancomThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
HWPX is Korea's standard document format — a ZIP archive containing XML files. The core idea: `header.xml` defines all styles by ID (like CSS), and `section0.xml` references those IDs to format content (like HTML). The converter (`md_to_hwpx.py`) handles all XML generation from annotated markdown.
HWPX is Korea's standard document format — a ZIP archive containing XML files. The core idea: header.xml defines all styles by ID (like CSS), and section0.xml references those IDs to format content (like HTML). The converter (md_to_hwpx.py) handles all XML generation from annotated markdown.
This skill runs in two contexts: local (CLI/IDE) and Cowork (cloud sandbox).
In Cowork, uploaded files are mounted read-only. Bash cp preserves the source
permissions, so copied files are also read-only — scripts that write in-place will
fail with PermissionError.
Three rules for Cowork compatibility:
cleaned_original.md must be in a writable directory
because the linter writes to it in-place, and you Edit() it afterward for
normalization. The final .hwpx output must also go to a writable directory.
Never create working files in the upload directory./sessions/.../mnt/.remote-plugins/.... Use the full resolved path
when calling scripts via Bash.These rules also apply locally — they just don't cause errors there.
| When | Read |
|---|---|
| Preparing content (normalize + annotate) | references/content-prep-guide.md |
| Understanding design principles | references/document-design.md |
| Looking up style IDs | references/style-catalog.md |
| Understanding HWPX XML structure | references/hwpx-format.md |
Run the linter with -o to create a linted copy in the working directory:
python3 scripts/md_lint.py original.md -o cleaned_original.md
The -o flag reads the original, applies lint rules, and writes the result to
cleaned_original.md. No separate copy step needed. The output file must be in
a writable directory — in Cowork, that's the session working directory, not the
upload directory.
Do not Read() the input file before this step. The linter is purely mechanical
— it needs no understanding of the content. You will Read() the linted
cleaned_original.md in Step 2, so reading the original here wastes tokens.
Lint rules: heading level gaps, consecutive blank lines, blank lines between list items, multiple spaces, trailing whitespace, EOF newline. No semantic judgment — purely mechanical.
Read references/content-prep-guide.md, then Read() cleaned_original.md. Apply all changes
using Edit() only. Never use Write() to rewrite the file.
Each Edit() targets a specific string and replaces it. Example:
Edit("---\ntags:...\n---\n", "") ← remove YAML frontmatter
Edit("## 🏛️ Section", "## Section") ← strip emoji from heading
Edit("> [!cite]\n> ...\n> ...", "") ← remove Obsidian callout block
Edit("## Duplicate Title\n\n", "") ← remove redundant heading
The converter turns markdown into 5x more XML. Every token saved in the input saves 5x in the output. A 100-line file: 15 Edit() calls ≈ 750 tokens, Write() the whole file ≈ 6000 tokens. Always use Edit().
Typical cleanup tasks:
<!-- table:compare -->, <!-- box:note -->, etc.)Most elements need no annotation — the converter auto-detects headings, bullets, tables, and paragraphs from standard markdown syntax.
python3 scripts/md_to_hwpx.py cleaned_original.md --output output.hwpx --build --title "문서 제목"
Images referenced in the markdown () are automatically detected and embedded.
The converter handles all XML generation: headings, bullets, tables, boxes, images, spacing. No manual XML assembly needed.
All paths (cleaned_original.md, output.hwpx) are resolved relative to the
current working directory. In Cowork, this is the session directory — which is
writable. Never write output to the upload directory.
python3 scripts/read_hwpx.py input.hwpx # text only
python3 scripts/read_hwpx.py input.hwpx --verbose # with style info
These are hard technical requirements — violating them crashes Hancom Office:
templates/base/Contents/header.xmlhh:/hc: prefixes to ns0:/ns1:, breaking Hancom renderingbuild_hwpx.py injects it from the template automaticallyAll scripts are in scripts/ within this skill directory:
scripts/md_lint.py — mechanical markdown linter (pre-processing)scripts/md_to_hwpx.py — annotated markdown → HWPX (main converter)scripts/build_hwpx.py — section0.xml → HWPX ZIP assemblyscripts/validate_hwpx.py — structural validationscripts/read_hwpx.py — HWPX → structured text extractionTemplates are in templates/:
templates/base/ — header.xml, secPr template, base ZIP structuretemplates/xml-parts/ — XML fragment templates used by md_to_hwpx.pyCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub tjdwls101010/i-hate-hancom_for_claude --plugin i-hate-hancom