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

oma-hwp · first-fluke, oma — скилл для Claude Code: что делает и как установить

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

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

Скилл разбирает файлы корейского текстового процессора Hancom Office через утилиту kordoc. Он извлекает заголовки, списки, изображения, сноски, ссылки и таблицы. После базовой конвертации запускается встроенный скрипт flatten-tables.ts, который преобразует сложные объединённые ячейки в плоский формат GitHub Flavored Markdown и вырезает символы Private Use Area, отображающиеся пустыми без фирменных шрифтов.

Для работы требуется установленный в системе bun. Если рантайма нет в путях, скилл остановит выполнение и попросит поставить Bun на машину. Скилл предназначен только для чтения: создавать или редактировать исходные файлы HWP он не умеет, а документы под защитой DRM или паролем обработать не сможет.

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

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

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

  • Переведи этот отчёт report.hwpx в Markdown и сохрани рядом
  • Извлеки структуру и таблицы из government-form.hwp в JSON
  • Сконвертируй все файлы .hwp из папки incoming в директорию markdown-out

Как установить 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.

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

В операционной системе должен быть установлен рантайм bun, так как утилита kordoc и скрипт постобработки таблиц вызываются через bunx и bun run.

Умеет ли oma-hwp редактировать файлы HWP?

Нет, скилл работает только на извлечение содержимого в Markdown или JSON. Генерация и изменение исходных файлов HWP не поддерживаются.

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

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

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

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

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

oma-hwp First Fluke Скилл oma-hwp превращает корейские документы HWP, HWPX и HWPML в Markdown через kordoc. Извлекает текст, таблицы, списки, изображения и сноски. 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звёзд репо markitdown K-Dense-AI Скилл markitdown для Claude Code переводит документы и выбранные URI в Markdown для поиска, анализа текста и LLM/RAG. CX Codex +1 2 400установок rhwp-edit NomaDamas Скилл rhwp-edit для Claude Code редактирует файлы HWP через агента: заменяет текст, создаёт таблицы и заполняет ячейки без запуска офисного пакета. CX Codex +1 12 200установок

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

Весь набор →
oma-pm Скилл oma-pm превращает требования к продукту в план задач с приоритетами, зависимостями и критериями приёмки. Пригодится перед передачей работы специализированным агентам. CX Codex +1 ★ 1 472звёзд репо oma-brainstorm Скилл oma-brainstorm для Claude Code исследует замысел, ограничения и варианты решения до планирования или разработки. Уточняет неясную идею. CX Codex +1 ★ 1 472звёзд репо oma-pm Скилл oma-pm для Claude Code и Codex декомпозирует требования к продукту в дерево задач с зависимостями и критериями приёмки. Готовит артефакты планирования для субагентов и оркестратора. CX Codex +1 ★ 1 472звёзд репо oma-design Скилл oma-design определяет визуальное направление проекта и ведёт файл DESIGN.md с контрактом дизайн-системы. Выбирает внешний дизайн-скилл — Interface Design, Taste или Impeccable — под конкретную задачу. CX Codex +1 ★ 1 472звёзд репо 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звёзд репо

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

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