Oh-my-agent oma-hwp

install

source · Clone the upstream repo

git clone https://github.com/first-fluke/oh-my-agent

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/first-fluke/oh-my-agent "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.agents/skills/oma-hwp" ~/.claude/skills/first-fluke-oh-my-agent-oma-hwp && rm -rf "$T"

manifest: .agents/skills/oma-hwp/SKILL.md

source content

HWP Skill - HWP / HWPX / HWPML to Markdown Conversion

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 -> currently out of scope (may be covered by a future
```
oma-docs
```
)
Generating or editing HWP documents -> out of scope
Already-text files -> use Read tool directly

Core Rules

Use
```
bunx kordoc@latest
```
to run — no installation required. Always pass
```
@latest
```
(or a pinned version) to avoid using a stale bunx cache
Default output format is Markdown
If no output directory specified, output to the same directory as the input
kordoc handles structure preservation (headings, tables, nested tables, footnotes, hyperlinks, images)
Security defenses (ZIP bomb, XXE, SSRF, XSS) are provided by kordoc — do not add our own
For encrypted or DRM-locked HWP, report the limitation to the user clearly
After kordoc runs, post-process with
```
resources/flatten-tables.ts
```
to (a) convert HTML
```
<table>
```
blocks into GFM pipe tables and (b) strip Private Use Area characters (Hancom font-specific glyphs that render as blanks without the Hancom font). Merged-cell fidelity is traded for pure-Markdown output — this is the accepted default
Validate the output Markdown is readable and well-structured before reporting success
Report any conversion issues (missing tables, garbled text, empty output) to the user

How to Execute

resources/execution-protocol.md

step by step.

Quick Reference

Without
-o
or
-d
, kordoc prints Markdown to stdout. Always pass an output target to write a file.

Basic conversion (write next to input)

# Given input.hwp at /path/to/input.hwp, write /path/to/input.md
bunx kordoc@latest /path/to/input.hwp -o /path/to/input.md

Print to stdout (preview / pipe)

bunx kordoc@latest input.hwp
bunx kordoc@latest input.hwpx

Specify output directory (multiple files)

bunx kordoc@latest *.hwp -d ./out/

Page / section range

bunx kordoc@latest input.hwp -p 1-5
bunx kordoc@latest input.hwp -p 1,3,5

JSON output (structured)

bunx kordoc@latest input.hwp --format json

Silent mode (hide progress)

bunx kordoc@latest input.hwp --silent

kordoc CLI Flags

Flag	Description
`-o, --output <path>`	Output file path (single-file mode)
`-d, --out-dir <dir>`	Output directory (multi-file mode)
`-p, --pages <range>`	Page/section range (e.g., `1-3` , `1,3,5` )
`--format <type>`	`markdown` (default) or `json`
`--no-header-footer`	Strip PDF headers/footers (PDF only)
`--silent`	Suppress progress messages
`-V, --version` / `-h, --help`	Standard

This skill passes kordoc flags through as-is — no translation layer.

Supported Formats (official scope)

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. Those are intentionally outside this skill's scope — see "When NOT to use".

Configuration

Project-specific settings:

config/hwp-config.yaml

Troubleshooting

See

resources/troubleshooting.md

References

Execution steps:
```
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)