Skip to main content
skill CX Codex

oma-hwp · first-fluke — Claude Code skill: converts HWP to Markdown

oma-hwp turns Korean HWP, HWPX and HWPML documents into Markdown via kordoc. Extracts text, tables, lists, images and footnotes.

MIT ★ 1,472 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add first-fluke/oh-my-agent
/plugin install oma@oh-my-agent
Open on GitHub

What oma-hwp does

The skill calls bunx kordoc to transform .hwp, .hwpx and .hwpml files into readable Markdown or JSON. Pulls out headings, nested tables, lists, images, footnotes and hyperlinks. After conversion it runs post-processing via resources/flatten-tables.ts: normalizes tables to GFM and strips Private Use Area glyphs.

Requires Bun and bunx. On first run, execute bun install in the skill's resources/ folder, since node_modules there is gitignored. Encrypted or DRM-protected documents are not supported — the skill will report the limitation and request an accessible copy.

Outputs a Markdown file next to the source or in a specified directory, plus a brief report: output path, source format and any conversion issues found. Handles page ranges and can output structured JSON for RAG, where each chunk contains heading breadcrumbs.

What it helps with

  • convert Korean HWP documents to Markdown for LLM context
  • extract tables and headings from HWPX files
  • prepare Korean government forms from HWP for RAG
  • pull text and images from HWPML
  • flatten complex nested HWP tables into readable format

Example prompts for the agent

  • Convert contract.hwp to Markdown
  • Extract tables from government-form.hwpx into JSON for RAG
  • Convert all HWPML files from docs/ folder to Markdown

How to install oma-hwp

1Plugin marketplace

/plugin marketplace add first-fluke/oh-my-agent
/plugin install oma@oh-my-agent

This installs the whole oma plugin with all its skills

2Skills CLI (Vercel)

npx skills add first-fluke/oh-my-agent --skill oma-hwp -a claude-code

3Manually: put the files in place

~/.claude/skills/oma-hwp/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/oma-hwp/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about oma-hwp

How to install oma-hwp in Claude Code?

Run /plugin marketplace add first-fluke/oh-my-agent, then /plugin install oma@oh-my-agent. After that, execute npx skills add first-fluke/oh-my-agent --skill oma-hwp -a claude-code and open ~/.claude/skills/oma-hwp/SKILL.md.

What does oma-hwp do?

Converts Korean HWP, HWPX and HWPML documents to Markdown or JSON via kordoc. Extracts text, tables, lists, images, footnotes and hyperlinks while preserving document structure.

What does oma-hwp need to work?

Requires Bun and bunx. On first run, execute bun install in the skill's resources/ folder, since node_modules there is gitignored. Encrypted and DRM-protected documents are not supported.

Source text

SKILL.md · MIT
---
name: oma-hwp
description: "Convert Hangul HWP, HWPX, or HWPML documents to Markdown with kordoc. Use for text, table, and image extraction from these formats."
---

# 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

### 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
| 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 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

### 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
```bash
bunx kordoc@latest "{input_path}" -o "{output_path}"
# 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)
```

For batch conversion, use an explicit output directory:
```bash
bunx kordoc@latest "{input_pattern}" -d "{output_dir}"
```

### Resource scope
| Scope | Resource target |
|-------|-----------------|
| `LOCAL_FS` | Input HWP-family files and generated outputs |
| `PROCESS` | `bunx kordoc` and `bun run` subprocesses |
| `MEMORY` | Format decisions, validation notes, and final report |

### 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
| Format | Extension | Notes |
|--------|-----------|-------|
| HWP 5.x binary | `.hwp` | Full support (incl. DRM-locked via kordoc's rhwp-algorithm port) |
| HWPX | `.hwpx` | Full support incl. nested tables, merged cells |
| HWPML | `.hwp` (XML variant) | Auto-detected by signature |

> 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`.

## 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)

© First Fluke · MIT · first-fluke/oh-my-agent

Similar skills

All skills for Office documents →

oma-hwp by other authors comes first.

From the same set69

The whole set →
oma-search The oma-search skill picks a search channel for docs, web research, code, or local project files, then labels external sources by domain trust. Use it when the right place to search is unclear. CX Codex +1 ★ 1,472repo stars oma-image oma-image routes image generation requests across Codex, Pollinations and Gemini, and turns a reference picture into a new variation matching its style or layout. CX Codex +1 ★ 1,472repo stars oma-architecture oma-architecture is a Claude Code skill that helps design module and service boundaries, compare alternatives, and document architecture decisions as ADRs. CX Codex +1 ★ 1,472repo stars oma-coordination The oma-coordination skill guides manual coordination across specialist agents on multi-domain projects. It covers task planning, progress checks, contract alignment, and a final QA review. CX Codex +1 ★ 1,472repo stars oma-pdf oma-pdf converts PDF documents into structured Markdown while preserving tables, headings, and lists. Runs when preparing files for LLM context or RAG pipelines. CX Codex +1 ★ 1,472repo stars oma-market oma-market runs community-signal research on customer pain, trends, and competitors, then saves a market brief for the requested topic. CX Codex +1 ★ 1,472repo stars oma-video Builds videos through the OMA video CLI or works on an existing clip: pulling frames, cutting silence, assembling dubbed audio. CX Codex +1 ★ 1,472repo stars oma-skill-creator oma-skill-creator is a Claude Code skill that creates, formats, and validates OMA skills in SSL-lite format inside .agents/skills/. CX Codex +1 ★ 1,472repo stars

Project sponsors

Companies that keep this analytics open