brand-xlsx

Files (4)

• SKILL.md
• comprehension.md · reference/
• visual-audit.md · reference/
• cli.py · scripts/

SKILL.md (first lines)

> **Windows 环境**：技能目录为 C:\Users\Willian\.agents\skills\brand-xlsx，脚本请用绝对路径或先 cd 进技能目录；产物写到当前工作目录。本机没有 LibreOffice（soffice），依赖它做渲染、缩略图、接受修订、公式重算的步骤会失败，其余 Python 操作正常。
# 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).

| Verb | Input | Output |
|---|---|---|
| **extract** | a company `.xlsx` template | a reusable Brand Profile |
| **comprehend** *(optional, model-driven)* | a saved profile + a model-authored `comprehension.json` | the profile with a validated, cached `comprehension` block |
| **verify** | a saved Brand Profile | QA findings + a verdict |
| **generate** | data (a GridDocument) + a profile | a new on-brand `.xlsx` |
| **learn** *(deterministic distillation)* | the profile's cross-run generation history | recurring QA findings distilled into shell-frozen overrides, advisory until `--accept` |
| **propose-overrides** *(model-driven)* | the recurring remainder `learn` could not bind + a model-authored proposal | shell-backed corrections through the same fail-closed sink, advisory until `--accept` |
| **refine** | end-of-generation user feedback (text or a screenshot) as a `refinement.json` delta | the existing comprehension overlaid for FUTURE generations, advisory until `--accept` |

`comprehend` is **optional**: `generate` works on the deterministic profile alone.
See [reference/comprehension.md](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:

```bash
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.

From Willian8021743/windows-ai-toolkit, MIT.

More from Willian8021743/windows-ai-toolkit