Oma Hwp

HWP Skill - HWP / HWPX / HWPML to Markdown Conversion

Scheduling

Goal

Convert Korean HWP-family documents into readable Markdown or structured JSON while preserving document structure for LLM context, RAG, government-document review, or enterprise document processing.

Intent signature

• User asks to convert, parse, read, extract, or transform .hwp, .hwpx, or .hwpml.
• User mentions Korean word processor files, Hangul documents, government forms, or "한글 파일".
• User needs headings, tables, nested tables, lists, images, footnotes, or hyperlinks extracted from HWP-family files.

When to use

• Converting Korean HWP documents (.hwp, .hwpx, .hwpml) to Markdown
• Preparing Korean government/enterprise documents for LLM context or RAG
• Extracting structured content (tables, headings, lists, images) from HWP
• User says "convert this HWP", "parse hwpx", "HWP to markdown", "한글 파일"

When NOT to use

• PDF files -> use oma-pdf (OCR + Tagged PDF specialization)
• XLSX / DOCX files -> out of scope; run bunx kordoc directly if needed (note: oma-docs is the documentation-drift skill, not a converter)
• Generating or editing HWP documents -> out of scope
• Already-text files -> use Read tool directly

Expected inputs

• input_path: .hwp, .hwpx, or .hwpml file path
• output_path or output_dir: optional explicit output target
• format: optional output format, default markdown
• page_range: optional page or section range
• kordoc_version: optional pinned kordoc version

Expected outputs

• Markdown output next to the input file or in the requested directory
• Optional JSON output when requested
• Post-processed Markdown with flattened GFM tables and stripped Private Use Area glyphs by default
• A short report with output path, detected source format, and conversion issues

Dependencies

• bun and bunx
• bunx kordoc@latest or configured pinned kordoc version
• resources/flatten-tables.ts for Markdown cleanup
• Local filesystem access to input and output paths

Control-flow features

• Branches by file extension, output target, format, page range, encryption/DRM state, and post-processing requirements
• Calls external CLI tools through bunx and bun run
• Reads local HWP-family files and writes local Markdown or JSON output
• Routes non-HWP inputs to other skills instead of stretching this skill's scope

Structural Flow

Entry

1. Confirm the input path exists. 2. Confirm the extension is .hwp, .hwpx, or .hwpml. 3. Resolve output path or directory and default filename. 4. Check that bun is available.

Scenes

1. PREPARE: Validate path, extension, size, output target, and requested format. 2. ACQUIRE: Detect source format and runtime availability. 3. ACT: Run kordoc with explicit output target and requested options. 4. VERIFY: Post-process Markdown and inspect structure for headings, tables, lists, images, and footnotes. 5. FINALIZE: Report output path, source format, and any conversion limitations.

Transitions

• If the input is .pdf, stop and route to oma-pdf.
• If the input is .xlsx or .docx, explain that this skill does not advertise those formats.
• If bun is unavailable, stop and ask the user to install Bun.
• If Markdown is produced, run resources/flatten-tables.ts unless the caller explicitly needs HTML tables or PUA glyphs preserved.
• If output is empty or garbled, consult resources/troubleshooting.md.

Failure and recovery

Exit

• Success: output file exists and structure is readable after post-processing.
• Partial success: output exists with explicitly reported table, glyph, encryption, or fidelity limitations.
• Failure: no reliable output is produced and the blocking cause is reported.

Logical Operations

Actions

Tools and instruments

• kordoc: primary HWP-family conversion CLI
• flatten-tables.ts: post-processing for GFM tables and Hancom PUA cleanup
• bun / bunx: runtime and CLI executor

Canonical command path

bunx kordoc@latest "{input_path}" -o "{output_path}"
# fresh clone: run `bun install` in .agents/skills/oma-hwp/resources/ first (node_modules is gitignored)
bun ".agents/skills/oma-hwp/resources/flatten-tables.ts" "{output_path}"

For batch conversion, use an explicit output directory:

bunx kordoc@latest "{input_pattern}" -d "{output_dir}"

Resource scope

Preconditions

• Input file exists and is readable.
• Output location is writable or can be created.
• bun is installed.
• kordoc can parse the document or fail with a reportable error.

Effects and side effects

• Creates Markdown or JSON output files.
• May flatten merged-cell tables, trading cell fidelity for Markdown compatibility.
• Strips Private Use Area characters by default because they render as blanks without Hancom fonts.
• Does not intentionally modify the source HWP-family document.

Guardrails

1. Always pass @latest or an explicit pinned version to avoid stale bunx cache. 2. Always pass an explicit output target when the user expects a file. 3. Do not add custom security defenses around kordoc's ZIP, XML, SSRF, or XSS defenses. 4. Report missing tables, garbled text, empty output, encrypted segments, and best-effort DRM extraction. 5. Keep full CLI details in resources/execution-protocol.md and troubleshooting branches in resources/troubleshooting.md.

Supported Formats

kordoc also parses PDF / XLSX / DOCX. Those are intentionally outside this skill's scope; see "When NOT to use".

References

• Execution protocol: resources/execution-protocol.md
• Troubleshooting: resources/troubleshooting.md
• Configuration: config/hwp-config.yaml
• Upstream: https://github.com/chrisryugj/kordoc
• Related: ../oma-pdf/SKILL.md (use for .pdf inputs)

HWP Conversion - Execution Protocol

Step 0: Validate Input

1. Confirm the input file path exists 2. Check extension is one of .hwp, .hwpx, .hwpml

• If .pdf -> hand off to oma-pdf
• If .xlsx / .docx -> not in scope; advise user to run bunx kordoc@latest <file> directly

3. Check file size (wc -c or ls -lh); warn if >100MB 4. Determine output location:

• If user specified output path (-o or -d) → use it
• Otherwise → same directory as the input file

5. Determine output filename: {input_basename}.md

Step 1: Check Runtime

bun --version

