Cuándo usar esto

Usa Typst en lugar de Word/.docx para cualquier informe técnico detallado: informes de investigación, resúmenes de arquitectura, documentos de causa raíz, explicadores de migración. Documentos objetivo que:

Se lean como un informe técnico real: portada, resumen ejecutivo, secciones numeradas
Se vean bien impresos (tipografía similar a LaTeX: #set page, #set heading(numbering: "1.1"), texto justificado)
Incluyan diagramas (diagramas de arquitectura/flujo, no solo prosa)
Incluyan tablas (tablas de comparación, de evidencia, de estado)
Incluyan enlaces en los que se pueda hacer clic a fuentes (hilos de chat, PRs de GitHub, páginas wiki)
Citen fuentes primarias con citas directas (mensajes, cuerpos de PR) atribuidas por nombre/fecha

Frases de activación: "redacta esto", "crea un documento", "pásalo a Typst", "haz un informe sobre esto" — especialmente después de una investigación de múltiples fuentes (búsqueda en chat, revisión de PRs de GitHub, evidencia de sistema en vivo) que necesite ser sintetizada en un artefacto compartible.

Antes de compilar, guarda y consulta un archivo personal de errores comunes de Typst (por ejemplo, ~/notes/typst.md) para conocer las trampas sintácticas conocidas (ubicación de notas al pie, colisiones con #N, importación de Fletcher, tamaño de columnas de tabla, etc.) — y añade a él cada vez que se descubra una nueva clase de error de compilación.

Reglas sintácticas críticas (Lista de verificación previa a typst compile):

El marcado de negrita es una sola *palabra*, NUNCA **palabra**: Los dobles asteriscos de Markdown emiten docenas de advertencias del compilador (warning: no text within stars; using multiple consecutive stars has no additional effect).
Las cadenas en modo matemático requieren comillas: En $ ... $ , los identificadores de múltiples letras como $Count=65$ o $RTO$ fallan en la compilación (unknown variable). Escribe $"Count"=65$ o coloca el código entre acentos graves (`Count=65`).
No hay operadores de barra invertida de LaTeX en matemáticas: Escribir $\approx$ falla (unknown variable: pprox). Typst usa símbolos simples: $approx$ sin barra invertida.

Profundiza en el contenido; sé consciente de los recursos en la presentación

Dos directrices permanentes que dan forma a cada informe:

Profundiza en el contenido técnico genuino. Apunta a una profundidad técnica exhaustiva, no a un resumen superficial: más salida de consola sin procesar, más diagramas de arquitectura/máquina de estados, detalles a nivel de registro/campo de bits o circuito digital cuando el tema esté relacionado con hardware, detalles a nivel de instrucción de CPU/ensamblador cuando el tema esté relacionado con la ejecución de software. Cuando un borrador se sienta "terminado" en 5-6 páginas, esa es una señal para profundizar una capa más (un volcado adicional de redis-cli/systemctl/registro, un diagrama de arquitectura adicional, un ángulo adicional de comparación industrial), no para detenerse. Consulta "Expectativa de profundidad" a continuación para el desglose concreto sección por sección.
Pero sé consciente de los recursos en la presentación, no en el contenido. La profundidad del contenido y la conciencia de los recursos del estilo son ejes separados: profundiza en hechos/evidencias/diagramas, pero mantén la presentación visual en sí misma con poca tinta: fondos de tono claro + bordes/texto coloreados en lugar de rellenos de color sólido, y el color usado solo donde tenga significado (ver Esquema de color a continuación). Poca tinta gobierna la tinta del cuerpo de la página, NO el bloque de título: el título SÍ está enmarcado (ver Esquema de color punto 1). Más páginas de sustancia técnica real es el objetivo; más tinta de color sólido por página no lo es.

Flujo de trabajo

Reúne TODA la evidencia primero (búsquedas en chat, lecturas de PRs de GitHub, salida de comandos en vivo, búsqueda de artefactos anteriores en el rastreador de incidencias/chat) antes de escribir — no comiences el archivo .typ a mitad de la investigación; sintetiza una vez.
Escribe el código fuente .typ completo en una o dos llamadas write/eval, usando la plantilla de estructura anterior (título enmarcado con un solo acento, encabezados con acento y una regla fina, encabezados de tabla con tono claro, llamadas semánticas en 2-4 momentos clave elegidos por significado no por novedad, bloques de consola claros, diagramas de Fletcher envueltos en #figure para gráficos de nodos, sin tabla de contenido por defecto). Si usas Fletcher, SIEMPRE comienza el archivo con #import "@preview/fletcher:0.5.7": diagram, node, edge — omitir esta importación es el error de primera compilación más común.
Compila: typst compile file.typ (desde un directorio de trabajo donde se encuentre el archivo — verifica typst --version una vez por sesión para confirmar que el binario está disponible; si usas Fletcher, una compilación de prueba en /tmp desechable confirma la resolución de red/paquete antes de integrarlo en el documento real). ¿Te encuentras con un error de compilación? Revisa tu archivo de notas de errores comunes antes de depurar desde cero.
Verifica visualmente siempre antes de declarar terminado — renderiza cada página a PNG (typst compile --format png --ppi 100 file.typ "page-{p}.png" — entrecomilla el patrón de salida) y read cada PNG para inspeccionar el diseño/espaciado/renderizado, especialmente cualquier página con un diagrama, tabla o llamada. Los diagramas con 3 o más aristas o pares de aristas bidireccionales necesitan un escrutinio particular por colisiones de etiquetas.
Luego realiza una pasada de lectura de CONTENIDO separada: la verificación del diseño no es verificación del contenido. El paso 4 prueba que nada se renderiza mal; NO prueba que nada sea cierto. read cada página renderizada de nuevo, esta vez leyendo la prosa contra el material de origen, y busca específicamente: (a) referencias cruzadas de sección escritas a mano ("ver §9.1.3") que quedaron obsoletas cuando se insertó un capítulo; (b) celdas de tabla cuya afirmación está invertida o transpuesta en relación con la fuente; (c) números que se transcribieron de segunda mano en lugar del artefacto principal — márcalos como [INFERENCIA] o ve a verificarlos. Confirmado como necesario en la práctica: un documento que pasó la pasada de diseño completa aún contenía una referencia § colgante Y una celda de tabla invertida factualmente, ambos detectados solo mediante la lectura. Un documento de 40 KB escrito en una sola pasada NO ha sido revisado solo porque compiló.
Mueve los archivos .typ + .pdf finales a la ubicación de documentos del proyecto (por ejemplo, docs/generated/) y confirma ambos, luego elimina cualquier archivo de verificación PNG intermedio — mantén la fuente junto con la salida compilada para que se pueda volver a editar más tarde.

Usa marcado semántico

Según la propia guía de accesibilidad de Typst: usa siempre el elemento semántico real (= Heading, #quote(...), #table(...)) en lugar de aplicar estilo manual a texto sin formato/prosa para que parezca ese elemento (por ejemplo, #text(size: 16pt, weight: "bold")[Heading]). Nunca inventes una convención paralela "parece un encabezado"; siempre basa la apariencia en el elemento de marcado real.

Esquema de color

Fuente del cuerpo: New Computer Modern. El punto de referencia es "como LaTeX" — NCM es el aspecto de LaTeX y viene con Typst, por lo que siempre se resuelve. NUNCA elijas una fuente que no esté instalada en la máquina (verifica con typst fonts): Typst solo advierte sobre una familia faltante y recurre silenciosamente, por lo que el documento se compila "limpio" mientras se ve incorrecto. Si aparece una advertencia de unknown font family, eso es un defecto que hay que corregir, no una advertencia que tolerar.
Paleta de llamadas semánticas. verde #1a7f37, amarillo #9a6700, rojo #cf222e, azul #0969da, púrpura #6639ba, naranja #bc4c00; tintes de consola/tabla #f2f6fb / #eaf1fb con borde #9fb8d6 / #c8d6e8. Las referencias en línea y en bloque deben usar una familia monoespaciada que exista en la máquina (por ejemplo, Consolas, JetBrains Mono, Menlo).

Un color de acento estructural, usado solo para el marco — más bloques de llamadas semánticas para el significado. Este es el patrón establecido; aplícalo por defecto sin derivarlo desde cero:

Bloque de título: texto centrado de color liso con marco con borde. Usa #box(fill: white, stroke: 1.5pt + accent, ...) alrededor del título.
Encabezados de tabla: relleno de tono claro + texto de color de acento, NUNCA un relleno de color sólido.
Bloques de llamadas semánticas para hallazgos significativos — aquí es donde se gana color extra, porque es funcional, no decorativo. Usa el que se ajuste al contenido; no los fuerces todos en cada documento. De 2 a 4 llamadas totales por informe es una buena densidad, no una por párrafo.
- Verificado (marca de verificación verde) — hallazgo confirmado como bueno, una línea.
- Anomalía (exclamación amarilla) — inesperado pero aún no confirmado como defecto.
- Defecto confirmado (X roja) — hallazgo confirmado como malo, una línea.
- Nota (información azul) — una observación no crítica que vale la pena destacar.
- Consejo (bombilla púrpura) — una sugerencia útil o mejor práctica.
- Pregunta abierta (signo de interrogación naranja) — una discrepancia o consulta genuina no resuelta.
Varía el tono según el documento/sección donde ayude a la legibilidad de la impresión.
Los colores de los cuadros de diagrama siguen siendo semánticos/basados en roles.
No hay grandes rellenos de color oscuro sólido en ningún lado (por ejemplo, un banner azul oscuro completo con texto blanco). Encabezados de sección: texto coloreado + una regla coloreada delgada debajo, no una banda o cuadro de color relleno.
Bloques de salida de consola/código: fondo de tono claro, no gris. Un gris plano #f4f4f4 se lee como aburrido/de fotocopiadora. Usa un tono claro con un borde sutil a juego.
NUNCA uses #pagebreak() entre capítulos. Un salto antes de cada encabezado = deja media página de papel en blanco por capítulo y desperdicia hojas reales al imprimir. Deja que las secciones fluyan; un nuevo capítulo que comienza a media página es CORRECTO. El único #pagebreak() aceptable es el único que separa la portada del cuerpo.

Dos secciones predeterminadas: inclúyelas sin que se te solicite

Contexto competitivo / de la industria. ¿Cómo resuelven las alternativas este problema, y qué compra y cuesta estructuralmente esta posición arquitectónica? Enmarca cada ventaja como un riesgo comprobable correspondiente. Etiqueta la sección como conocimiento general de la industria con [INFERENCIA] a menos que provenga de un documento competitivo real.
El automatismo / banco de pruebas, concretamente. Invocación exacta, host de ejecución, venv y dependencias fijadas, selección de marcadores y cómo leer los recuentos de recopilados vs. no seleccionados vs. ejecutados. "Hay un conjunto" no es cobertura.

Colocación de figuras: envuelve diagramas/tablas en `#figure(...)`, deja que Typst los flote

Según la guía de diseño de Typst, las figuras por defecto se colocan en línea en el flujo de contenido, pero envolver un diagrama o tabla en #figure(..., caption: [...]) desbloquea placement: top/placement: bottom para permitir que Typst lo flote hacia la parte superior/inferior de la página en lugar de dividir incómodamente el contenido a su alrededor a mitad del párrafo. Siempre da a los diagramas un envoltorio #figure(...) con un título real (nunca una llamada #diagram(...) desnuda flotando en prosa) — esto también es lo que hace que el diagrama sea referenciable a través de @sec-label y proporciona a los lectores de pantalla/herramientas de reutilización un emparejamiento semántico adecuado de figura+título, no solo una imagen sin etiqueta.

Fletcher para diagramas de nodo/arista

Patrón de trabajo, confirmado que compila y renderiza correctamente (envuelto en #figure según la guía de colocación anterior). Recuerda la importación (ver Flujo de trabajo paso 2) — este fragmento asume que ya está en la parte superior del archivo:

#figure(
  diagram(
    node-stroke: 0.6pt,
    spacing: (3em, 2em),
    node((0,0), [Paso 1], fill: rgb("#dbe9ff"), corner-radius: 4pt),
    node((0,1), [Paso 2], fill: rgb("#dbe9ff"), corner-radius: 4pt),
    edge((0,0), (0,1), "-|>", bend: 10deg),
    edge((0,1), (0,0), "-|>", bend: 10deg),
  ),
  caption: [Título de una línea que explica ambas direcciones/aristas, ya que las etiquetas en línea se omiten aquí.],
)

Las coordenadas son tuplas (columna, fila); node-stroke/fill/corner-radius estilizan nodos individuales; edge(from, to, "-|>") dibuja una flecha (la cadena de marca, no un argumento de palabra clave, selecciona la punta de flecha — "-|>" y "->" funcionan; "..|>" para una flecha punteada). Varias cadenas independientes pueden compartir una llamada diagram(...) usando diferentes índices de columna por cadena más un nodo de fila de encabezado con stroke: none por cadena. Mantén las etiquetas de arista en una palabra/frase corta y mueve la explicación completa al caption de la figura — las etiquetas de arista en línea más largas que una palabra son el fallo clásico de colisión de etiquetas.

Expectativa de profundidad: por defecto, formato largo, profundo para expertos, no un resumen

A menos que se solicite explícitamente algo corto, apunta a 10-12 páginas renderizadas para un informe de investigación completo: un informe corto, correcto pero superficial es un modo de fallo, no un resultado eficiente. Concretamente, "profundizar" significa incluir, siempre que el tema lo permita:

Salida de consola/registro completa sin procesar, no fragmentos truncados — comando real + salida real, palabra por palabra, para cada afirmación que provino de evidencia de sistema en vivo.
Al menos un diagrama de arquitectura o máquina de estados (a través de Fletcher, ver arriba) que muestre cómo se conectan las piezas, no solo prosa que lo describa.
Detalle a nivel de registro/campo de bits o circuito digital cuando el tema esté relacionado con hardware (por ejemplo, el diseño de bits de un registro de configuración específico, un diagrama de temporización de señal, la tabla de mapeo de puertos de un bloque ASIC, definiciones reales de struct/opcode extraídas del código fuente del controlador) — no te detengas en "el hardware hace X", muestra el mecanismo real.
Detalle a nivel de instrucción/ensamblador o llamada al sistema de CPU cuando el tema esté relacionado con la ejecución de software (por ejemplo, qué llamada al sistema emite realmente un controlador, cómo se ve el desmontaje de la ruta crítica) — no te detengas en "el controlador hace X", muestra la ruta de código real.
Una sección dedicada de Contexto Externo/Industrial (ver abajo) — nunca presentes un mecanismo interno de forma aislada.
Búsqueda genuina de arte previo/historial — verifica el rastreador de incidencias, el historial de chat y el historial de git para ver si esta misma pregunta se hizo antes (incluso años antes); un informe que cierra una pregunta abierta de varios años es una evidencia más sólida que uno que trata un hallazgo como completamente nuevo.

Estructura: (1) Título + Resumen Ejecutivo, (2) Antecedentes, (3) Cronología/Metodología de Evidencia — una subsección por hallazgo distinto con su propio bloque de evidencia citada, generalmente la sección más larga, (4) Sección de Desambiguación si el nombre del tema se superpone con otra cosa, (5) Tablas comparativas, (6) Contexto industrial/externo, (7) Arquitectura/Síntesis como una lista numerada de principio a fin emparejada con diagramas, (8) Preguntas Abiertas con seguimientos concretos, (9) Vinculación con la investigación original, (10) Apéndice con evidencia sin procesar completa recortada del cuerpo. Cuando un borrador se sienta terminado pero breve, haz una ronda más de investigación real (otra verificación en vivo, otro volcado de registro, otra búsqueda web, otro diagrama, otra búsqueda en el historial de arte previo) en lugar de rellenar la prosa existente — la profundidad debe provenir de contenido real, nunca de relleno o repetición.

ankitg12/agent-skills

¿Qué es agent-skills?

Preguntar en tu IA favorita

Documentación