oma-hwp

HWP スキル - HWP / HWPX / HWPML から Markdown への変換

スケジューリング

目標

韓国語の HWP 系ドキュメントを、LLM のコンテキスト、RAG、政府文書のレビュー、または企業でのドキュメント処理に向けて、文書構造を保持しながら読みやすい Markdown または構造化 JSON に変換します。

インテントのシグネチャ

• ユーザーが .hwp、.hwpx、.hwpml の変換、解析、読み取り、抽出、または変形を依頼している。
• ユーザーが韓国語ワープロファイル、ハングル文書、政府書式、または「한글 파일」に言及している。
• ユーザーが HWP 系ファイルから見出し、表、入れ子の表、リスト、画像、脚注、またはハイパーリンクを抽出する必要がある。

使用する場合

• 韓国語の HWP ドキュメント（.hwp、.hwpx、.hwpml）を Markdown に変換する場合
• 韓国語の政府・企業ドキュメントを LLM のコンテキストまたは RAG 用に準備する場合
• HWP から構造化コンテンツ（表、見出し、リスト、画像）を抽出する場合
• ユーザーが「この HWP を変換して」「hwpx を解析して」「HWP を markdown に」「한글 파일」と依頼した場合

使用しない場合

• PDF ファイル -> oma-pdf（OCR + Tagged PDF に特化）を使用します
• XLSX / DOCX ファイル -> 対象外です。必要に応じて bunx kordoc を直接実行してください（注：oma-docs はドキュメントのドリフトを扱うスキルであり、コンバーターではありません）
• HWP ドキュメントの生成または編集 -> 対象外です（kordoc 自体は generate / fill / seal / patch / redact / lint / validate / render サブコマンドをサポートしています。必要に応じて bunx kordoc@latest <subcommand> を直接実行してください）
• すでにテキスト形式のファイル -> Read ツールを直接使用します

想定される入力

• input_path：.hwp、.hwpx、または .hwpml ファイルのパス
• output_path または output_dir：任意の明示的な出力先
• format：任意の出力形式 — markdown（デフォルト）、json（構造化 AST）、または chunks（見出しのパンくずリストと独立した表チャンクを含む、RAG 向け構造化チャンク JSON）
• page_range：任意のページまたはセクション範囲
• kordoc_version：任意の固定 kordoc バージョン

想定される出力

• 入力ファイルと同じ場所、または指定されたディレクトリに出力される Markdown
• 要求された場合の任意の JSON または RAG チャンク出力
• デフォルトで GFM の表を平坦化し、私用領域のグリフを除去した後処理済み Markdown
• 出力パス、検出されたソース形式、変換時の問題を記載した短いレポート

依存関係

• bun および bunx
• bunx kordoc@latest または設定済みの固定 kordoc バージョン
• Markdown のクリーンアップ用 resources/flatten-tables.ts
• 入力パスと出力パスへのローカルファイルシステムアクセス

制御フローの機能

• ファイル拡張子、出力先、形式、ページ範囲、暗号化／DRM の状態、後処理の要件に応じて分岐します
• bunx および bun run を通じて外部 CLI ツールを呼び出します
• ローカルの HWP 系ファイルを読み取り、ローカルに Markdown または JSON を書き出します
• このスキルの対象範囲を無理に広げず、HWP 以外の入力を他のスキルに振り分けます

構造フロー

開始

1. 入力パスが存在することを確認します。
2. 拡張子が .hwp、.hwpx、または .hwpml であることを確認します。
3. 出力パスまたはディレクトリ、およびデフォルトのファイル名を解決します。
4. bun が利用可能であることを確認します。

シーン

1. PREPARE：パス、拡張子、サイズ、出力先、要求された形式を検証します。
2. ACQUIRE：ソース形式とランタイムの利用可否を検出します。
3. ACT：明示的な出力先と要求されたオプションを指定して kordoc を実行します。
4. VERIFY：Markdown を後処理し、見出し、表、リスト、画像、脚注の構造を確認します。
5. FINALIZE：出力パス、ソース形式、変換上の制限を報告します。

遷移

• 入力が .pdf の場合は停止し、oma-pdf に振り分けます。
• 入力が .xlsx または .docx の場合、このスキルはそれらの形式を対象としていないことを説明します。
• bun を利用できない場合は停止し、Bun のインストールをユーザーに依頼します。
• Markdown が生成された場合、呼び出し元が HTML テーブルまたは PUA グリフの保持を明示的に必要としていない限り、resources/flatten-tables.ts を実行します。
• 出力が空、または文字化けしている場合は、resources/troubleshooting.md を参照します。

失敗と復旧

