Convert HWP / HWPX / HWPML files to Markdown using kordoc. Extracts text, headings, tables, lists, images, footnotes, and hyperlinks. Use for Korean word processor files (Hangul), government documents, and AI-ready data preparation.
Installation
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Convert HWP / HWPX / HWPML files to Markdown using kordoc. Extracts text, headings, tables, lists, images, footnotes, and hyperlinks. Use for Korean word processor files (Hangul), government documents, and AI-ready data preparation.
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
Confirm the input path exists.
Confirm the extension is .hwp, .hwpx, or .hwpml.
Resolve output path or directory and default filename.
Check that bun is available.
Scenes
PREPARE: Validate path, extension, size, output target, and requested format.
ACQUIRE: Detect source format and runtime availability.
ACT: Run kordoc with explicit output target and requested options.
VERIFY: Post-process Markdown and inspect structure for headings, tables, lists, images, and footnotes.
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
Failure
Recovery
bun or bunx unavailable
Ask user to install Bun
Unsupported or mismatched format
Check extension and magic bytes, then route or stop
Encrypted or DRM-locked document
Report limitation and request an accessible copy when needed
Empty Markdown output
Treat as possible scanned-image content and recommend OCR outside this skill
Complex merged tables
Accept flattened Markdown or HTML fallback as best effort
Stale kordoc cache
Use bunx kordoc@latest or configured pinned version
Cannot find module "turndown" from flatten-tables.ts
Run bun install in .agents/skills/oma-hwp/resources/ (its node_modules is gitignored and absent on fresh clones)
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
Action
SSL primitive
Evidence
Validate file path and extension
VALIDATE
Input preflight in execution protocol
Check runtime availability
VALIDATE
bun --version
Select output target and format
SELECT
Output behavior and config
Run converter
CALL_TOOL
bunx kordoc@latest
Write output artifact
WRITE
Markdown or JSON output
Flatten tables and strip PUA glyphs
CALL_TOOL
resources/flatten-tables.ts
Inspect extraction quality
VALIDATE
Verification step
Report result
NOTIFY
Final user-facing summary
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:
