claude-plugins/dev-tools/skills/docx/SKILL-light.md

name, description

name	description
docx	Criação, edição e análise de documentos Word (.docx). Versão light para heartbeats.

DOCX — Referência Rápida

Referência rápida

Tarefa	Abordagem
Ler conteúdo	pandoc ou descompactar XML
Criar novo	docx-js (npm install -g docx)
Editar existente	Descompactar → editar XML → recompactar
Converter .doc	python scripts/office/soffice.py --headless --convert-to docx doc.doc

Criar novos documentos (docx-js)

Setup básico

const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell, ImageRun,
        Header, Footer, AlignmentType, PageOrientation, LevelFormat, HeadingLevel,
        BorderStyle, WidthType, ShadingType, PageNumber, PageBreak } = require('docx');

const doc = new Document({ sections: [{ children: [/* conteúdo */] }] });
Packer.toBuffer(doc).then(buffer => fs.writeFileSync("doc.docx", buffer));

Tamanho de página (A4)

sections: [{
  properties: {
    page: {
      size: { width: 11906, height: 16838 },  // A4 em DXA
      margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 }
    }
  },
  children: [/* conteúdo */]
}]

Largura de conteúdo A4 com margens 1": 11906 - 2880 = 9026 DXA

Paisagem: Passar dimensões retrato + orientation: PageOrientation.LANDSCAPE (docx-js troca internamente).

Listas

numbering: { config: [
  { reference: "bullets", levels: [{ level: 0, format: LevelFormat.BULLET, text: "\u2022",
    alignment: AlignmentType.LEFT, style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] }
] }
// Usar: new Paragraph({ numbering: { reference: "bullets", level: 0 }, children: [...] })

Tabelas

// Largura tabela = soma columnWidths. Usar SEMPRE WidthType.DXA (nunca PERCENTAGE).
new Table({
  width: { size: 9026, type: WidthType.DXA },
  columnWidths: [4513, 4513],
  rows: [new TableRow({ children: [
    new TableCell({
      borders: { top: b, bottom: b, left: b, right: b },
      width: { size: 4513, type: WidthType.DXA },
      shading: { fill: "D5E8F0", type: ShadingType.CLEAR },  // CLEAR, nunca SOLID
      margins: { top: 80, bottom: 80, left: 120, right: 120 },
      children: [new Paragraph({ children: [new TextRun("Célula")] })]
    })
  ] })]
})

Imagens

new ImageRun({
  type: "png",  // Obrigatório
  data: fs.readFileSync("image.png"),
  transformation: { width: 200, height: 150 },
  altText: { title: "T", description: "D", name: "N" }  // Três obrigatórios
})

Cabeçalhos/rodapés

headers: { default: new Header({ children: [new Paragraph({ children: [new TextRun("Cabeçalho")] })] }) },
footers: { default: new Footer({ children: [new Paragraph({
  children: [new TextRun("Página "), new TextRun({ children: [PageNumber.CURRENT] })]
})] }) }

Regras críticas docx-js

• Nunca usar \n — usar Paragraphs separados
• Nunca usar bullets unicode — usar LevelFormat.BULLET
• PageBreak dentro de Paragraph: new Paragraph({ children: [new PageBreak()] })
• ImageRun requer type
• Tabelas: columnWidths E width na célula, ambos devem corresponder
• Usar ShadingType.CLEAR, nunca SOLID
• TOC requer HeadingLevel apenas, sem estilos custom
• Override estilos: IDs exactos "Heading1", "Heading2" + outlineLevel

Editar documentos existentes

Passo 1: Descompactar

python scripts/office/unpack.py document.docx unpacked/

Passo 2: Editar XML

Editar ficheiros em unpacked/word/. Usar ferramenta Edit directamente (não scripts Python).

Tracked changes:

<!-- Inserção -->
<w:ins w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z">
  <w:r><w:t>texto inserido</w:t></w:r>
</w:ins>

<!-- Eliminação -->
<w:del w:id="2" w:author="Claude" w:date="2025-01-01T00:00:00Z">
  <w:r><w:delText>texto eliminado</w:delText></w:r>
</w:del>

Comentários:

python scripts/comment.py unpacked/ 0 "Texto do comentário"
python scripts/comment.py unpacked/ 1 "Resposta" --parent 0

Smart quotes: ‘ ’ “ ”

Passo 3: Recompactar

python scripts/office/pack.py unpacked/ output.docx --original document.docx

Validação: python scripts/office/validate.py doc.docx

Convenções Descomplicar

• Data: DD-MM-YYYY
• Monetário: 1.234,56 EUR
• Fonte: Arial 12pt
• Página: A4 (11906 x 16838 DXA)
• Autor tracked changes: "Claude"
• Idioma: PT-PT

---

Versão: 1.0.0-light | Base: 1.0.0