O que esta skill faz
Trata um deck como uma construção, não como um documento:
| Artefato | Função |
|---|---|
template.pptx | o toolkit — seus slides são o catálogo de arquétipos. Sempre obrigatório. |
deck.mdx | a fonte — o único arquivo que alguém edita |
assets/*.svg | arte gerada, também fonte — apenas conteúdo, sem design |
deck.pptx | o artefato de construção — regenerado por completo a cada vez |
deck.pdf + prévias de página | o que uma pessoa realmente vê — o único lugar onde o layout é |
Cada slide de saída é um clone de um slide do modelo com seu conteúdo trocado, de modo que o design do modelo sobrevive byte por byte. Nada é criado do zero.
Mecanismo: scripts/deck.py (invoque com um caminho absoluto).
Recolorir (qualquer pptx; para um deck construído, recolorir template.pptx e reconstruir): scripts/ppt_keycolor_changer.py, procedimento e predefinições em references/recolor.md — descubra, mapeie por luminosidade, confirme, substitua, verifique.
Mandamentos Permanentes
- Nunca construir sem um modelo de referência. Não há design de deck embutido nem alternativa. Se o usuário não forneceu um
.pptx, pare e peça um — não monte slides de outra forma, não ofereça um deck genérico, não fabrique um template. O mecanismo também recusa, mas a solicitação é sua, antes de qualquer trabalho. - O arquivo fonte é
deck.mdx, nuncadeck.md. Ele é compilado, não lido. O mecanismo rejeita qualquer outra extensão. - Catalogar antes de escrever. Nunca escreva
deck.mdxbaseado em um palpite sobre o modelo. Executecataloge escreva usando os IDs de slot que ele imprimir. - Nunca edite manualmente o pptx de saída. Ele é regenerado na próxima construção. Correções vão para
deck.mdx. - Execute
checkantes debuild, e mostre os avisos ao usuário. Avisos de estouro são o que separa texto apertado de um slide que ninguém consegue ler. - Visibilidade decide, não organização.
| transparenté correto quando o conteúdo da imagem permanece legível contra o slide;checkdiz quando não estaria, e um painel atrás da imagem é a melhor resposta nesse caso. Não opte por transparência porque parece mais limpo. - Nunca corte conteúdo sem avisar.
checkrelata a porcentagem; repita ao usuário e ofereça| fit. Uma imagem perdendo metade de si é o mesmo defeito que uma linha de tabela caindo do slide. - Nunca escreva manualmente a arte de um slot de imagem como binário. Escreva o SVG para que o deck permaneça reproduzível a partir de texto. Um PNG que alguém colou não pode ser regenerado, recolorido ou revisado em um diff.
- Um deck é lido por pessoas, portanto olhe para ele. Quando um renderizador estiver disponível, termine com
render, não combuild— a auditoria de layout e as prévias de página são o único lugar onde colisões de texto aparecem. Se nenhum renderizador estiver disponível, diga isso claramente no relatório, em vez de sugerir que o layout foi verificado. - Nunca invente um arquétipo. Se nenhum slide do modelo se adequa ao conteúdo, diga e pergunte se é melhor reformular o conteúdo ou estender o modelo — não faça aproximações.
- Relate os avisos que você escolheu ignorar. Um aviso de estouro que você decidiu que estava ok ainda pertence ao relatório final — o usuário é quem verá o slide.
- Gráficos são somente leitura. Diga isso em voz alta quando o arquétipo escolhido tiver um; os números do modelo são mantidos a menos que o usuário edite o gráfico no PowerPoint.
Processo
Etapa 0 · Obter o modelo de referência
Peça o .pptx antes de qualquer outra coisa se você não tiver um:
"레퍼런스 템플릿 pptx를 주세요. deck-builder는 템플릿 슬라이드를 복제하는 방식이라, 템플릿 없이는 만들 수 있는 슬라이드가 없습니다."
Não prossiga baseado em uma descrição de um modelo, um deck de aparência semelhante ou uma promessa de fornecê-lo depois.
Etapa 1 · Catalogar o modelo
python3 /abs/path/scripts/deck.py catalog \
--template "template.pptx" --output "deck.catalog.md"
Imprime cada arquétipo como @s1…@sN com seus slots, o que o modelo mostra atualmente e uma estimativa de capacidade. Leia antes de qualquer outra coisa.
Etapa 2 · Mapear conteúdo para arquétipos
Pergunte ao usuário pelo conteúdo se você não o tiver. Então, antes de escrever qualquer md, mostre um plano de uma linha por slide:
1. @s1 표지 — 제목 + 부제
2. @s3 요약 — 불릿 3개 + 한 줄 결론
3. @s7 숫자 — 표 4행
Obtenha uma aprovação no plano. A escolha errada de arquétipo é o erro caro, não a redação errada.
Etapa 3 · Escrever deck.mdx
---
template: template.pptx
template_hash: 5f84440a3521 # do catálogo — prende o deck à estrutura do modelo
output: deck.pptx
---
## @s3
title: 분기 요약
text1:
- 응답 p99 **2.1s → 340ms**
- 배포 실패율 12% → 0.4%
table1:
| 지표 | 이전 | 이후 |
| p99 | 2.1s | 340ms |
pic1: assets/arch.svg
notes: 숫자의 출처를 먼저 말할 것
text5: !drop
Imagens aceitam um modo de ajuste — | fit mantém a imagem inteira, o padrão fill a corta — e | transparent remove o fundo de um PNG. Slots que você omitir mantêm o conteúdo do modelo.
Sintaxe completa — formas de slot, !drop, notes:, ênfase inline, níveis de tópico e o que template_hash protege — está em references/mdx-syntax.md. Leia antes de escrever o primeiro slide.
Etapa 3b · Gerar a arte que o deck precisa
Escreva a arte de um slot de imagem como um .svg, nas cores do modelo e no tamanho exato em pt do quadro — ambos impressos por catalog. Torna-se fonte como o resto do deck e é rasterizado para PNG no momento da construção.
Regras, justificativa e um exemplo prático: references/generated-art.md.
Etapa 4 · Verificar
python3 /abs/path/scripts/deck.py check --deck deck.mdx
Erros devem ser corrigidos. Avisos são decisões — apresente cada um, incluindo aqueles que você decidir ignorar.
| O que mede | Contra |
|---|---|
| Uma tabela ou texto saindo do slide | a borda do slide — um erro, nomeando as linhas perdidas |
| Uma linha muito larga para um slot que o modelo mantém em uma linha | o próprio quadro do slot, em em, para que o Hangul não seja contado como Latim |
| Um slot comportando muito menos do que o modelo coloca lá | o volume do próprio modelo — o quadro foi desenhado para aquela quantidade e o slide abre um buraco |
| Texto passando para baixo do que o design coloca | a contagem de linhas do próprio modelo e o que está abaixo |
| Perda de corte, dpi efetivo, desvios de paleta, bordas de caixa coladas | o quadro, a tela e a paleta do modelo |
| Texto sobre uma imagem | os pixels realmente atrás dela: 3:1 para texto grande, 4.5:1 para corpo |
Uma imagem desenhada depois das palavras que cobre é um erro — elas acabam atrás da imagem.
Cada estimativa aqui é calibrada contra o conteúdo do próprio modelo, em vez de um valor absoluto, porque a maioria dos quadros é desenhada para conter texto que já quebra. Margens de cerca de uma linha estão além do que uma estimativa estática pode resolver: apenas a Etapa 6 resolve essas.
Etapa 5 · Construir
python3 /abs/path/scripts/deck.py build --deck deck.mdx [--output out.pptx] [--strict]
O mesmo deck.mdx sempre produz um pptx byte a byte idêntico.
Etapa 6 · Renderizar e olhar
python3 /abs/path/scripts/deck.py render --deck deck.mdx
Constrói, converte através do LibreOffice, escreve prévias PNG de cada página e audita a geometria renderizada — overlap (dois quadros de texto colidem), bunched (linhas dentro de um quadro estão mais próximas do que a norma daquele quadro, então o texto excedeu sua caixa), off-slide (o renderizador cortou). Limpo significa limpo: a auditoria compara entre quadros e mede o pitch contra a mediana de cada quadro, de modo que fontes CJK cuja caixa em excede 100% da linha não geram alarme falso.
render primeiro diz quais das faces tipográficas do modelo o renderizador não possui. Uma fonte substituída requebra cada linha, portanto, até que essas sejam instaladas, as quebras de linha da prévia são do substituto, não do deck — a correção é instalar a fonte, não encurtar as palavras. O pptx em si sempre nomeia as faces corretas.
Leia as prévias para layout, não para espaçamento. O LibreOffice preenche a junção entre CJK e Latim por padrão, então 평균 42분 renderiza como 평균 42 분 na prévia, enquanto o pptx mantém a string original. Verifique <a:t> no arquivo construído antes de tratar espaçamento como defeito.
O renderizador é soffice no PATH ou DECK_RENDER_DOCKER=<image>. Sem nenhum dos dois, render recusa em vez de fingir que o layout foi verificado — diga isso e recorra a build.
Modelo de Saída
Relatório após uma construção:
빌드 완료 — <출력 경로>
슬라이드 <N>개 · 템플릿 <이름> · 이미지 <M>개 삽입
렌더 검사 — 겹침 0건 (또는: 3페이지 제목이 본문과 겹칩니다)
아키타입 사용
@s1 ×1 표지
@s3 ×4 본문
확인 필요
· 3번 슬라이드 title 58자 (프레임 ~39자/줄) — 두 줄로 넘어갑니다
· 5번 슬라이드 chart1 — 차트 수치는 템플릿 값 그대로입니다
다음 수정은 deck.mdx만 고치고 다시 build 하세요. 출력 pptx는 손대면 날아갑니다.
O que Claude Faz / O que Você Faz
| Claude | Você |
|---|---|
| Pergunta pelo pptx de referência, recusa-se a prosseguir sem ele | Fornece o modelo — obrigatório — e o conteúdo bruto |
Executa catalog, lê o mapa de slots | Revisa a lista de arquétipos |
| Propõe o plano de arquétipo por slide | Aprova ou reorganiza o plano |
Escreve e revisa deck.mdx | Edita deck.mdx diretamente sempre que preferir |
Executa check, relata todos os avisos | Decide se um aviso de estouro é relevante |
Executa render, olha as prévias, relata colisões | Abre o pptx, edita gráficos se necessário |
Limitações
As seis que alteram o que você pode prometer:
| Limitação | Consequência |
|---|---|
| Sem novos layouts | Cada slide é um clone. Conteúdo sem arquétipo precisa que o modelo seja estendido no PowerPoint — diga isso em vez de aproximar. |
| Um modelo é obrigatório | Sem design embutido, sem alternativa. |
| Gráficos não são graváveis | build deixa os números do modelo. Use um SVG em um slot de imagem. |
| Quadros nunca se movem | Escreva curto e a lacuna permanece; check relata, apenas o modelo pode fechá-la. |
| A verdade do layout precisa de um renderizador | check estima e não pode resolver margens abaixo de uma linha. Apenas render vê o que colide. |
| Legibilidade é apenas PNG | Texto sobre um fundo JPEG ou SVG não é pontuado; cores de texto herdadas são deixadas intactas. |
Tabela completa e qual etapa detecta cada uma: references/limits.md.
Skills Relacionadas
write:plans(propósito do documento) — desenvolva o conteúdo antes de mapeá-lo para slidesthink:untangle-thoughts— transforme notas dispersas na estrutura slide a slide que a Etapa 2 precisa