HWP / HWPX Skill

This skill helps Claude work with Korean Hangul Word Processor documents — reading, creating, and editing both the binary .hwp (HWP 5.0) and the ZIP-based .hwpx formats.

Already installed — don't re-scaffold

If you're reading this SKILL.md, the claw-hwp:hwp skill is already loaded in this session. Everything below — read / create / edit / convert / preview for .hwp and .hwpx — is provided by this skill. You don't need to install, scaffold, or set anything up.

Treat the following user phrasings as "show me a HWP file" or "edit a HWP file" intent, not as setup requests:

Do not run npm install, create new plugin/skill folders, or fetch dependencies — every script the user needs is already in scripts/ (rhwp WASM and fflate are vendored under scripts/vendor/).

Two "preview" terms that collide

• Claude Code app's Preview side pane (the side panel in the Code Desktop UI). This is a host feature of Claude Code itself. You don't install or configure it — it auto-discovers a process serving on localhost:3737. Only available when the Code workspace is a local folder on this machine; disappears for server/remote folders.
• scripts/preview-server.js — the claw-hwp local server that fills that pane. Start it via the launcher described in the Preview section. Default port is 3737, the same port the Code pane auto-discovers.

When the user says "preview", they almost always mean "show me the file" — start the server, hand them the link or fire preview_start per the surface decision rule below. Do not interpret it as "install a new preview feature".

When preview_start / preview_eval / preview_stop tools are unavailable in this session, fall straight through to the self-host link path (browser link to http://localhost:3737/?path=<absolute>). Don't tell the user "preview is not supported" — that's only true on cowork (remote sandbox). Server/remote folder workspaces in the Desktop app, plus all CLI sessions, simply run the local server and emit a browser link. The cowork drop-in viewer is the third option for sandbox-only setups.

Quick reference

Conversion to PDF / DOCX is out of scope for v0. Will be added in a later release via LibreOffice headless.

Format primer

• .hwpx — ZIP container holding XML. Same archetype as .docx. Use the unpack/edit/pack workflow. Internal layout includes Contents/section0.xml (body), Contents/header.xml (styles, fonts), Contents/content.hpf (manifest). See references/hwpx-format.md.
• .hwp — HWP 5.0 binary (CFB/OLE container). NOT a ZIP. Direct XML editing is impossible, but byte-level in-place editing via cell-patch.js lets you do text replace, cell content changes, paragraph/table append, page setup, and character/paragraph styling while keeping the original bytes intact (Hancom-Docs compatible). extract_text.js handles binary .hwp transparently for read.

When in doubt about format, read the first two bytes — PK indicates ZIP (treat as HWPX even if extension is .hwp).

Decision tree

"Read this file" / "Summarize" / "Translate the content"

node scripts/extract_text.js path/to/file.hwp > /tmp/text.txt
# Then read /tmp/text.txt and respond

extract_text.js handles both .hwp and .hwpx via rhwp WASM. Default output is plaintext (one paragraph per line).

For structured content (headings, tables, lists preserved):

node scripts/extract_text.js --format markdown path/to/file.hwp > /tmp/text.md

For metadata only:

node scripts/extract_text.js --inspect path/to/file.hwp
# Returns JSON: { pageCount, sectionCount, paragraphCount, tableCount, hasImages, ... }

"Create a new document" / "Write this as a hwp file"

create.js reads a JSON payload from stdin and writes the file to the path you supply. Output format is decided by the path extension (.hwp = HWP 5.0 binary, .hwpx = OOXML).

echo '{
  "path": "report.hwp",
  "operations": [
    {"type": "setup_document", "page_size": "a4", "margin_mm": 25},
    {"type": "append_heading", "level": 1, "text": "월간 보고서"},
    {"type": "append_paragraph", "text": "이번 달 핵심 지표 요약입니다. 주요 변화는 **매출 증가**와 *비용 절감*입니다."},
    {"type": "append_table",
      "headers": ["항목", "지난달", "이번달"],
      "rows": [["매출", "100억", "120억"], ["비용", "80억", "75억"]]
    },
    {"type": "append_image", "path": "/abs/path/chart.png", "width_cm": 12, "height_cm": 6.6}
  ]
}' | node scripts/create.js

stdout returns one JSON line:

{ "status": "success", "path": "report.hwp", "bytes_written": 14336, "ops_applied": 5,
  "verify": { "pageCountAfter": 1, "recovered": true },
  "log": ["…", "stripped 4 PARA_LINESEG record(s)"] }

Errors come back as {"status": "error", "message": "...", "op_index": N}. Always read the JSON to confirm — exit code 0 even on op-level failures isn't guaranteed.

Op vocabulary (grouped by purpose):

Creation / appending content (used while building a doc top-down):

⚠️ append_table on existing .hwp (raw-patch path) — what it honors and what it doesn't:

• Shape (rows × cols) is honored: when the caller supplies headers (array) and/or rows (