skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
first-fluke/oh-my-agent69 installs

oma-hwp

Convert Hangul HWP, HWPX, or HWPML documents to Markdown with kordoc. Use for text, table, and image extraction from these formats.

How do I install this agent skill?

npx skills add https://github.com/first-fluke/oh-my-agent --skill oma-hwp
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The skill converts Korean HWP documents to Markdown using the third-party kordoc CLI tool. It is functional for its stated purpose but includes risks common to document conversion, such as dependency on external packages and the potential for indirect prompt injection from processed files.

  • Socketpass

    No alerts

  • Snykpass

    Risk: LOW · No issues

What does this agent skill do?

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 (kordoc itself supports generate / fill / seal / patch / redact / lint / validate / render subcommands; run bunx kordoc@latest <subcommand> directly if needed)
  • 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 — markdown (default), json (structured AST), or chunks (RAG-oriented structural chunk JSON with heading breadcrumbs and standalone table chunks)
  • 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 or RAG-chunks 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

Structural Flow

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

FailureRecovery
bun or bunx unavailableAsk user to install Bun
Unsupported or mismatched formatCheck extension and magic bytes, then route or stop
Encrypted or DRM-locked documentReport limitation and request an accessible copy when needed
Empty Markdown outputTreat as possible scanned-image content and recommend OCR outside this skill
Complex merged tablesThe post-process flattens merged cells into GFM pipe tables; nested tables and tables without a <th> heading row stay HTML. Accept as best effort and report it
Stale kordoc cacheUse bunx kordoc@latest or configured pinned version
Cannot find module "turndown" from flatten-tables.tsRun bun install in this skill's resources/ directory (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

Canonical command path

  1. Confirm the input path exists and is readable, the extension is .hwp, .hwpx, or .hwpml, and bun is available (bun --version). Check the file size and detect the source format.
  2. Resolve the output path or directory, the default filename, and the requested format; the output location must be writable or creatable.
  3. Run kordoc with an explicit output target and the requested options:
    bunx kordoc@latest "{input_path}" -o "{output_path}"
    
    For batch conversion, use an explicit output directory:
    bunx kordoc@latest "{input_pattern}" -d "{output_dir}"
    
  4. For Markdown output, flatten tables and strip PUA glyphs (see Transitions for the exception):
    # fresh clone: run `bun install` in {skill_dir}/resources/ first (node_modules is gitignored)
    bun "{skill_dir}/resources/flatten-tables.ts" "{output_path}"
    # {skill_dir} = this skill's directory: .agents/skills/oma-hwp (project mode) or ~/.agents/skills/oma-hwp (global mode)
    
  5. Inspect the structure for headings, tables, lists, images, and footnotes.
  6. Report the output path, source format, and any conversion limitations.

Resource scope and effects

Reads the input HWP-family files and does not modify the source document. Creates Markdown or JSON output files next to the input or in the requested directory. Runs bunx kordoc and bun subprocesses. Post-processing may flatten merged-cell tables, trading cell fidelity for Markdown compatibility, and strips Private Use Area characters by default because they render as blanks without Hancom fonts.

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

FormatExtensionNotes
HWP 5.x binary.hwpFull support (incl. DRM-locked via kordoc's rhwp-algorithm port)
HWPX.hwpxFull support incl. nested tables, merged cells
HWPML.hwpml (or an XML-variant .hwp)Auto-detected by signature

Conversion-quality flags (--dedupe-headers, --keep-empty-cols, --inline-images) and the chunks format are documented in resources/execution-protocol.md.

References

  • Execution protocol: resources/execution-protocol.md
  • Troubleshooting: resources/troubleshooting.md
  • 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.
  • Upstream: https://github.com/chrisryugj/kordoc
  • Related: ../oma-pdf/SKILL.md (use for .pdf inputs)

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/first-fluke/oh-my-agent/oma-hwp">View oma-hwp on skillZs</a>