SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsdoc-hwp

doc-hwp

Office & productivity

View repository

Updated 10-15 21:03

About this skill

Hangul Document Writer (HWPX Writer)

Overview

Creates documents in HWPX format. HWPX is a ZIP containing OWPML (Open Word Processor Markup Language) XML, so python-hwpx if the library is available, use its API (Path A); if not, use Python stdlib zipfileto assemble the XML directly (Path B). You can create official documents, drafts, and reports compatible with Hancom Office (Hwp), convert existing HWP files to HWPX, or extract text.

Trigger Keywords

Hangul, hwpx, Arae-A Hangul, Hancom, official document, HWP conversion, Hangul document creation, HWPX editing

Workflow

Step 1: Analyze document requirements

After analyzing the user's request, determine the task type:

  • Create new HWPX: official documents, drafts, reports, meeting minutes
  • HWP → HWPX conversion: convert older Hangul files to the latest format
  • Text extraction: extract content from existing HWPX
  • Fill forms: preserve template layout and modify only the content

Step 2: Determine format + determine generation path

Determine format (required for formal documents such as official documents, drafts, approval requests, etc.): references/kr-official-forms.mdand apply the structure of opening, body, and closing, document number, enforcement date (YYYY. M. D.), recipient/carbon copy, item numbering system (1.→가.→1)→가)), 붙임 n부. 끝., sender name, and approval box/final approval notation according to the format. For the concrete layout (margins, fonts, placeholders), use the templates below ( references/templates/ official document gonmun, report report, meeting minutes minutes, proposal proposal, common base).

Determine generation path (choose one of two paths)

  • Path A — use python-hwpx if it is available in the environment (convenient if present, otherwise Path B): 
    python -c "import hwpx" 2>/dev/null && echo "python-hwpx 사용 가능" || echo "경로 B(직접 XML 조립) 사용"
# 없고 설치 가능하면: pip install python-hwpx lxml  (HWP 바이너리 처리 시 olefile 추가)
  • Path B — assemble ZIP+XML directly without a library (default path): HWPX is a ZIP containing OWPML (XML) files, so it can be assembled with only Python stdlib zipfile. Execute the Step 3 inline code as is.

Step 3: Generate document

Path A (when python-hwpx is available):

from hwpx import HwpxDocument

hwp = HwpxDocument.new()
# 단락 추가·표 삽입·서식 적용은 python-hwpx API(add_paragraph, add_table 등)로 수행
hwp.save("output.hwpx")

Path B (stdlib only, default path): HWPX = ZIP(mimetype + version.xml + Contents/content.hpf + Contents/section0.xml 등)을 zipfilewrite directly. Minimal skeleton:

import zipfile

# section0.xml — OWPML 본문(단락·표). 실제로는 <hp:p> 단락, <hp:tbl> 표를 필요한 만큼 채웁니다.
section = """<?xml version="1.0" encoding="UTF-8"?>
<hs:sec xmlns:hs="http://www.hancom.co.kr/hwpml/2011/section"
        xmlns:hp="http://www.hancom.co.kr/hwpml/2011/paragraph">
  <hp:p><hp:run><hp:t>여기에 본문 단락 텍스트</hp:t></hp:run></hp:p>
</hs:sec>"""

with zipfile.ZipFile("output.hwpx", "w", zipfile.ZIP_DEFLATED) as z:
    z.writestr("mimetype", "application/hwp+zip")           # 반드시 첫 엔트리
    z.writestr("version.xml", '<?xml version="1.0"?><hv:HCFVersion xmlns:hv="http://www.hancom.co.kr/hwpml/2011/version"/>')
    z.writestr("Contents/section0.xml", section)
    # 실제 배포용은 header.xml(글꼴·문단모양)·content.hpf(패키지 매니페스트)를 함께 채웁니다.

Path B is a minimal skeleton. For complex documents such as forms, tables, and headers, using python-hwpx (Path A) is recommended; if the library is not available, extend the above XML with paragraph and table elements according to the OWPML spec and assemble it.

Step 4: Validate OWPML structure

Validate directly with stdlib whether the generated HWPX complies with the OWPML spec — check ZIP integrity and required XML well-formedness:

import zipfile, xml.etree.ElementTree as ET

with zipfile.ZipFile("output.hwpx") as z:
    assert z.testzip() is None, "ZIP 손상"
    names = z.namelist()
    assert "mimetype" in names and "Contents/section0.xml" in names, "필수 엔트리 누락"
    ET.fromstring(z.read("Contents/section0.xml"))   # XML well-formed 검증 (실패 시 ParseError)
print("OWPML 기본 구조 OK — 한컴오피스에서 최종 열림 여부는 사용자가 확인")

