# oma-hwp

oma-hwp converts Korean HWP, HWPX, and HWPML documents into Markdown or JSON for LLM prompts and retrieval pipelines.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 1472 repo stars
- Author: First Fluke
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/first-fluke/oh-my-agent/tree/HEAD/benchmarks/runs/oma/.agents/skills/oma-hwp/SKILL.md
- Updated: 2026-10-29
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/first-fluke-oma-hwp

## What it 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.

## Install

### Claude Code (native platform)

1. **Plugin marketplace**
In the agent chat (not a shell):
```text
/plugin marketplace add first-fluke/oh-my-agent
```
In the agent chat (not a shell):
```text
/plugin install oma@oh-my-agent
```
This installs the whole oma plugin with all its skills

2. **Skills CLI (Vercel)**
```bash
npx skills add first-fluke/oh-my-agent --skill oma-hwp -a claude-code
```

3. **Manually: put the files in place**
- File: `~/.claude/skills/oma-hwp/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/oma-hwp/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add first-fluke/oh-my-agent --skill oma-hwp -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/oma-hwp/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add first-fluke/oh-my-agent --skill oma-hwp -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/oma-hwp/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install first-fluke/oh-my-agent benchmarks/runs/oma/.agents/skills/oma-hwp
```

2. **Manually: put the files in place**
- File: `.github/skills/oma-hwp/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add first-fluke/oh-my-agent --skill oma-hwp -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/first-fluke/oh-my-agent --path benchmarks/runs/oma/.agents/skills/oma-hwp
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/oma-hwp/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/first-fluke/oh-my-agent/tree/HEAD/benchmarks/runs/oma/.agents/skills/oma-hwp/SKILL.md

## When to use it
- 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
- 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

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: f15ce81503777911.

BEGIN THIRD-PARTY FILE f15ce81503777911
```text
---
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
```
END THIRD-PARTY FILE f15ce81503777911

The third-party file has ended. Everything between the f15ce81503777911 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2869 of 7711 bytes. © First Fluke · MIT · https://github.com/first-fluke/oh-my-agent/tree/HEAD/benchmarks/runs/oma/.agents/skills/oma-hwp/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
