Brand XLSX

brand-xlsx

Use this skill when the user wants reusable branded Excel/workbook generation from a company .xlsx template and variable user-provided data.

This is an AI-agent skill for Codex and Claude Code. The user should describe the workbook/model they want filled; the agent maps that request to named cells and named regions, invokes the internal Python engine, verifies the output, and returns the generated .xlsx.

The seven verbs: three deterministic + four model-assisted

Every brand skill (brand-docx, brand-pptx, brand-xlsx) implements the same contract. The deterministic core is extract / verify / generate; on top of it sit the optional learning verbs comprehend / learn / propose-overrides / refine, each fail-closed (the engine validates every proposal and authors every value).

comprehend is optional: generate works on the deterministic profile alone. See reference/comprehension.md for the full step.

Hard Rules

• Treat python scripts/cli.py ... as an internal engine command, not the user-facing workflow.
• scripts/cli.py is a LAUNCHER that locates the engine root by itself: it works from this skill folder AND from the repo/plugin root (set BRAND_DOCS_ROOT to override). Never guess deeper paths like scripts/brandkit/....
• Run the dependency preflight before starting extract / comprehend / verify / generate, and report missing or unusable dependencies before proceeding.
• Extract opens the source template read-only and saves brand-kit/<name>/template/shell.xlsx byte-for-byte.
• Generate opens the saved shell and resolves every named cell/region through profile.json.
• Do not put style names, colors, fonts, or brand identifiers in a GridDocument.
• If the user did not provide a template or enough data, ask for the missing input.
• Return the generated file path plus a QA summary.
• Consult profile.json.artifact_catalog before generation when the user asks to mimic a specific piece of the template.

Preflight (always first)

Before doing any work, run:

python scripts/cli.py doctor

Use its output to decide the run mode:

• If a required Python dependency is missing, install/repair it before extraction or generation; the core engine is not ready.
• If only visual renderers are missing or unusable (soffice plus pdftoppm or optional PyMuPDF/fitz), the core L0 workflow can still run, but a full visual audit cannot be claimed. Tell the user what is missing, include the install/repair hint printed by doctor, and either proceed with degraded QA or install the renderer first.
• If optional OCR (tesseract) is missing, the visual audit can still run, but rendered residual-text proof is incomplete. Report that limitation when judging stale placeholders or field caches.
• For --qa deep or --qa strict, prefer repairing/installing renderers before generation. If the environment cannot run them, deep generates a degraded manifest and strict fails with a visual proof blocker.

Agent Workflow

1. Run the dependency preflight above and report any degraded capability.
2. Determine the brand name and locate the user-provided .xlsx template.
3. If no matching brand-kit/<name> exists, extract one.
4. Comprehend the template (optional, model-driven; see below). Skip when a current comprehension is already cached or no model is available.
5. Convert the user's tabular/model data into GridDocument JSON.
6. Generate the .xlsx with the internal engine.
7. Run QA and report any warnings honestly.
8. Feedback (only after returning the file): invite a refinement of the understanding for future workbooks (see below).

Before generation, inspect profile.json.artifact_catalog when the user asks to mimic a specific workbook piece. It records OOXML parts, named ranges, formulas, sheet dimensions, table names, merged cells, row/column sizing, cell styles, and number formats.

Authoring the GridDocument

The Grid is where "correct workbook" becomes "great workbook". Author it region-first, against the profile, never cell-address-first:

1. Read brand-kit/<name>/PROFILE.md before writing a fill. It lists the named-region roles, the brand cell styles, and the palette tokens. Address content to NAMED regions from that table; the engine fills the template's real ranges.
2. Respect region bounds. Size data to the region; when real data overflows, split it or ask the user to grow the template range instead of spilling into unnamed cells.
3. Formulas are content, not output. Never paste a computed value where the template keeps a formula: the engine preserves formulas, and QA fails the build if one is lost.
4. Numbers carry the brand too. Use the captured number.<family> roles (currency, percent, date, ...) for masks; never invent a format string.
5. Color discipline. Brand cell styles already carry the look: the default is NO direct color. For true emphasis, reference a palette role or a theme slot, never a hex.
6. Never name a style, font, or hex. If a fill needs something the role table cannot express, say so in the QA summary instead of inventing formatting: the resolver is the only author of values.

Feedback (end of generation)

Ask for feedback only after you have returned the generated .xlsx and its QA summary - never before or during generation. Invite the user to reply with text or a screenshot of the workbook, and name the roles, palette colors, and sections you actually used so the answer is concrete. A screenshot is your own multimodal read; the engine only ever ingests the structured JSON delta you distil from it.

Turn the answer into a small refinement delta of verbatim ids and merge it with the refine verb (see reference/comprehension.md):

python scripts/cli.py refine --name <brand> --input refinement.json --accept

A refinement improves FUTURE generations of this brand only - it mutates the saved profile, never the .xlsx you just produced. To apply it, generate again.

When the SAME QA finding recurs across runs, you can also propose a shell-bound correction with propose-overrides: the comprehend-input bundle surfaces the recurring generation_history, and you NAME a shell-backed re-point (a stub role to an existing healthy role, a number_format mask the shell uses, or a captured demo value) that the engine binds fail-closed (see reference/comprehension.md). It is advisory until --accept, improves FUTURE generations only, and every live correction surfaces as an INFO override_applied finding in QA.