1---2name: oma-hwp3description: Convert Hangul HWP, HWPX, or HWPML documents to Markdown with4 kordoc. Use for text, table, and image extraction from these formats.5metadata:6 source: https://skillmd.com/skills/tuyv/oma-hwp7---89# HWP Skill - HWP / HWPX / HWPML to Markdown Conversion1011## Scheduling1213### Goal14Convert 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.1516### Intent signature17- User asks to convert, parse, read, extract, or transform `.hwp`, `.hwpx`, or `.hwpml`.18- User mentions Korean word processor files, Hangul documents, government forms, or "한글 파일".19- User needs headings, tables, nested tables, lists, images, footnotes, or hyperlinks extracted from HWP-family files.2021### When to use22- Converting Korean HWP documents (`.hwp`, `.hwpx`, `.hwpml`) to Markdown23- Preparing Korean government/enterprise documents for LLM context or RAG24- Extracting structured content (tables, headings, lists, images) from HWP25- User says "convert this HWP", "parse hwpx", "HWP to markdown", "한글 파일"2627### When NOT to use28- PDF files -> use `oma-pdf` (OCR + Tagged PDF specialization)29- XLSX / DOCX files -> out of scope; run `bunx kordoc` directly if needed (note: `oma-docs` is the documentation-drift skill, not a converter)30- Generating or editing HWP documents -> out of scope (kordoc itself supports `generate` / `fill` / `seal` / `patch` / `redact` / `lint` / `validate` / `render` subcommands; run `bunx kordoc@latest <subcommand>` directly if needed)31- Already-text files -> use Read tool directly3233### Expected inputs34- `input_path`: `.hwp`, `.hwpx`, or `.hwpml` file path35- `output_path` or `output_dir`: optional explicit output target36- `format`: optional output format — `markdown` (default), `json` (structured AST), or `chunks` (RAG-oriented structural chunk JSON with heading breadcrumbs and standalone table chunks)37- `page_range`: optional page or section range38- `kordoc_version`: optional pinned kordoc version3940### Expected outputs41- Markdown output next to the input file or in the requested directory42- Optional JSON or RAG-chunks output when requested43- Post-processed Markdown with flattened GFM tables and stripped Private Use Area glyphs by default44- A short report with output path, detected source format, and conversion issues4546### Dependencies47- `bun` and `bunx`48- `bunx kordoc@latest` or configured pinned kordoc version49- `resources/flatten-tables.ts` for Markdown cleanup50- Local filesystem access to input and output paths5152### Control-flow features53- Branches by file extension, output target, format, page range, encryption/DRM state, and post-processing requirements54- Calls external CLI tools through `bunx` and `bun run`55- Reads local HWP-family files and writes local Markdown or JSON output56- Routes non-HWP inputs to other skills instead of stretching this skill's scope5758## Structural Flow5960### Entry611. Confirm the input path exists.622. Confirm the extension is `.hwp`, `.hwpx`, or `.hwpml`.633. Resolve output path or directory and default filename.644. Check that `bun` is available.6566### Scenes671. **PREPARE**: Validate path, extension, size, output target, and requested format.682. **ACQUIRE**: Detect source format and runtime availability.693. **ACT**: Run `kordoc` with explicit output target and requested options.704. **VERIFY**: Post-process Markdown and inspect structure for headings, tables, lists, images, and footnotes.715. **FINALIZE**: Report output path, source format, and any conversion limitations.7273### Transitions74- If the input is `.pdf`, stop and route to `oma-pdf`.75- If the input is `.xlsx` or `.docx`, explain that this skill does not advertise those formats.76- If `bun` is unavailable, stop and ask the user to install Bun.77- If Markdown is produced, run `resources/flatten-tables.ts` unless the caller explicitly needs HTML tables or PUA glyphs preserved.78- If output is empty or garbled, consult `resources/troubleshooting.md`.7980### Failure and recovery81| Failure | Recovery |82|---------|----------|83| `bun` or `bunx` unavailable | Ask user to install Bun |84| Unsupported or mismatched format | Check extension and magic bytes, then route or stop |85| Encrypted or DRM-locked document | Report limitation and request an accessible copy when needed |86| Empty Markdown output | Treat as possible scanned-image content and recommend OCR outside this skill |87| Complex merged tables | Accept flattened Markdown or HTML fallback as best effort |88| Stale kordoc cache | Use `bunx kordoc@latest` or configured pinned version |89| `Cannot find module "turndown"` from `flatten-tables.ts` | Run `bun install` in this skill's `resources/` directory (its `node_modules` is gitignored and absent on fresh clones) |9091### Exit92- Success: output file exists and structure is readable after post-processing.93- Partial success: output exists with explicitly reported table, glyph, encryption, or fidelity limitations.94- Failure: no reliable output is produced and the blocking cause is reported.9596## Logical Operations9798### Actions99| Action | SSL primitive | Evidence |100|--------|---------------|----------|101| Validate file path and extension | `VALIDATE` | Input preflight in execution protocol |102| Check runtime availability | `VALIDATE` | `bun --version` |103| Select output target and format | `SELECT` | Output behavior and config |104| Run converter | `CALL_TOOL` | `bunx kordoc@latest` |105| Write output artifact | `WRITE` | Markdown or JSON output |106| Flatten tables and strip PUA glyphs | `CALL_TOOL` | `resources/flatten-tables.ts` |107| Inspect extraction quality | `VALIDATE` | Verification step |108| Report result | `NOTIFY` | Final user-facing summary |109110### Tools and instruments111- `kordoc`: primary HWP-family conversion CLI112- `flatten-tables.ts`: post-processing for GFM tables and Hancom PUA cleanup113- `bun` / `bunx`: runtime and CLI executor114115### Canonical command path116```bash117bunx kordoc@latest "{input_path}" -o "{output_path}"118# fresh clone: run `bun install` in {skill_dir}/resources/ first (node_modules is gitignored)119bun "{skill_dir}/resources/flatten-tables.ts" "{output_path}"120# {skill_dir} = this skill's directory: .agents/skills/oma-hwp (project mode) or ~/.agents/skills/oma-hwp (global mode)121```122123For batch conversion, use an explicit output directory:124```bash125bunx kordoc@latest "{input_pattern}" -d "{output_dir}"126```127128### Resource scope129| Scope | Resource target |130|-------|-----------------|131| `LOCAL_FS` | Input HWP-family files and generated outputs |132| `PROCESS` | `bunx kordoc` and `bun run` subprocesses |133| `MEMORY` | Format decisions, validation notes, and final report |134135### Preconditions136- Input file exists and is readable.137- Output location is writable or can be created.138- `bun` is installed.139- `kordoc` can parse the document or fail with a reportable error.140141### Effects and side effects142- Creates Markdown or JSON output files.143- May flatten merged-cell tables, trading cell fidelity for Markdown compatibility.144- Strips Private Use Area characters by default because they render as blanks without Hancom fonts.145- Does not intentionally modify the source HWP-family document.146147### Guardrails1481. Always pass `@latest` or an explicit pinned version to avoid stale `bunx` cache.1492. Always pass an explicit output target when the user expects a file.1503. Do not add custom security defenses around kordoc's ZIP, XML, SSRF, or XSS defenses.1514. Report missing tables, garbled text, empty output, encrypted segments, and best-effort DRM extraction.1525. Keep full CLI details in `resources/execution-protocol.md` and troubleshooting branches in `resources/troubleshooting.md`.153154### Supported Formats155| Format | Extension | Notes |156|--------|-----------|-------|157| HWP 5.x binary | `.hwp` | Full support (incl. DRM-locked via kordoc's rhwp-algorithm port) |158| HWPX | `.hwpx` | Full support incl. nested tables, merged cells |159| HWPML | `.hwp` (XML variant) | Auto-detected by signature |160161> kordoc also parses PDF / XLSX / DOCX and offers document-authoring subcommands (`generate`, `fill`, `seal`, `patch`, `redact`, `lint`, `validate`, `render`). All of those are intentionally outside this skill's scope; see "When NOT to use". Conversion-quality flags (`--dedupe-headers`, `--keep-empty-cols`, `--inline-images`) and the `chunks` format are documented in `resources/execution-protocol.md`.162163## References164- Execution protocol: `resources/execution-protocol.md`165- Troubleshooting: `resources/troubleshooting.md`166- Configuration: read the `hwp:` section of `.agents/oma-config.yaml` first, then fall back to `config/hwp-config.yaml` for any key it does not set (`supported_formats` lives only in the skill config). User overrides belong in `.agents/oma-config.yaml`, since `oma update` overwrites the skill config.167- Upstream: https://github.com/chrisryugj/kordoc168- Related: `../oma-pdf/SKILL.md` (use for `.pdf` inputs)