失敗	復旧方法
bun または bunx を利用できない	ユーザーに Bun のインストールを依頼します
サポート対象外、または形式が一致しない	拡張子とマジックバイトを確認してから、適切な処理に振り分けるか停止します
暗号化されている、または DRM でロックされているドキュメント	制限を報告し、必要に応じてアクセス可能なコピーを依頼します
Markdown の出力が空	スキャン画像の内容である可能性があるものとして扱い、このスキルの範囲外で OCR を行うよう推奨します
複雑な結合テーブル	最善の対応として、フラット化された Markdown または HTML の代替出力を受け入れます
古い kordoc キャッシュ	bunx kordoc@latest または設定済みの固定バージョンを使用します
flatten-tables.ts で Cannot find module "turndown" が発生	このスキルの resources/ ディレクトリで bun install を実行します（node_modules は gitignore 対象で、新規クローン時には存在しません）

終了

• 成功：出力ファイルが存在し、後処理後も構造を読み取れます。
• 部分的な成功：出力が存在し、テーブル、字形、暗号化、または忠実度の制限が明示的に報告されています。
• 失敗：信頼できる出力が生成されず、処理を妨げた原因が報告されています。

論理的な操作

アクション

アクション	SSL プリミティブ	根拠
ファイルパスと拡張子を検証する	VALIDATE	実行プロトコルの入力事前チェック
ランタイムの利用可否を確認する	VALIDATE	bun --version
出力先と形式を選択する	SELECT	出力動作と設定
コンバーターを実行する	CALL_TOOL	bunx kordoc@latest
出力ファイルを作成する	WRITE	Markdown または JSON の出力
テーブルをフラット化し、PUA の字形を除去する	CALL_TOOL	resources/flatten-tables.ts
抽出品質を確認する	VALIDATE	検証ステップ
結果を報告する	NOTIFY	ユーザー向けの最終概要

ツールと手段

• kordoc：HWP 系形式を変換する主要な CLI
• flatten-tables.ts：GFM テーブルへの後処理と Hancom PUA のクリーンアップ
• bun / bunx：ランタイムおよび CLI 実行ツール

標準のコマンドパス

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)

一括変換では、明示的な出力ディレクトリを指定します：

bunx kordoc@latest "{input_pattern}" -d "{output_dir}"

リソースの範囲

範囲	リソース対象
LOCAL_FS	入力 HWP 系ファイルと生成された出力
PROCESS	bunx kordoc と bun run のサブプロセス
MEMORY	形式の判断、検証メモ、最終レポート

前提条件

• 入力ファイルが存在し、読み取り可能であること。
• 出力先に書き込み可能であるか、作成できること。
• bun がインストールされていること。
• kordoc がドキュメントを解析できるか、報告可能なエラーで失敗すること。

効果と副作用

• Markdown または JSON の出力ファイルを作成します。
• Markdown との互換性を優先し、結合セルのテーブルをフラット化する場合があります。その際、セルの忠実度は低下します。
• Hancom フォントがないと空白として表示されるため、既定で私用領域の文字を除去します。
• 元の HWP 系ドキュメントを意図的に変更することはありません。

ガードレール

1. 古い bunx キャッシュを避けるため、必ず @latest または明示的な固定バージョンを指定します。
2. ユーザーがファイルを期待している場合は、必ず明示的な出力先を指定します。
3. kordoc の ZIP、XML、SSRF、XSS 対策に対する独自のセキュリティ防御を追加しないでください。
4. テーブルの欠落、文字化け、空の出力、暗号化されたセグメント、およびベストエフォートでの DRM 抽出について報告します。
5. CLI の詳細は resources/execution-protocol.md に、トラブルシューティングの分岐は resources/troubleshooting.md に記載します。

サポート対象形式

形式	拡張子	備考
HWP 5.x バイナリ	.hwp	完全対応（kordoc の rhwp-algorithm 移植版による DRM ロックへの対応を含む）
HWPX	.hwpx	ネストされたテーブル、結合セルを含め完全対応
HWPML	.hwp（XML 形式）	シグネチャに基づいて自動検出

kordoc は PDF / XLSX / DOCX も解析でき、ドキュメント作成サブコマンド（generate、fill、seal、patch、redact、lint、validate、render）も提供します。これらはすべて意図的にこのスキルの対象外です。「使用しない場合」を参照してください。変換品質フラグ（--dedupe-headers、--keep-empty-cols、--inline-images）と chunks 形式については、resources/execution-protocol.md に記載されています。

参考資料

• 実行プロトコル：resources/execution-protocol.md
• トラブルシューティング：resources/troubleshooting.md
• 設定：まず .agents/oma-config.yaml の hwp: セクションを読み、設定されていないキーについては config/hwp-config.yaml を参照してください（supported_formats はスキル設定にのみあります）。ユーザーによる上書き設定は .agents/oma-config.yaml に記述してください。oma update によってスキル設定が上書きされるためです。
• 上流： https://github.com/chrisryugj/kordoc
• 関連：.pdf の入力には ../oma-pdf/SKILL.md を使用してください