MÓDULO 3.3

📄 A skill de documentos (DocX/PPTX/Excel/PDF)

Os entregáveis que o cliente abre — Word, PowerPoint, Excel, PDF — nascem de Python, não de Markdown cru. Aqui você aprende as quatro bibliotecas e as embrulha numa skill: gerar-entregavel.

6
Tópicos
~45
Minutos
Intermediário
Nível
Código
Tipo
1

🎁 Por que gerar documentos programaticamente

O cliente não abre um .md. Ele abre um .docx, um .pptx, uma planilha .xlsx ou um .pdf. Gerar por código significa saída formatada, repetível e com a sua marca — é exatamente isso que faz o pacote parecer consultoria de elite, não um rascunho de chat.

Markdown entregável cru gerar-entregavel a skill de docs .docx .pptx .xlsx .pdf

A fundação é simples: um ambiente virtual com as quatro bibliotecas instaladas. O Claude Code roda isso por você uma vez — depois é só gerar.

// setup: venv + as 4 bibliotecas

python3 -m venv venv
source venv/bin/activate
pip install python-docx reportlab openpyxl python-pptx

✗ Markdown cru

  • ✗Cliente vê texto de chat, não um entregável
  • ✗Sem marca, sem tabela formatada, sem fórmula
  • ✗Não abre direto no Word/PowerPoint/Excel

✓ Documento gerado

  • ✓Formatado, com a sua identidade visual
  • ✓Repetível: mesmo código, novo cliente
  • ✓Abre direto — parece consultoria de elite

💡 Dica prática

Você não digita esse código à mão. Peça ao Claude Code "crie o venv e instale as 4 libs de documento" — ele roda, resolve conflito de Python do sistema e te deixa pronto pra gerar. Sua função é dirigir o formato de saída, não decorar a API.

Formatado

marca + estilo

Repetível

1 código, N clientes

4 formatos

docx/pptx/xlsx/pdf

Profissional

o que o cliente abre

2

📘 python-docx — relatórios Word

Esta é a biblioteca dos relatórios. Você cria um Document(), empilha headings (nível 0 = título, 1-9 = seções), parágrafos, tabelas e runs formatados (negrito, cor). No fim, doc.save(). É o que gera o Relatório final e o SOW da Fábrica.

// python-docx: título, seção, tabela e run formatado

from docx import Document
from docx.shared import Pt, RGBColor

doc = Document()
doc.add_heading('Relatório de Estratégia de IA', level=0)
doc.add_heading('Sumário Executivo', level=1)
doc.add_paragraph('Texto do relatório aqui.')

table = doc.add_table(rows=4, cols=3)
table.style = 'Table Grid'

p = doc.add_paragraph()
run = p.add_run('Destaque')
run.bold = True
run.font.color.rgb = RGBColor(0x00, 0x00, 0xFF)

doc.save('relatorio.docx')

Repare em três coisas: o level controla a hierarquia, table.style = 'Table Grid' dá as bordas, e o run é a unidade mínima onde você aplica negrito e cor. Esse mesmo esqueleto vira o Relatório final e o documento de proposta (SOW).

💡 Nota

Estilos prontos poupam trabalho: 'List Bullet' e 'List Number' para listas, 'Heading 1' / 'Heading 2' para seções. Você descreve a estrutura do relatório; o Claude Code escolhe os estilos.

Document()

cria o doc

Headings

level 0–9

Tabelas

Table Grid

Saída

Relatório + SOW

3

📙 python-pptx — apresentações (RGBColor, layouts)

A biblioteca das apresentações. Você cria uma Presentation(), adiciona slides escolhendo um layout (0 = Title, 6 = Blank, o mais flexível), e desenha textboxes com bullets e cores via RGBColor. É o que gera o deck executivo — o material que fecha a venda na Trilha 5.

// python-pptx: slide em branco com título centralizado

from pptx import Presentation
from pptx.util import Inches, Pt
from pptx.dml.color import RGBColor   # NÃO RgbColor
from pptx.enum.text import PP_ALIGN

prs = Presentation()
slide = prs.slides.add_slide(prs.slide_layouts[6])  # branco

box = slide.shapes.add_textbox(Inches(0.5), Inches(2), Inches(9), Inches(1.5))
p = box.text_frame.paragraphs[0]
p.text = "Estratégia de IA"
p.font.size = Pt(44)
p.font.bold = True
p.font.color.rgb = RGBColor(31, 78, 121)  # azul escuro
p.alignment = PP_ALIGN.CENTER

prs.save('deck.pptx')

O layout 6 (Blank) é o mais usado porque te dá controle total: você posiciona cada caixa em polegadas. O primeiro parágrafo já existe em paragraphs[0]; para os bullets seguintes use add_paragraph().

💡 A pegadinha que trava todo mundo

É RGBColor (RGB maiúsculo), não RgbColor. Errar essa capitalização gera um ImportError que parece misterioso. Cor é por inteiros RGB: RGBColor(31, 78, 121) = azul escuro profissional.

Presentation()

cria o deck

Layout 6

branco, flexível

RGBColor

não RgbColor

Saída

deck executivo

4

📊 openpyxl — Excel com convenção de cores

A biblioteca das planilhas — e aqui mora a calculadora de ROI. Três regras de ouro: indexação 1-based (A1 = linha 1, coluna 1), fórmulas em vez de valores fixos, e a convenção de cores financeira. Quem entrega Excel sem fórmula entrega um print, não um modelo.

// openpyxl: fórmula + cores de input/fórmula

from openpyxl import Workbook
from openpyxl.styles import Font, PatternFill

wb = Workbook(); ws = wb.active
ws.title = "ROI"

ws['A1'] = 'Premissa'           # 1-based: A1
ws['B5'] = '=SUM(B1:B4)'        # fórmula, nunca valor fixo

input_font   = Font(color='0000FF')  # azul = input do usuário
formula_font = Font(color='000000')  # preto = fórmula
ws['B1'].font = input_font
ws['B5'].font = formula_font

wb.save('roi.xlsx')

A convenção de cores abaixo é padrão de modelagem financeira — qualquer analista que abrir a planilha entende na hora o que é input, o que é cálculo e o que vem de fora. Aplique-a sempre na calculadora de ROI:

🎨 Convenção de cores (obrigatória)

  • Azul 0000FF — inputs do usuário (premissas ajustáveis)
  • Preto 000000 — fórmulas e cálculos
  • Verde 008000 — links entre abas (outras worksheets)
  • Vermelho FF0000 — referências a arquivos externos
  • Amarelo (fundo) FFFF00 — premissas-chave em destaque

💡 Dica prática

Nunca calcule no Python e cole o número. Coloque as premissas em células próprias (azul) e referencie por fórmula (preto). Assim o cliente muda uma premissa e a planilha inteira recalcula — é isso que separa um modelo de um relatório morto.

Workbook()

cria a planilha

1-based

A1 = (1,1)

Fórmulas

nunca valor fixo

Cores

calculadora de ROI

5

📕 reportlab — PDF (Platypus)

A biblioteca dos PDFs. O método recomendado é o Platypus: você monta uma story (lista de elementos — parágrafos, espaçadores, tabelas) e chama doc.build(story) no fim. O PDF só existe depois do build.

// reportlab: monta a story e constrói no fim

from reportlab.lib.pagesizes import letter
from reportlab.lib.styles import getSampleStyleSheet
from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer
from reportlab.lib.units import inch

doc = SimpleDocTemplate('saida.pdf', pagesize=letter)
styles = getSampleStyleSheet()
story = []
story.append(Paragraph('Estratégia de IA', styles['Heading1']))
story.append(Spacer(1, 0.5 * inch))
story.append(Paragraph('Corpo do documento.', styles['Normal']))
doc.build(story)   # constrói no fim

💡 Dica prática

O build vem no FIM. Tudo que você quer no PDF precisa estar na story antes de chamar doc.build(). Esqueceu de dar append em algo? Não aparece no arquivo.

Repare que o padrão é sempre o mesmo nas quatro libs — e dá pra desenhar o fluxo da skill gerar-entregavel como quatro passos lineares:

1

Markdown de entrada

A skill recebe o entregável em Markdown e o formato-alvo desejado.

2

Escolher o formato

docx / pptx / xlsx / pdf → seleciona a biblioteca certa.

3

Montar os elementos

Headings, tabelas, fórmulas, cores — segundo a convenção de cada formato.

4

Salvar o arquivo

.save() nas três; .build(story) no PDF. Vai pra pasta do cliente.

Platypus

story de elementos

append

empilha na story

build()

no fim, sempre

Saída

PDF do cliente

6

📦 Empacotar como skill gerar-entregavel

Você não quer lembrar de quatro APIs toda vez. Embrulhe as quatro bibliotecas numa única skill: "dado um Markdown, gere o .docx/.pptx/.xlsx/.pdf". A skill carrega o conhecimento; você só diz o formato. É o motor de saída da Fábrica.

// SKILL.md — gerar-entregavel

---
name: gerar-entregavel
description: Use para transformar um entregável em Markdown
  num arquivo final — .docx, .pptx, .xlsx ou .pdf — usando
  python-docx, python-pptx, openpyxl ou reportlab.
---

# Gerar Entregável

## Passos
1. Ler o Markdown e o formato-alvo.
2. Escolher a biblioteca (docx / pptx / xlsx / pdf).
3. Montar o documento (headings, tabelas, cores).
4. Salvar na pasta de saída do cliente.

A description bem escrita é o que faz o Claude Code acionar a skill na hora certa. Os passos são o roteiro que ele segue. Daqui pra frente, "transforme esse diagnóstico em PowerPoint" é um comando — não um projeto.

✓ Boa skill de docs

  • ✓Escolhe o formato certo pro entregável
  • ✓Usa fórmulas no Excel, com convenção de cores
  • ✓Importa RGBColor certo no pptx

✗ Erros comuns

  • ✗Entrega Markdown cru, sem gerar arquivo
  • ✗Valores fixos no Excel em vez de fórmulas
  • ✗Escreve RgbColor e quebra o import
1 skill

4 bibliotecas

description

aciona na hora

Passos

roteiro fixo

Reuso

motor de saída

✅ Resumo do módulo

✓
Documentos saem de Python — formatados e repetíveis, não Markdown cru.
✓
Cada lib cobre um formato — docx (Word), pptx (deck), xlsx (Excel), pdf (reportlab).
✓
Excel usa fórmulas + convenção de cores — azul input, preto fórmula, e o resto da paleta.
✓
Tudo embrulhado em gerar-entregavel — uma skill, qualquer formato de saída.

🎯 Missão 3.3 — Markdown vira pacote

Transforme um único Markdown em dois arquivos de cliente:

  1. Pegar 1 entregável em Markdown (ex.: um mini-diagnóstico da 3.2).
  2. Gerar 1 .docx com python-docx.
  3. Gerar 1 .pptx com python-pptx (cuidado: RGBColor).
  4. Embrulhar na skill gerar-entregavel.

Sucesso: 1 .docx + 1 .pptx gerados a partir do mesmo Markdown. O que você ganhou: o motor de saída da Fábrica — qualquer prompt vira arquivo de cliente.

Próximo módulo:

3.4 — Construa seu subagente (pesquisador & redator)

← Voltar para Trilha Próximo Módulo →