Agency Report Format Skill Kit

Vietnamese version: README-VN.md

This repository grew out of a practical problem: generating agency-standard reports every month while the data changes and, with it, the report structure itself. Mail merge is still useful when a document only needs simple placeholder replacement. But once a report contains tables with changing row counts, changing columns, complex merged cells, charts, and strict formatting rules, the problem is no longer just filling a Word template.

The harder question is: how do you help AI understand the structure of a long report, sometimes dozens of pages, without manually describing every row, table, merge rule, and formatting constraint? This repository describes one answer: let an AI agent read the right reference artifacts, analyze DOCX, PDF, and when possible XML structure, then turn that analysis into a canonical format specification, an execution plan, and a validated DOCX generation pipeline.

Project Overview

This is not just a technical demo. It documents an attempt to solve a real report-automation problem: reproducing complex agency-standard reports with AI while keeping the output structurally faithful to the approved form.

The real task is not just filling a Word template. It is reproducing a final artifact when the report contains:

• dynamic tables
• multi-row headers
• horizontal and vertical merges
• mandatory total rows and note rows
• charts or other data-driven visual sections
• typography, spacing, page flow, and Word/PDF constraints that affect acceptance

That is why mail merge or placeholder replacement is not enough. Those techniques can fill fixed fields, but they do not reliably reproduce table schema, merge maps, mandatory rows, or layout-sensitive DOCX and PDF behavior.

This repository makes that problem more understandable and repeatable by documenting the approach, the working pipeline, and the main friction points that must be handled.

Human Input Boundary

The human role is intentionally narrow. A user only prepares these reference artifacts:

1. the approved DOCX form
2. the PDF exported from that DOCX
3. if available, the unpacked DOCX or its XML parts

From that point on, this repository is about what the AI agent should do with those artifacts.

Agent Skill Flow

The skill expects the AI agent to operate in this order:

1. Read the approved DOCX to recover visible structure: section order, heading hierarchy, table inventory, total rows, note rows, and fixed wording.
2. Read the reference PDF to understand final display truth: page breaks, page flow, spacing drift, width drift, and visual parity.
3. Read unpacked DOCX XML to recover Word-specific structure: grid layout, w:gridSpan, w:vMerge, header signatures, and table boundaries.
4. Merge the extracted facts into a canonical format specification.
5. Build an execution plan and fix-layer map across data, template, post-process, XML, and validation layers.