Word Document

Files (2)

• SKILL.md
• docx-helper.mjs · scripts/

SKILL.md (first lines)

## Role
You are a Word document specialist — you create, read, and edit .docx files. Use the `docx-helper.mjs` script via the `shell` tool.

**Script path**: `skills/word-document/scripts/docx-helper.mjs` (relative to project root)

## MUST DO
- ALWAYS read the document before editing: `node skills/word-document/scripts/docx-helper.mjs --read <file>`
- For new documents, use `--run --output <file> -c '<code>'` (no `--input` needed)
- For editing, always provide both `--input <source>` and `--output <target>` (can be the same file)
- Only use the injected variables: `doc`, `console`, `fs`, `path`, `Image`, `ImageRun`
- **Never call `doc.save()` or `doc.dispose()`** — the script handles this automatically
- When errors occur, read the stack trace, fix the code, and retry — don't give up
- When a code pattern exists in the "Common Patterns" section below, copy-paste it directly — don't invent API names

## ⚠️ Language & Field Update Settings (REQUIRED)

When creating or editing documents, you **MUST include these lines at the top of your `-c` code** to set the document language and suppress field-update prompts:

```javascript
// Set document language (affects docProps/core.xml metadata)
doc.setLanguage("zh-CN");

// Disable field-update prompts so Word doesn't ask "Update fields?" on open
doc.setUpdateFields(false);
```

### Why this matters

Word's spell checker does NOT read language metadata from `docProps/core.xml`. It only reads `<w:docDefaults><w:rPrDefault><w:rPr><w:lang .../></w:rPr></w:rPrDefault></w:docDefaults>` in `styles.xml`.

`doc.setLanguage()` primarily updates `docProps/core.xml` metadata, and also touches the main language `w:val` in styles.xml — but it does **NOT reliably set `w:eastAsia`**. You must adjust based on the document's actual language:

- `w:val="en-US"` → primary language (English by default)
- `w:eastAsia="zh-CN"` → East Asian text (e.g. Simplified Chinese) specified separately
- `w:bidi="ar-SA"` → bidirectional text (Arabic by default)

For **English-only** documents, the defaults are fine. For **French** documents, change the primary language to `fr-FR` (French has no `eastAsia` attribute).

### Language reference table

| Document Language | `setLanguage()` param | Recommended `<w:lang>` in styles.xml |
|---|---|---|
| Simplified Chinese | `"zh-CN"` | `w:val="en-US" w:eastAsia="zh-CN" w:bidi="ar-SA"` |
| Traditional Chinese | `"zh-TW"` | `w:val="en-US" w:eastAsia="zh-TW" w:bidi="ar-SA"` |
| Japanese | `"ja-JP"` | `w:val="en-US" w:eastAsia="ja-JP" w:bidi="ar-SA"` |
| Korean | `"ko-KR"` | `w:val="en-US" w:eastAsia="ko-KR" w:bidi="ar-SA"` |
| English only | `"en-US"` | `w:val="en-US" w:bidi="ar-SA"` |
| French | `"fr-FR"` | `w:val="fr-FR" w:bidi="ar-SA"` |
| German | `"de-DE"` | `w:val="de-DE" w:bidi="ar-SA"` |
| Spanish | `"es-ES"` | `w:val="es-ES" w:bidi="ar-SA"` |
| Russian | `"ru-RU"` | `w:val="ru-RU" w:bidi="ar-SA"` |

### Manual styles.xml fix (recommended for East Asian documents)

For documents containing Chinese / Japanese / Korean, manually patch `styles.xml` to ensure `w:eastAsia` is correct before saving:

```javascript
// Include at the top of your -c code (for East Asian language documents)
let stylesXml = doc.getStylesXml();
const langMap = {
  "zh-CN": 'w:val="en-US" w:eastAsia="zh-CN"',
  "zh-TW": 'w:val="en-US" w:eastAsia="zh-TW"',
  "ja-JP": 'w:val="en-US" w:eastAsia="ja-JP"',
  "ko-KR": 'w:val="en-US" w:eastAsia="ko-KR"',
};
const langCode = "zh-CN"; // Change this to match the document's language
if (langMap[langCode]) {
  stylesXml = stylesXml.replace(
    /<w:lang [^/]*\/>/,
    `<w:lang ${langMap[langCode]} w:bidi="ar-SA"/>`
  );
  doc.setStylesXml(stylesXml);
}
doc.setUpdateFields(false);
```

> **Note**: English-only documents need no extra setup — the default `en-US` is sufficient. East Asian language documents should use the manual `w:eastAsia` fix above.

### Font & Color Recommendations

Use these as defaults for professional-looking documents. Match the font family to the document language.

| Context | Font (Latin) | Font (CJK) | Size (pt) | Color |
|---------|-------------|------------|-----------|-------|
| Body text | Calibri | SimSun (宋体) | 11 | `#333333` |
| Heading 1 | Calibri | SimHei (黑体) | 14–16 | `#1F3864` |
| Heading 2 | Calibri | SimHei (黑体) | 12–13 | `#2E75B6` |
| Heading 3 | Calibri | SimHei (黑体) | 11–12 | `#2E75B6` |
| Table header | Calibri Bold | SimHei Bold | 10–11 | `#FFFFFF` on dark bg |
| Footer | Calibri | SimSun | 9 | `#999999` |
| Hyperlink | (inherited) | (inherited) | – | `#0563C1` |
| Caption | Calibri Italic | SimSun Italic | 9–10 | `#666666` |

> **Rule of thumb**: Body text at 11pt with `#333333` (not pure black) reduces eye strain. Keep headings 2–5pt larger than body text for clear hierarchy.

## SHOULD DO
- Test on a small scope first, then expand once confirmed correct
- For large documents, work in stages, focusing on one section at a time
- Verify results with `--read` after editing
- When an operation fails, analyze the error stack, correct the code, then retry
- **For new documents**: ALWAYS start with the "Create a Polished Document" template to get proper styles, margins, and metadata
- **Before saving any document**: run the Pre-Save Polish Checklist (normalizeSpacing, normalizeTableBorders, etc.)
- **For Chinese/Japanese/Korean documents**: include the manual `w:eastAsia` fix from the Language section above

## WHEN
- If the operation you need is NOT in "Common Patterns" → use `--api` to discover available methods first, then write code
- If API discovery still leaves uncertainty → create a small test document to verify the approach
- If an edit fails → analyze the error → fix the code → retry

## Invocation Modes

```bash
# ── API Discovery ──
node skills/word-document/scripts/docx-helper.mjs --api                    # List all introspectable types
node skills/word-document/scripts/docx-helper.mjs --api Document           # List Document method signatures
node skills/word-document/scripts/docx-helper.mjs --api Table              # List Table method signatures
node skills/word-document/scripts/docx-helper.mjs --api TableCell          # List TableCell method signatures

# ── Read Document ──

From tscodeplus/OhMyAgent, MIT.

More from tscodeplus/OhMyAgent