К основному содержанию
скилл CX Codex

oma-hwp · first-fluke — скилл для Claude Code: конвертирует HWP в Markdown

Скилл oma-hwp превращает корейские документы HWP, HWPX и HWPML в Markdown через kordoc. Извлекает текст, таблицы, списки, изображения и сноски.

MIT ★ 1 472 обновлён 2026-10-29

Установить в Claude Code · Через маркетплейс плагинов Все способы и платформы ↓
/plugin marketplace add first-fluke/oh-my-agent
/plugin install oma@oh-my-agent
Открыть на GitHub

Что делает oma-hwp

Скилл вызывает bunx kordoc для преобразования файлов .hwp, .hwpx и .hwpml в читаемый Markdown или JSON. Умеет вытаскивать заголовки, вложенные таблицы, списки, картинки, сноски и гиперссылки. После конвертации запускает постобработку через resources/flatten-tables.ts: приводит таблицы к GFM и убирает глифы из Private Use Area.

Требует Bun и bunx. При первом запуске нужно выполнить bun install в папке resources/ скилла, так как node_modules там игнорируется git. Зашифрованные или защищённые DRM документы не поддерживаются — скилл сообщит об ограничении и попросит доступную копию.

Выдаёт файл Markdown рядом с исходником или в указанную папку, плюс краткий отчёт: путь к выходному файлу, формат источника и найденные проблемы конвертации. Умеет работать с диапазонами страниц и выводить структурированный JSON для RAG, где каждый чанк содержит breadcrumbs заголовков.

Какие задачи решает

  • преобразовать корейский HWP-документ в Markdown для LLM
  • извлечь таблицы и заголовки из HWPX-файла
  • подготовить правительственные формы из HWP для RAG
  • вытащить текст и изображения из HWPML
  • привести сложные вложенные таблицы HWP к читаемому виду

Примеры запросов агенту

  • Преобразуй contract.hwp в Markdown
  • Извлеки таблицы из government-form.hwpx в JSON для RAG
  • Конвертируй все HWPML-файлы из папки docs/ в Markdown

Как установить oma-hwp

1Через маркетплейс плагинов

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

Команда ставит плагин oma целиком, со всеми его скиллами

2Через Skills CLI (Vercel)

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

3Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/oma-hwp/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об oma-hwp

Как установить oma-hwp в Claude Code?

Выполни /plugin marketplace add first-fluke/oh-my-agent, затем /plugin install oma@oh-my-agent. После этого запусти npx skills add first-fluke/oh-my-agent --skill oma-hwp -a claude-code и открой ~/.claude/skills/oma-hwp/SKILL.md.

Что делает oma-hwp?

Конвертирует корейские документы HWP, HWPX и HWPML в Markdown или JSON через kordoc. Извлекает текст, таблицы, списки, изображения, сноски и гиперссылки, сохраняя структуру документа.

Что нужно для работы oma-hwp?

Требуется Bun и bunx. При первом запуске выполни bun install в папке resources/ скилла, так как node_modules там игнорируется git. Зашифрованные и защищённые DRM документы не поддерживаются.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Документы и офис» →

Сначала — oma-hwp от других авторов.

oma-hwp First Fluke Скилл oma-hwp конвертирует южнокорейские текстовые документы HWP, HWPX и HWPML в Markdown или JSON для передачи контекста в LLM и базы RAG. CX Codex +1 ★ 1 472звёзд репо hwp NomaDamas Парсит корейские документы HWP и HWPX через библиотеку kordoc. Запускается при команде агенту «прочитай .hwp» или «преобразуй Markdown в HWPX». CX Codex +1 14 100установок claw-hwp DoHyun468 Плагин claw-hwp читает, создаёт и редактирует корейские документы HWP и HWPX в Claude Code без сторонних офисных пакетов. ★ 226звёзд репо kordoc-korean-document-parser reason-machines Скилл kordoc-korean-document-parser для Claude Code разбирает корейские документы HWP 5.x, HWPX и PDF в Markdown и структурированные блоки. Вытаскивает текст, таблицы и поля формы. CX Codex +1 782установок kordoc chrisryugj MCP-сервер kordoc парсит документы HWP, HWPX, PDF, таблицы и сканы в Markdown без внешних сервисов. Даёт агенту инструменты для заполнения форм и сравнения версий. CX Codex +1 ★ 3 092звёзд репо html-to-ppt claude-office-skills Скилл html-to-ppt для Claude Code превращает Markdown или HTML в слайды PowerPoint, PDF и HTML через Marp. Собирает презентацию из готового текстового черновика. CX Codex +1 5 200установок dedot LilMGenius Скилл dedot для Claude Code проверяет средние точки в корейском тексте и предлагает замену для открытых перечислений. Запускается по запросу редакторской правки. CX Codex +1 130установок

Из того же набора69

Весь набор →
oma-search Скилл oma-search для Claude Code выбирает канал поиска документации, веб-материалов, кода или файлов проекта и помечает результаты метками доверия. Определяет, где искать, если источник неясен. CX Codex +1 ★ 1 472звёзд репо oma-image Скилл oma-image генерирует изображения через несколько провайдеров сразу — Codex, Pollinations, Gemini — и подхватывает референсы для вариаций по стилю и композиции. CX Codex +1 ★ 1 472звёзд репо oma-architecture Скилл oma-architecture помогает проектировать границы модулей и сервисов, сравнивать альтернативные решения и оформлять архитектурные решения в формате ADR. CX Codex +1 ★ 1 472звёзд репо oma-coordination Скилл oma-coordination помогает вручную координировать работу нескольких специализированных агентов. Он раскладывает задачу по этапам, отслеживает договорённости между командами и доводит работу до QA-проверки. CX Codex +1 ★ 1 472звёзд репо oma-pdf Скилл oma-pdf конвертирует PDF-документы в Markdown с сохранением таблиц, заголовков и списков. Запускается при подготовке файлов для RAG и контекста LLM. CX Codex +1 ★ 1 472звёзд репо oma-market Скилл oma-market собирает сигналы рынка из сообществ и оформляет их в краткий отчёт о болях клиентов, трендах или конкурентах. CX Codex +1 ★ 1 472звёзд репо oma-video Создаёт видео через CLI OMA video или обрабатывает готовый клип: извлекает кадры, режет паузы, собирает дубляж. CX Codex +1 ★ 1 472звёзд репо oma-skill-creator Скилл oma-skill-creator создаёт, форматирует и проверяет скиллы OMA в стандарте SSL-lite с четырьмя обязательными блоками внутри .agents/skills/. CX Codex +1 ★ 1 472звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой