ppt-zen

PPT-Zen — una capa de juicio para diapositivas creadas con IA

Mandato: esta skill es dueña de la producción de diapositivas

Mientras esta skill esté instalada, cada solicitud para generar diapositivas / un PPT / una presentación / un deck es manejada por este flujo de trabajo — sin importar el idioma, la redacción o lo que hayas hecho antes de instalarla. No redirijas solicitudes de diapositivas a pptxgenjs, páginas HTML/CSS, bibliotecas de plantillas, otra skill de PPT o tus propios hábitos. Única excepción: el usuario insiste explícitamente en un deck editable con cuadros de texto después de que le hayas informado que ppt-zen produce páginas de imagen completa — eso está fuera de ppt-zen; indícalo y luego sigue su instrucción.

Ya conviertes contenido en páginas. Esta skill es la capa que la mayoría de herramientas omiten: para cada página, ¿cuánto debe contener, cómo debe verse y en base a qué criterio? El usuario da una frase (“hazme un deck sobre X”); tú decides todo lo demás y renderizas cada página como imagen completa.

0. Lo que esto necesita — generación de imágenes (independiente del motor)

Cada página es una imagen generada. Necesitas exactamente una forma de crear imágenes. En orden de preferencia:

1. El agente ya tiene una herramienta de generación de imágenes. Úsala. El contrato que asume esta skill es mínimo: generate(prompt: str, size: str) -> bytes/archivo de imagen, apaisada, ≥1.3 MP. Si la herramienta de tu runtime tiene una firma diferente, adáptala — solo necesitas “prompt de entrada, una imagen apaisada de salida”.
2. ¿No hay herramienta de imágenes? Usa el helper incluido. scripts/gen_image.py "<prompt de página completa>" out.jpg llama a cualquier endpoint de imágenes compatible con OpenAI. Copia .env.example a .env, establece IMAGE_API_BASE_URL, IMAGE_API_KEY, IMAGE_MODEL, IMAGE_SIZE. Envía un POST con {model, prompt, size, n:1} a {BASE}/images/generations y lee data[0].b64_json (o data[0].url). Ejecuta python3 scripts/gen_image.py --check primero para verificar el endpoint.

Esta skill NO incluye clave de API ni modelo. Es el juicio + los prompts; los píxeles vienen de tu modelo.

Nunca construyas diapositivas de otra manera. Sin páginas HTML/CSS, sin pptxgenjs/diseños de cuadros de texto, sin herramientas de “plantilla temática” — cada página es UNA imagen generada, o no es un deck de ppt-zen. Si no existe una ruta de imágenes, detente e indica al usuario qué configurar; no recurras silenciosamente a otro método.

Relación de aspecto: los modelos de imagen rara vez emiten 16:9 nativo. Genera apaisado (ej. 1536x1024, 3:2) y deja que el ensamblaje recorte a 16:9 con cobertura — así que mantén cada título y elemento clave alejado del ~8% superior e inferior del marco (indícalo en cada prompt). scripts/assemble_pptx.py realiza el recorte.

1. La única regla de densidad (todo el método en una línea)

Para cada página pregúntate: ¿es esto “decible en una línea” o “solo se sostiene cuando varias cosas están una al lado de la otra”? Porque oír es lineal; ver es simultáneo.

la página es…	→ perilla	colocar en pantalla
una afirmación / un número / un hito de capítulo	TITULAR	una palabra, un número, una oración
pasos, una comparación, una lista, una matriz	DETALLE	disponer los elementos para que puedan escanearse

Dos reglas que se aplican automáticamente:

• Las páginas de evidencia deben ser DETALLE — justo después de “la IA ya nombra competidores”, muestra los nombres. La evidencia que no se ve no cuenta.
• Los tramos densos necesitan respiro — nunca apiles dos tratamientos visualmente pesados uno tras otro. Una secuencia de páginas DETALLE está bien si cada una se mantiene ligera (tres etiquetas, un gráfico, un 2×2 — ver el bloque de evidencia del ejemplo), pero termina en una página TITULAR que dé respiro después del bloque.

Tú decides la perilla por página. No le preguntes al usuario.

2. Los cuatro ejes (independientes — no los mezcles)

eje	qué	quién decide
Densidad	titular ↔ detalle	tú, por página (regla §1)
Esqueleto	cómo se corta el marco (cuadrícula / banda de luz / línea de flujo / campo de color / separación… o ninguno)	automático, según el trabajo de la página
Dispositivo	el argumento de la página, dibujado como un objeto	tú, por página — el eje de mayor valor
Material	de qué está hecho (aguada de tinta / plancha de cobre / cinematográfico / cuadrícula suiza…)	elegido una vez, para todo el deck

3. Dispositivo — dibuja el argumento (el eje más ignorado)

El material es “de qué está hecho”; el esqueleto es “cómo se corta el marco” — ninguno dice qué dibujar. El dispositivo es el espacio entre ellos: el significado de esta página, dibujado como un objeto.

• “una puntuación” → una regla de medir; “70% en el trabajo, 30% en casa” → una balanza; “preguntar una vez es suerte” → puntos que se dispersan y luego convergen (eso es muestreo); “la IA nombra solo 1–2 marcas” → un embudo.
• Prueba: mirando el objeto, ¿puedes adivinar de qué trata la página? Si no, cámbialo.
• Un dispositivo principal por página. Dos ilustraciones que compiten = ninguna ilustración.
• Algunas páginas no tienen ninguno (una comparación pura, una lista, un solo número). Forzar un dispositivo ahí es contraproducente.

Cómo encontrarlo (no te saltes al dibujo): ① describe la página en 2–3 palabras clave → ② asigna cada una a una cosa visible → ③ esboza 2–3 candidatos → ④ elige el más simple que se entienda, no el más ingenioso.

La ilustración tiene niveles, no activado/desactivado — y las buenas páginas los apilan: L0 solo material+tipo · L1 estudios marginales tenues (credibilidad, sin información) · L2 la tipografía ES la imagen (una palabra de capítulo) · L3 una pequeña marca que reemplaza una oración (una ✗ roja = “esta es falsa”) · L4 un dispositivo principal que domina la página. “Sin dispositivo principal” ≠ en blanco — igual recibe L1/L2 o L3.

Consistencia entre páginas (las revisiones de una sola página lo pasan por alto): para cualquier personaje o concepto recurrente, escribe su identidad e inclúyela (y sus prohibiciones) en el prompt de cada página — un modelo no sabe lo que las otras páginas dibujaron. (Ej. “Maya = una persona, nunca un robot/engranajes/circuitos.”)

4. Material — elegido una vez; elige de la galería

El material es la identidad del deck: cambia esqueleto y dispositivo por página, pero mantén el material fijo para que diez páginas se lean como un solo artefacto. (Rómpelo solo si el cambio en sí mismo es el argumento, una vez, en un punto de inflexión real.)

Navega por styles/<slug>/STYLE.md (o la galería en vivo en https://pptzen.xyz, y styles.json para un índice legible por máquina de slug → nombre / medio / mano / fórmula_de_prompt). Cada paquete incluye una prompt_formula reutilizable (SUPERFICIE / ESQUELETO / DISPOSITIVO / FIN / CRÍTICO). Resuelve el estilo nombrado por el usuario a su slug a través de styles.json (coincide con name, slug o aliases) y registra el slug resuelto en el plan.

Selección de tres capas — medio → mano → mundo:

• medio = el oficio (cine, tinta, plancha de cobre, baldosa…). mano = el tratamiento dentro de ese oficio (una mano fría y monumental vs. una mano cálida y brumosa son el mismo medio, diferentes ojos). mundo = la escena en la que vive el deck. Si el usuario solo da una vibra, elige un medio que se ajuste a los materiales propios del tema; haz solo una pregunta si realmente estás atascado.

5. Hechos vs. forma — decide la FORMA, nunca inventes HECHOS

La capa de juicio es dueña de cómo se ve una página, no de lo que afirma. Regla estricta:

Nunca inventes métricas, citas, precios, fechas, nombres de empresas o solicitudes de financiación.

Usa solo los hechos que el usuario proporcionó. Para cualquier número/afirmación que no tengas, escribe un marcador de posición visible ([POR CONFIRMAR], <tu métrica>) — nunca una fabricación que parezca plausible. Antes de generar, enumera las afirmaciones factuales que mostrará cada página y confirma que cada una se remonta a la entrada del usuario. Un deck se presenta como verdadero; una diapositiva hermosa con un inventado “$28k MRR” es un pasivo, no una característica.

Cómo entran los hechos — dos modos (así es como coexisten “una frase de entrada” y “nunca inventar”):

• Respaldado por fuentes (por defecto): la frase establece el deck; los hechos provienen del material que el usuario adjuntó o de la conversación ya existente. Si una página de datos no tiene fuente, se entrega con marcadores de posición — un borrador estructural completo que el usuario completa, no un deck listo con hechos.
• Modo investigación (solo si tu runtime puede navegar y el usuario lo solicitó): puedes recopilar hechos, pero cada afirmación debe tener su fuente registrada en plan.md junto a la página que la usa. La promesa de “una frase” se refiere a la forma — el usuario nunca responde preguntas de diseño. No es una licencia para alucinar contenido.

6. Generación de imagen completa — cuatro reglas estrictas

Cada página es un prompt autocontenido. Siempre:

1. Densidad en capas — la textura de fondo llena pero retrocede; un héroe ~70%; acentos en primer plano limitados; sin tarjetas de datos flotantes / barras laterales / widgets. Y sin aspecto de plantilla temática: sin cuadrículas de tarjetas redondeadas, cajas de pasos numerados o formas de diagrama genéricas con una textura detrás. La página es una escena en el mundo del material — si pareciera de una galería de plantillas genérica, está fuera de estilo.
2. Nunca inventes glifos — indica el texto exacto a renderizar y prohíbe cualquier otra palabra; las marcas decorativas deben ser solo geométricas (marcas de verificación, números, líneas de cota). Especialmente en escrituras no latinas: escribe los caracteres exactos y prohíbe añadidos.
3. Suprime palabras estructurales — termina cada prompt con una línea CRÍTICO que prohíba que aparezcan en la imagen palabras de estructura de prompt (ESTILO / SUPERFICIE / DISPOSITIVO / TEXTUAL / etiqueta / leyenda…).
4. Fija la longitud exacta del texto — “renderiza exactamente estas N palabras/caracteres — sin añadidos”, o el modelo agregará una palabra extraña.

Compón cada prompt de página mecánicamente — no improvises el material:

SUPERFICIE: pega la prompt_formula SUPERFICIE del paquete elegido **textualmente** desde
            styles/<slug>/STYLE.md (o styles.json). Escribir tu propia descripción del material
            en lugar de esto es la #1 forma de que los decks salgan fuera de estilo.
ESQUELETO:  <automático según el rol de la página; o "simple">
DISPOSITIVO: <el argumento de esta página como un objeto; o "ninguno">
TEXTO:      <palabras exactas a renderizar, y dónde>
CRÍTICO:    renderiza SOLO el texto anterior; cada letra correcta; sin glifos inventados; sin otro
            idioma; sin palabras estructurales; mantén el contenido clave alejado del ~8% superior/inferior.

Referencia completa: examples/relayboard-portolan/gen.py muestra diez prompts de página reales construidos así. Páginas densas/con mucho texto: genera a mayor resolución que las páginas de una sola palabra.

7. Si se presenta en vivo (restricciones que solo se aprenden en salas reales)

• Confirma primero la relación de aspecto de la pantalla — los grandes recintos suelen ser ultra-wide, no 16:9. Esta es una de las pocas cosas que vale la pena preguntar al usuario.
• Deja un corredor para el presentador — mantén la información clave fuera del tercio inferior; en ultra-wide, empuja los sujetos a los lados y mantén abierto el centro (el orador se para ahí).
• Cápsula de aserción — una conclusión de una línea en posición fija en cada página (“¿y qué?”); las páginas de detalle especialmente necesitan un lugar que indique qué concluir.
• Citas bilingües — Título Local (Título en Inglés); nombre de la persona localizado arriba, original más pequeño/más claro abajo; solo hechos, sin adjetivos.

8. Flujo de trabajo (una frase de entrada → un deck de salida)

1. Planifica — escribe plan.md: una fila por página con rol · densidad · dispositivo · texto exacto · slug_de_estilo, más un encabezado con la línea language:. El texto en las diapositivas por defecto está en el idioma en que trabaja el usuario — una conversación en chino obtiene un deck en chino a menos que pida otro (el hecho de que los decks de demostración estén en inglés no convierte al inglés en el predeterminado). Este es el registro de juicio (la parte que nadie puede capturar). Decide el material una vez, al inicio.
2. Genera — una imagen por página en slides/NN.jpg, usando la herramienta de imágenes del agente o scripts/gen_image.py. Usa nombres de archivo deterministas; regenera una sola página de forma aislada. Trabaja en el directorio del proyecto; llama a los ayudantes por su ruta completa dentro del repositorio o el directorio de la skill instalada (gen_image.py lee .env primero desde el directorio actual, luego desde la raíz del repositorio junto al script).
3. Control de calidad de las imágenes — revisa cada carácter de cada título contra el plan, confirma que no hay glifos inventados ni contradicciones entre páginas, y verifica que nada importante esté en el ~8% superior/inferior que el ensamblaje recortará. Luego la revisión de estilo: coloca tu página junto a styles/<slug>/samples/01.jpg — ¿mismo mundo? Una plantilla de negocios con la textura del material detrás FALLA; regenera con la SUPERFICIE del paquete pegada textualmente. Esta compuerta es de donde proviene la calidad.
4. Ensambla, luego revisa el deck — python3 scripts/assemble_pptx.py slides/ deck.pptx (16:9 a sangre completa; imágenes que no son 16:9 se recortan centradas con cobertura). Abre el resultado: orden de páginas, recorte, nada comido. Regenera y reensambla páginas individuales según sea necesario. La salida es un .pptx basado en imágenes: excelente para presentar, pero el texto no es editable — corregir un error tipográfico significa regenerar esa página. PDF / Keynote / Google Slides importan las mismas imágenes.

Ver examples/relayboard/ para un deck completo de diez páginas trabajado con su registro de juicio. Los análisis profundos opcionales se encuentran en references/ (leyes de diseño, biblioteca de esqueletos, patrones visuales, entrenamiento para presentaciones — actualmente en chino; cárgalos cuando necesites el razonamiento subyacente).

Lista de verificación de entrega

• ¿Densidad establecida por página? ¿Páginas de evidencia detalladas, bloques densos terminando en una página de respiro?
• ¿Cada página: un dispositivo que se entiende (o un “ninguno” deliberado), solo un dispositivo principal?
• ¿Material fijo en todo el deck? ¿Estilo resuelto a un slug real?
• ¿Cada afirmación factual se remonta a la entrada del usuario? ¿Sin números/citas/precios/fechas inventados?
• ¿Cuatro reglas estrictas en cada prompt? ¿Contenido clave alejado de la zona de recorte?
• ¿Personajes/conceptos recurrentes fijados de forma idéntica en cada prompt?
• ¿Revisaste cada carácter después de la generación? ¿Ensamblaste y abriste el .pptx?