If bun is not available, ask the user to install Bun (https://bun.sh). bunx is required.

Step 2: Convert

Important: Without -o or -d, kordoc prints the Markdown to stdout and does not create a file. Always pass an explicit output path to match this skill's "same directory as input" convention.

Standard conversion (single file, write next to input)

bunx kordoc@latest "{input_path}" -o "{output_path}"
# {output_path} = "{dirname(input_path)}/{basename_without_ext(input_path)}.md"

Output directory (multiple files)

bunx kordoc@latest "{input_pattern}" -d "{output_dir}"

Print to stdout (piping / preview)

bunx kordoc@latest "{input_path}"
# No file written; useful when piping to another tool

Page / section range

bunx kordoc@latest "{input_path}" -p "{range}"

JSON output (structured intermediate form)

bunx kordoc@latest "{input_path}" --format json

Notes:

• Default format is markdown. Pass --format json only when you need the structured AST.
• --silent suppresses progress output, useful in automation / piping contexts.

Step 2.5: Post-process kordoc output (default)

resources/flatten-tables.ts cleans up two kordoc artifacts that hurt downstream use:

1. HTML `<table>` blocks: kordoc emits these when a table has colspan / rowspan because GFM cannot represent merged cells. Converted to GFM pipe tables via turndown-plugin-gfm. 2. Private Use Area characters: HWP references Hancom-font-specific glyphs via U+E000-U+F8FF / U+F0000-U+FFFFD / U+100000-U+10FFFD code points. Without the Hancom font these render as blanks or tofu squares. Silently stripped.

node "{skill_resources}/flatten-tables.ts" "{output_path}"

• {skill_resources} = .agents/skills/oma-hwp/resources
• Ensure bun install has been run once inside that directory (it installs turndown + turndown-plugin-gfm locally)
• Merged cells get flattened during the conversion (accepted trade-off)
• Skip this step only if the caller explicitly needs HTML tables or PUA characters preserved (rare)

Step 3: Verify

1. Read the generated Markdown file 2. Verify structure:

• Headings preserved (#, ##, etc.)
• Tables rendered (GFM pipe syntax, or HTML <table> fallback for merged cells)
• Lists maintained (bullets, numbered)
• Images referenced (relative paths or inline)
• Footnotes linked via [^id]

3. If the file is empty or clearly garbled, consult troubleshooting.md 4. If output directory is temporary, move the file to the target location 5. If the user needs the content in-conversation, read and present it

Step 4: Report

Tell the user:

• Output file path
• Source format detected (HWP5 / HWPX / HWPML)
• Any issues encountered (encrypted segments, missing tables, best-effort DRM extraction)
• Page/section count if available

Error Recovery

Pin vs Latest

• Default: bunx kordoc@latest (always latest). Gets upstream fixes automatically. @latest is required because a bare bunx kordoc can reuse a stale cached version indefinitely.
• Reproducibility: pin with bunx kordoc@2.4.0 ... or similar. Record the pinned version in config/hwp-config.yaml under version.pinned and set version.channel: pinned.

Scope Reminder

If the user hands you a .pdf / .xlsx / .docx with this skill activated, do not proceed. Redirect:

• .pdf → switch to oma-pdf
• .xlsx / .docx → ask the user to run bunx kordoc@latest <file> directly; this skill does not advertise those formats

kordoc technically supports them, but routing keeps skill scopes clean.

oma-hwp Troubleshooting

Diagnosing conversion issues

1. "지원하지 않는 파일 형식" / unsupported file format

• Verify the extension matches the content. HWP5 files should start with D0 CF 11 E0 (OLE compound). HWPX starts with 50 4B 03 04 (ZIP).
• Check with: xxd "{file}" | head -1
• If the extension is wrong, rename and retry.
• If the file is genuinely a different format (e.g., Word, Excel), use the appropriate skill.

2. Encrypted or password-protected HWP

• kordoc reports 암호화된 문서 / "encrypted document".
• General password-locked HWP: the CLI currently has no inline password flag. Ask the user to decrypt the file first (via Hancom Office) and retry.
• DRM "distribution-only" HWP (배포용): kordoc ports rhwp's AES-128 ECB algorithm and often succeeds. If it still fails, note as best-effort and continue with other files.

3. Empty Markdown output

Most likely causes:

• HWP contains only scanned images without a text layer → needs OCR (out of scope).
• kordoc bug on a specific document → try bunx kordoc@latest; if still empty, report upstream with a sample.

4. Missing or broken tables

• Simple tables: GFM pipe syntax.
• Tables with colspan / rowspan: kordoc falls back to HTML <table>. This is expected and correct.
• Nested tables: large nested tables become separate blocks; small ones get flattened into the parent cell.
• If tables are completely absent, confirm the source file actually contains tables (sometimes they are images).

5. Hyperlinks look wrong

kordoc sanitizes links (XSS defense). If a legitimate link is stripped, verify the original URL scheme: only http://, https://, mailto:, and relative paths are preserved by default.

6. Image extraction issues

• kordoc extracts images from ZIP entries (HWPX) and HWP5 BinData streams.
• Output is typically written as {input_basename}.assets/ next to the Markdown file.
• If images are missing, check whether the source file truly embeds them (vs linking externally).

7. Slow conversion / timeout on huge files

• Use -p to narrow to a page/section range.
• Split processing across page ranges and concatenate results.
• If a specific PDF-embedded HWPX is slow, consider oma-pdf for the PDF portion.

8. kordoc crash / stack trace

1. Upgrade: bunx kordoc@latest (bust the bunx cache if needed) 2. Capture a minimal reproducible fixture 3. File an issue: https://github.com/chrisryugj/kordoc/issues 4. Meanwhile, if only a subset of the document triggers the crash, use -p to skip it

9. Reproducibility vs freshness tradeoff

• bunx kordoc@latest always pulls latest. Fixes land fast, but outputs may drift. A bare bunx kordoc reuses the bunx cache and can be arbitrarily old; always include @latest or a pinned version.
• For long-running projects, pin a version: edit config/hwp-config.yaml:

  version:
    channel: pinned
    pinned: "2.4.0"

Then invoke via bunx kordoc@2.4.0 ... in commands.

kordoc limitations (upstream-owned)

• Inline password entry for encrypted HWP: not yet supported.
• OCR of scanned HWPs: out of kordoc's scope; it does not perform OCR.
• Perfect fidelity of complex shapes / drawings: Markdown cannot represent drawing primitives; expect them to be dropped or replaced by placeholder markers.

When to route elsewhere