Usage Examples

  • "Create a Hangul file requesting cooperation in the official document format"
  • "Convert the existing HWP file to HWPX"
  • "Draft the approval request in the HWP draft document format"
  • "Extract text from the HWPX file"
  • "Verify that the HWP document content has a valid OWPML structure"

Output Format

  • File Format: .hwpx (Hancom Office 2010+ standard)
  • Standard: OWPML 1.5 (Open Word Processor Markup Language)
  • Compression: ZIP-based (XML + resource files)
  • HWP Compatibility: Opens correctly in Hancom Office 2014, 2018, 2020

Precautions

Stable Features vs Limited Features

Feature Status Notes
Add Paragraph Stable Basic feature
Bold/Italic/Underline Stable lxml patch applied automatically
Table Stable No row/column limit
Header/Footer Stable -
Footnotes/Endnotes Stable -
Bookmark Stable -
Text Replacement Stable -
Shapes (Line/Rectangle/Ellipse) Limited May cause error warnings in HWP
Image Insertion Limited Creates incomplete pic elements
Multi-column Settings Limited May cause error warnings in HWP

Hancom Office Environment

HWPX files open optimally in Hancom Office. In environments where Hancom Office is not installed, moai-officer:doc-docx we recommend using the skill.

Font Compatibility

Hancom-exclusive fonts (HYHeadLine, HYGothic, etc.) display correctly only in environments with Hancom Office installed. When distributing, embedding fonts or converting to PDF is recommended.

HWP Conversion Limitations

Conversion limitations may apply depending on the HWP file version (2010/2014/2018, etc.). Older HWP versions may only support text extraction.

Troubleshooting

Situation Solution
File creation failed (Path A) Check whether python-hwpx and lxml are installed (pip install python-hwpx lxml) and retry, or switch to Step 3 Path B (stdlib zipfile assembly)
HWPX Library Not Installed If python-hwpx is not available, use Step 3 Path B (assemble ZIP+XML directly without the library) — installation is optional
HWP Conversion Error Check the HWP file version (2010/2014/2018, etc.). Older versions may have conversion limitations
OWPML Structure Error Use the Step 4 inline validation code (zipfile + ElementTree) to check ZIP integrity and XML well-formedness, and if you share the error details, we will help you fix them
Font Corruption Hancom-exclusive fonts (HYHeadline, HYGothic, etc.) display correctly only in an environment where Hancom Office is installed
Does not open in Hangul Check the OWPML namespace and verify that the XML header is correct

Related skills / self-review

Once Hangul document generation is complete, reopen the produced .hwpx file to check for remaining placeholders, OWPML structure, broken Hangul encoding, and broken tables, self-reviewand if there are issues, automatically fix and regenerate them, then report the final PASS/FAIL result.

  • moai-officer:doc-docx - Generating DOCX (Word) documents
  • moai-officer:doc-pptx - Generating PPT slides for presentations
  • moai-officer:doc-xlsx - Generating Excel data sheets

Technical references

Korean copy quality gate (required)

Korean text produced by this skill must pass a mandatory gate before distribution:

  1. moai-coworker:ai-slop-reviewer — First-pass general AI slop review (banned words, structural patterns, rhythm)
  2. moai-writer:korean-humanize — Second-pass precise Korean editing (40+ pattern SSOT, meaning unchanged)

The two gates catch S1 patterns such as headlines with em dashes, particles, sentence fragments ending in nouns, and the "from A to B" transition formula. Outputs are not distributed directly without passing the gate.

Standard-format protection — The output of this skill is a standard-format document. Slop review only performs banned-word replacement and does not rewrite the structure (itemized format, item numbering system, opening/body/closing).

Detailed reference

File Load condition
references/kr-official-forms.md When drafting standard-format documents such as official letters, drafts, and approval requests (mandatory for workflow step 2 — SSOT for opening/body/closing, item numbering system, attachments/end mark, approval box, and prior approval notation)
references/guide.md When a detailed guide for HWPX generation overall is needed (library usage, document assembly procedures)
references/owpml-spec.md When spec references such as OWPML XML namespaces and section file structure are needed for HWPX editing
references/format-converter.md When an agent is needed for conversion between HWPX, PPTX, DOCX, and XLSX formats or template-based document generation
references/templates/base.md When common page, font, and style defaults are needed for all HWPX templates
references/templates/gonmun.md When generating official documents (enforcement documents) (layout based on the attached forms of the "Regulations on Administrative Efficiency and Promotion of Collaboration")
references/templates/report.md When generating report HWPX
references/templates/minutes.md When generating meeting minutes HWPX
references/templates/proposal.md When generating proposal HWPX