brand-docx

Files (11)

• SKILL.md
• intermediate-document.example.json · examples/
• block-catalog.md · reference/
• comprehension.md · reference/
• extraction.md · reference/
• generation.md · reference/
• idoc.schema.json · reference/
• profile-schema.md · reference/
• qa.md · reference/
• visual-audit.md · reference/
• cli.py · scripts/

SKILL.md (first lines)

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

Use this skill when the user wants a reusable Word brand kit or wants to create
a new on-brand `.docx` from a company template and variable content.

This is an AI-agent skill for Codex and Claude Code. The user should not need to
write JSON or run shell commands. The agent converts the user's content into an
IntermediateDocument, invokes the internal engine, verifies the output, and
returns the generated `.docx`.

## 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 `.docx` 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** | content (an IntermediateDocument) + a profile | a new on-brand `.docx` |
| **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.
When a current comprehension is present, `generate` additionally reconciles the
template's preserved cover/index structures with the new content. 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.docx` byte-for-byte.
- Generate opens the saved shell and resolves every semantic block through `profile.json`.
- Do not put style names, colors, fonts, or brand identifiers in an IntermediateDocument.
- If the user did not provide a template or enough content, 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 `.docx` 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 requested content into `IntermediateDocument` JSON.
6. **Generate** the `.docx` 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 documents (see below).

Before generation, inspect `profile.json.artifact_catalog` when the user asks
to mimic a specific template piece. It records OOXML parts, media parts,
paragraph/table styles, style details, sections/margins, paragraph samples,
and table counts.

## Authoring the IntermediateDocument

The IDoc is where "correct document" becomes "great document". Author it
role-first, against the profile, never style-first:

1. **Read `brand-kit/<name>/PROFILE.md` before writing a block.** It lists the
   role table (with scope, placement, required slots), the brand palette
   tokens, and the template's structural order. Choose every block by MEANING
   from that table; the engine resolves it to the template's own artifacts.
2. **Respect the skeleton.** Cover fields first (`cover.title`,
   `cover.subtitle`, extra cover `fields`), a `toc` block only where the
   template keeps one, then the freeform body.
3. **Shape the body for the reader.** One `heading` level 1 per major section
   and a real 1-2-3 hierarchy below it (the TOC regenerates from exactly these
   headings); paragraphs of 2-5 sentences; `list` blocks for enumerations
   (bullet for unordered, number for sequences); every `table` and `image`
   with a `caption` block so derived indexes regenerate from real content;
   `callout` sparingly, for genuinely load-bearing notes; `quote` only for
   actual quotations.
4. **Color discipline.** The named style already carries the brand: the
   default is NO run color. When emphasis is truly needed, reference a palette
   role (`primary`, `text`, ...) or a theme slot (`accent1`) from PROFILE.md,
   never a hex.
5. **Reuse before re-deriving.** When a comprehension is present, prefer its
   `component` / `section` fragments (`comprehension.fragments` in
   `profile.json`) with `{{slot}}` values over hand-building a recurring
   layout.
6. **Never name a style, font, size, or hex.** If a block 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.

From Willian8021743/windows-ai-toolkit, MIT.

More from Willian8021743/windows-ai-toolkit