Skip to content

oliverv/caro / .agents/skills/oma-hwp

oma-hwp

Flagged

Convert Hangul HWP, HWPX, or HWPML documents to Markdown with kordoc. Use for text, table, and image extraction from these formats.

resources/execution-protocol.md

View on GitHub
# HWP Conversion - Execution Protocol

## Step 0: Validate Input

1. Confirm the input file path exists
2. Check extension is one of `.hwp`, `.hwpx`, `.hwpml`
   - If `.pdf` -> hand off to `oma-pdf`
   - If `.xlsx` / `.docx` -> not in scope; advise user to run `bunx kordoc@latest <file>` directly
3. Check file size (`wc -c` or `ls -lh`); warn if >100MB
4. Determine output location:
   - If user specified output path (`-o` or `-d`) → use it
   - Otherwise → same directory as the input file
5. Determine output filename: `{input_basename}.md`

## Step 1: Check Runtime

```bash
bun --version
```

If `bun` is not available, ask the user to install Bun (https://bun.sh). `bunx` is required.

## Step 2: Convert

> **Important**: Without `-o` or `-d`, kordoc prints the Markdown to **stdout** and does not create a file. Always pass an explicit output path to match this skill's "same directory as input" convention.

### Standard conversion (single file, write next to input)
```bash
bunx kordoc@latest "{input_path}" -o "{output_path}"
# {output_path} = "{dirname(input_path)}/{basename_without_ext(input_path)}.md"
```

### Output directory (multiple files)
```bash
bunx kordoc@latest "{input_pattern}" -d "{output_dir}"
```

### Print to stdout (piping / preview)
```bash
bunx kordoc@latest "{input_path}"
# No file written; useful when piping to another tool
```

### Page / section range
```bash
bunx kordoc@latest "{input_path}" -p "{range}"
```

### JSON output (structured intermediate form)
```bash
bunx kordoc@latest "{input_path}" --format json
```

### RAG chunks output (structural chunk JSON)
```bash
bunx kordoc@latest "{input_path}" --format chunks
```
Emits RAG-oriented structural chunks: each chunk carries a heading / outline-hierarchy breadcrumb, and tables become standalone chunks. Prefer this over plain Markdown when the user is preparing HWP content for RAG ingestion or embedding pipelines.

### Conversion-quality flags (HWP-family relevant)
| Flag | Effect | When to use |
|------|--------|-------------|
| `--dedupe-headers` | Removes running headers repeated per page in HWP5 layout tables (default off) | Paginated forms where the same header row repeats; beware: may over-remove per-attachment renumbering |
| `--keep-empty-cols` | Preserves trailing empty table columns (form input fields); default trims them | Government form templates where blank fill-in columns are meaningful |
| `--inline-images` | Inlines images as base64 data URIs (BMP→PNG compression, HWP5 only) | Single self-contained Markdown file needed; skips writing an assets directory for inlined images |

Notes:
- Default format is `markdown`. Pass `--format json` for the structured AST, `--format chunks` for RAG chunks.
- `--silent` suppresses progress output, useful in automation / piping contexts.

## Step 2.5: Post-process kordoc output (default)

`resources/flatten-tables.ts` cleans up two kordoc artifacts that hurt downstream use:

1. **HTML `<table>` blocks**: kordoc emits these when a table has `colspan` / `rowspan` because GFM cannot represent merged cells. Converted to GFM pipe tables via `turndown-plugin-gfm`.
2. **Private Use Area characters**: HWP references Hancom-font-specific glyphs via U+E000-U+F8FF / U+F0000-U+FFFFD / U+100000-U+10FFFD code points. Without the Hancom font these render as blanks or tofu squares. Silently stripped.

```bash
bun "{skill_resources}/flatten-tables.ts" "{output_path}"
```

- `{skill_resources}` = this skill's `resources/` directory (`.agents/skills/oma-hwp/resources` in project mode, `~/.agents/skills/oma-hwp/resources` in global mode)
- Ensure `bun install` has been run once inside that directory (it installs `turndown` + `turndown-plugin-gfm` locally)
- Merged cells get flattened during the conversion (accepted trade-off)
- Skip this step only if the caller explicitly needs HTML tables or PUA characters preserved (rare)

## Step 3: Verify

1. Read the generated Markdown file
2. Verify structure:
   - Headings preserved (`#`, `##`, etc.)
   - Tables rendered (GFM pipe syntax, or HTML `<table>` fallback for merged cells)
   - Lists maintained (bullets, numbered)
   - Images referenced (relative paths or inline)
   - Footnotes linked via `[^id]`
3. If the file is empty or clearly garbled, consult `troubleshooting.md`
4. If output directory is temporary, move the file to the target location
5. If the user needs the content in-conversation, read and present it

## Step 4: Report

Tell the user:
- Output file path
- Source format detected (HWP5 / HWPX / HWPML)
- Any issues encountered (encrypted segments, missing tables, best-effort DRM extraction)
- Page/section count if available

## Error Recovery

| Error | Recovery |
|-------|----------|
| `bunx` / `bun` not found | Ask user to install Bun: `curl -fsSL https://bun.sh/install \| bash` |
| `지원하지 않는 파일 형식` / `unsupported file format` | Confirm extension matches actual content; check magic bytes |
| `암호화된 문서` / `encrypted document` | Ask user for password; current kordoc CLI may not accept it inline (document as limitation) |
| Empty Markdown output | Likely a scanned-image-only HWP; suggest OCR pipeline (out of this skill's scope) |
| Broken / missing tables | Complex merged-cell tables fall back to HTML `<table>`; accept as best-effort |
| kordoc crash or stack trace | Ensure `@latest` is passed (bunx cache can be stale); if persistent, capture fixture and file issue upstream at https://github.com/chrisryugj/kordoc/issues |
| Slow conversion on large files | Use `-p` to narrow the page range; process sections separately |

## Pin vs Latest

- **Default**: `bunx kordoc@latest` (always latest). Gets upstream fixes automatically. `@latest` is required because a bare `bunx kordoc` can reuse a stale cached version indefinitely.
- **Reproducibility**: pin with `bunx kordoc@4.7.3 ...` or similar. Record the pinned version under `hwp.version` in `.agents/oma-config.yaml` (`channel: pinned`, `pinned: "4.7.3"`). Do not edit `config/hwp-config.yaml` — `oma update` overwrites it.

## Scope Reminder

If the user hands you a `.pdf` / `.xlsx` / `.docx` with this skill activated, **do not proceed**. Redirect:

- `.pdf` → switch to `oma-pdf`
- `.xlsx` / `.docx` → ask the user to run `bunx kordoc@latest <file>` directly; this skill does not advertise those formats

Likewise, document **authoring / editing** requests are out of this skill's scope even though kordoc supports them. Point the user at the subcommand directly:

| Request | kordoc subcommand |
|---------|-------------------|
| Generate HWPX from Markdown | `bunx kordoc@latest generate <md> -o <hwpx>` |
| Fill form blanks | `bunx kordoc@latest fill <template> -f 'k=v,...' -o <out>` |
| Place stamp/signature image | `bunx kordoc@latest seal <file> --image <png> --anchor "(인)" -o <out>` |
| Apply edited Markdown back to original | `bunx kordoc@latest patch <original> <edited-md> -o <out>` |
| Mask personal data (주민번호 etc.) | `bunx kordoc@latest redact <files...>` |
| Check official-document notation | `bunx kordoc@latest lint <file>` |
| Validate HWPX structure | `bunx kordoc@latest validate <file>` |
| Layout-preserving SVG render | `bunx kordoc@latest render <file> -o <svg>` |

kordoc technically supports all of the above, but routing keeps skill scopes clean.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall