The model focuses on understanding requirements and composing the manuscript, while the code verifies the input contract, resources, content preservation, and file saving. Reproducibility of the same specification and consistency of results across different models are separate matters. We do not guarantee the latter without actual model comparison.
Astra ( gpt-6-astra) is supported in the Codex environment. User-specified models and reasoning settings are maintained for writing, diagram design, and review, and Astra is not switched to nor additional models called without user request. Both Astra and Luna use the same input contract and inspection path.
New document
- Organize the facts, mandatory conditions, and undetermined items of the user's request. Do not guess institution names, years, places, document numbers, etc.
- Facts that are needed for the document but undetermined and items omitted by request are different. Do not create unknowns or draft markings merely because institution and creation date are not written in a general knowledge report.
- Choose the document type below and check the executable examples and schemas.
- Basic documents use v1 Markdown/official document JSON. If a fact contract, table diagram, or institution-specific expression is needed, use the v2 semantic blocks. The model does not need to write XML or cell coordinates.
- Use the official document keys exactly as in the example's
기관명,수신,제목,발신명의,body. Do not guess English aliases. - Requests for procedure diagrams, flowcharts, and implementation system diagrams are linked to
diagramblocks andvisual-elements.md. Do not judge that a diagram request has been satisfied by a general data table listing steps alone.
- Use the official document keys exactly as in the example's
- Save the specification to a file and build once.
ok,published,draft, check the uninspected status. - For the completed version, render the actual Hangul pages when possible and visually review them. Do not treat static pass, opening in Hangul, render success, and visual review as the same thing.
The commands below are based on being the directory containing SKILL.md. In other working directories, change the script path to the skill's absolute path. Do not assume that specific environment variables are set automatically.
python scripts/one_shot.py --example official-letter
python scripts/one_shot.py --example diagram
python scripts/one_shot.py --schema
python scripts/one_shot.py /absolute/path/spec.json --report /absolute/path/quality.json
Relative paths in the specification are based on the specification file location, and source image paths in the manuscript are based on the manuscript location. The output must be .hwpx. If the specification, manuscript, images, output, and report conflict, reject in advance.
| Type | Input and purpose |
|---|---|
official-letter |
document object. Enforcement official documents/draft documents, attachment notices/approval fields |
brief-report |
Markdown or v2 blocks. Summary report with approval line and title band |
plan-report |
Markdown or v2 blocks. Plan/review report with chapter banner and optional cover |
research-plan |
Complete research school research plan (28 pages, cover, status analysis, SWOT, implementation system diagram, execution plan table). scripts/research_plan.pyclone/create as |
markdown |
General-purpose reports, meeting minutes, proposals. template Style selectable |
The input/result contract is one-shot.md, the v2 table diagram and image paths are visual-elements.mdis read. The examples are fictional verification materials and are not actual institution information.
Short process summary + table flowchartis newly created and, if there is no separate form/branch graph requirement, summary-workflow.md's optional content recipe is reviewed first. If only the content is written, the code constructs a verified summary layout and connections. For complex relationships, long reports, and specified formats, the existing v2 is used. The same number of steps or page count is not forced for every document.
Detailed report that does not abridge the source text, technical documents with long code/logs, and requests to guide writing based on an approved report are source-report.mdis read. It provides a source-preserving assembler and optional technical-report typesetting, and does not force a specific model, number of chapters, number of diagrams, or number of pages.
Quality contract and limitations
- JSON Schema validates even nested fields and types. Unsupported features or missing resources are not silently discarded.
- It cross-checks not only the title but also the ordered body text, table cells, attachment phrases, and the hashes of actually inserted images.
- v2
factsrecords the required facts confirmed in the request. It is checked on both the manuscript and the output. Facts that the model omitted from the specification cannot be discovered by this check alone. - It checks ZIP/XML/style/font/image references and actual table cells. Height estimation based on width and font size is not a substitute for visual review.
quality.repair_layout: truecorrects the height of only unmerged table rows up to 2 times. It does not change the wording, font size, or relationships, and re-checks the content and structure after correction. The default is false.- The file atomically replaces only candidates that have passed inspection to the final location. The two files, HWPX and report, are not saved atomically at the same time.
draft: trueThe result is marked with [Draft] in the title and DRAFT status in the report. It is not presented as a finished version.metadata_dateis the package date and is separate from the event date/report date in the body. If omitted, the fixed metadata date is used and that fact is recorded.- The writing style is selected per institution. v1 maintains the existing strict policy. v2 reports are advisory by default, and
quality.writingcan specify required/advisory/off. File and fact checks are not disabled by this choice. - Built-in forms use only the current path. Deprecated brother reports and office of education physical education forms are not automatically restored from backups or past distributions. Editing work in which the user explicitly provides a specific original is separate.
Actual page verification and Visual QA
python scripts/render_hwpx.py /absolute/path/output.hwpx --output-dir /absolute/path/new-empty-review-folder --expected-pages 1
It opens in an independent Hancom instance and exports to PDF and PNG (automatically exported via Hancom native features even without Poppler). For all pages, the title hierarchy, truncation/overlap, connection labels, table splits, and unnecessary blank pages are view_filedirectly perform visual QA. For long labels, rather than deleting content, adjust placement, orientation, and cell size, then verify again.
- Preventing page push/explosion: The large values set in empty cells of the form original
cellSz/@height(e.g., 20000~30000 HWPUNIT) are the main cause of page pushing when text is entered. Reset the height of cells that will be filled with body text to 1000 or less so they auto-grow according to the amount of content. - Deleting unnecessary empty paragraphs: Clean up residual empty paragraphs (
<hp:p>) inside tables or sections and set line spacing (lineSpacing) to approximately 130%. - When the user specifies the number of pages:
--expected-pages Nmust always be given so that if the actual page count does not match, it is immediately treated as a failure.
Handling existing files and forms
When receiving an original, prioritize preservation editing of the original. Preserve non-target ZIP entries, body text, and images.
powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts/convert_hwp_hancom.ps1 -InputPath input.hwp -OutputDirectory converted
python scripts/convert_hwp.py input.hwp -o converted.hwpx
python scripts/fill_hwpx.py analyze form.hwpx
python scripts/fill_hwpx.py fill form.hwpx filled.hwpx --values values.json
python scripts/fill_hwpx.py check filled.hwpx --strict
python scripts/research_plan.py --school "○○초등학교" --title "○○ 연구과제" -o 연구계획서.hwpx
- HWP Conversion Principles (Important): In a Windows Hancom environment, always prioritize Hancom COM (
convert_hwp_hancom.ps1or Pythonwin32com.clientbasedSaveAs(..., "HWPX")). The Python built-in converter (convert_hwp.py) may generate non-standard HWPX that cannot be opened in Hancom Office when converting HWP documents containing complex tables/text boxes. - Preventing text overlap (
linesegarraymandatory removal): HWPX generated by Hancom contains<hp:linesegarray>, a cache of previous line-break coordinates. If this is not removed when replacing/adding text, a serious bug occurs where characters overlap on a single line. Always remove all instances after editing. - Replacing entire paragraphs: When replacing paragraph text, changing only part of the
run/tcauses duplication by merging with residual text, so empty the existingrun과linesegarrayand create a new singlerun/t.
If created/modified outside of one-shot, perform the following checks and page review before delivery.
python scripts/fix_namespaces.py output.hwpx
python scripts/finalize_hwpx.py output.hwpx --strip-linesegarray --layout
python scripts/validate.py output.hwpx --layout
python scripts/fill_hwpx.py check output.hwpx --strict
python scripts/finalize_hwpx.py output.hwpx --hancom
Reference by task
| Request | Path |
|---|---|
| Official document notation | gonmunseo-2025-writing-rules.md |
| Summary report | yoyak-bogo-style.md |
| Plan/review report | geomto-bogo-style.md |
| General-purpose report | report-style.md |
| HTML activity sheet | html2hwpx.py, html-to-hwpx.md |
| Complex forms/tables/footnotes/equations/official seals/original editing | advanced-workflows.mdthe corresponding workflow of |
| Reference reproduction | doc_spec.py, advanced reference workflow R |
| Reading/text extraction | text_extract.py, advanced reference workflow E |
doc_spec.py renderis HWPX assembly and not a page renderer. Do not limit the number of times needed to read additional reference materials. For general new documents, this main path takes priority over past advanced examples.
Delivering results
Concisely report the HWPX link with absolute path, the format applied, the checks actually performed, and items not performed. published: falseThe draft is not delivered as a final version. PARTIAL means the document was saved but saving reports, etc. failed. Do not conceal failures, drafts, or incomplete visual review.