oma-hwp · first-fluke, oma — Claude Code skill: what it does, how to install
oma-hwp converts Korean HWP, HWPX, and HWPML documents into Markdown or JSON for LLM prompts and retrieval pipelines.
MIT ★ 1,472 updated 2026-10-29
/plugin marketplace add first-fluke/oh-my-agent
/plugin install oma@oh-my-agentWhat oma-hwp does
The skill transforms South Korean word processor documents into clean Markdown or JSON via kordoc. It parses nested tables, headings, footnotes, hyperlinks, lists, and images. Once parsed, it runs flatten-tables.ts to flatten merged cells into GitHub Flavored Markdown tables and strip Private Use Area glyphs that appear blank without Hancom system fonts.
Local execution depends on bun. Without bun and bunx in your environment, the skill aborts immediately. The workflow handles extraction only: it does not author new HWP files, cannot unlock encrypted DRM documents, and routes PDFs or spreadsheets to separate tools.
What it helps with
- convert HWP and HWPX files to Markdown for AI processing
- parse Korean government documents into structured JSON
- extract tables and footnotes from HWPML archives
- strip broken Hancom PUA glyphs from converted text
Example prompts for the agent
- Convert document.hwpx to markdown and save it in the current folder
- Parse the tables and headings from report.hwp into structured JSON
- Batch convert all .hwp files in ./docs into ./output
How to install oma-hwp
1Plugin marketplace
/plugin marketplace add first-fluke/oh-my-agent/plugin install oma@oh-my-agentThis 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-code3Manually: put the files in place
~/.claude/skills/oma-hwp/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/oma-hwp/
1Skills CLI (Vercel)
npx skills add first-fluke/oh-my-agent --skill oma-hwp -a codex2Manually: put the files in place
.agents/skills/oma-hwp/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add first-fluke/oh-my-agent --skill oma-hwp -a cursor2Manually: put the files in place
.cursor/skills/oma-hwp/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install first-fluke/oh-my-agent benchmarks/runs/oma/.agents/skills/oma-hwp2Manually: put the files in place
.github/skills/oma-hwp/SKILL.md1Skills CLI (Vercel)
npx skills add first-fluke/oh-my-agent --skill oma-hwp -a gemini-cli2Platform CLI
gemini skills install https://github.com/first-fluke/oh-my-agent --path benchmarks/runs/oma/.agents/skills/oma-hwpManually: put the files in place
.devin/skills/oma-hwp/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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?
Register the marketplace repository with /plugin marketplace add first-fluke/oh-my-agent, then run /plugin install oma@oh-my-agent.
What system requirements does oma-hwp have?
You must have bun installed locally, because the conversion workflow invokes bunx kordoc and runs its cleanup script via bun run.
Can oma-hwp create or modify HWP files?
No, it is strictly an extraction skill designed for reading and transforming existing HWP-family documents into text formats.
Source text
SKILL.md · MIT
---
name: oma-hwp
description: >
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.
---
# 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 -> 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
### 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
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 |
### 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}"
bun run ".agents/skills/oma-hwp/resources/flatten-tables.ts" "{output_path}"
```
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. Those are intentionally outside this skill's scope — see "When NOT to use".
## References
- Execution protocol: `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)
© First Fluke · MIT · first-fluke/oh-my-agent
Similar skills
All skills for Office documents →oma-hwp by other authors comes first.