wisp-writer: redactar con el tema Wisp

wisp-writer: redactar artículos con el tema Wisp manteniendo un estilo coherente

La filosofía de Wisp es ser sobrio, preciso y comedido. Los artículos se escriben en src/content/posts/<slug>/index.mdx (o index.md), y el frontmatter se define en src/content.config.ts. Este skill proporciona:

SKILL.md
reference/   frontmatter.md  style-guide.md  elements.md  templates/
scripts/     new_post.py  check_post.py  tests/   (Python + uv, dependencias inline PEP 723, no requiere instalación)

Convención de comandos

Todos los comandos se ejecutan desde la raíz del sitio, con la forma uv run skills/wisp-writer/scripts/<script>.py .... Al copiar este skill a otro sitio Wisp:

• Colócalo en <sitio>/skills/wisp-writer/: los comandos se mantienen igual.
• Colócalo en <sitio>/.claude/skills/wisp-writer/ o ~/.claude/skills/wisp-writer/: cambia la ruta por la ubicación real; el script buscará hacia arriba astro.config.* o src/content, o puedes usar --root <raíz del sitio> para especificarlo.
• Si no encuentra el sitio, el script mostrará un aviso y terminará con código de salida 2, sin escribir ningún archivo.
• Si no tienes uv: python3 <ruta>/new_post.py ... también funciona (solo usa la biblioteca estándar, requiere Python 3.10+).

Flujo de trabajo

1. Define la audiencia y los puntos clave. Antes de escribir, responde tres preguntas: quién es la audiencia (qué sabe y qué no), qué se llevará después de leer (una conclusión en una frase) y el tipo de artículo. Si falta información, pregunta al usuario; no inventes hechos, datos ni referencias.
2. Crea el artículo. Elige la plantilla según el tipo: tutorial, deep-dive (inmersión profunda), algorithm (explicación de algoritmo, con componentes interactivos), note (nota corta), paper-reading (lectura de artículo académico).

   uv run skills/wisp-writer/scripts/new_post.py atencion-explicada \
     --title "Explicación del mecanismo de autoatención" --template deep-dive \
     --tags "LLM,Transformer" --category Aprendizaje automático \
     --description "Desde la intuición hasta la fórmula, explica el proceso de cálculo de la autoatención."
   

   El slug se escribe en kebab-case; si ya existe, mostrará un error. El script listará las etiquetas y categorías existentes; prioriza la reutilización. Parámetros: --draft, --md/--mdx, --date, --list-templates.
3. Escribe. Sigue la guía de estilo, la escritura de elementos se detalla en elements, y los campos en frontmatter. Reemplaza todos los TODO de la plantilla.
4. Ilustraciones e interactividad. Si necesitas diagramas, usa el skill wisp-diagram para generar el archivo fuente y .wisp.svg, luego inserta la imagen con la sintaxis de referencia; para flujos simples usa Mermaid directamente. Si necesitas demostraciones interactivas, usa los componentes explainer existentes (actualmente MatMul); para otros algoritmos necesitarás crear nuevos componentes, el método se describe en docs/guide/explainers.md —eso es un cambio de código, que debes explicar y obtener aprobación por separado, no lo hagas mientras escribes el artículo.
5. Revisa y corrige.

   uv run skills/wisp-writer/scripts/check_post.py atencion-explicada --strict
   

   El formato de salida es archivo:línea nivel regla explicación. Los error deben corregirse; los warning evalúalos uno por uno, si se pueden corregir, hazlo; los info son solo sugerencias. --json para lectura por programa, --all para revisar todos los artículos.
6. Previsualiza. pnpm build debe pasar (valida frontmatter y Mermaid); para ver el resultado visual usa pnpm dev. Opcional: usa Playwright para tomar una captura de pantalla del artículo en modo claro y oscuro, verificando que fórmulas, gráficos y bloques de código no se desborden y que en modo oscuro sean legibles.

Reglas estrictas

1. El cuerpo del texto empieza con h2, no se escribe h1, y los niveles no se saltan; los h2 deben ser sintagmas nominales.
2. title ≤ 80 caracteres, description ≤ 200 caracteres; description debe indicar claramente qué problema resuelve el artículo.
3. Las etiquetas y categorías reutilizan las existentes, con la misma capitalización (no tener a la vez llm y LLM).
4. Los párrafos en chino usan signos de puntuación de ancho completo; no se añaden espacios manuales entre chino e inglés; el énfasis en chino se marca con negrita, no con cursiva.
5. La primera vez que aparece un término técnico se indica su equivalente en inglés, por ejemplo: "自注意力（self-attention）".
6. Cada bloque de código tiene un identificador de lenguaje; el plegado de bloques largos es opcional, por defecto no se toca.
7. Cada imagen tiene un alt que describe la conclusión que la imagen quiere transmitir; los pies de imagen usan el formato "图 N：说明".
8. No se codifican colores directamente, no se usa style=, no se usan escalas de Tailwind; los colores solo pueden venir de variables del tema.
9. Los artículos que usan componentes deben ser .mdx e incluir el import; los componentes interactivos llevan client:visible.
10. No se inventan hechos, datos, referencias ni enlaces. Si no hay certeza sobre algo, márcalo explícitamente o elimínalo.
11. No se modifican artículos existentes a menos que el usuario lo solicite; solo se trabaja dentro de src/content/posts/<slug>/.

Fragmento de ejemplo

El siguiente es un fragmento que sigue el tono adecuado (explica una idea, sin rodeos ni exageraciones):

## ¿Por qué dividir por √d?

Supongamos que cada componente de $q$ y $k$ es una variable aleatoria independiente con varianza 1. Entonces la varianza del producto punto $q \cdot k$ es $d_k$. Cuanto mayor es la dimensión, mayor es el producto punto, y más se acerca la softmax a one-hot, lo que hace que los gradientes se vuelvan muy pequeños.

Al dividir por $\sqrt{d_k}$, la varianza vuelve a estar alrededor de 1, y la salida de la softmax se mantiene en un rango moderado. Sin este paso, es difícil entrenar redes profundas.

Compara con: "Como todo el mundo sabe, este truco súper simple pero muy importante puede mejorar enormemente el rendimiento." — vacío, exagerado, sin información.

Errores comunes

• Comenzar con frases como "Este artículo presentará..." o "Con el desarrollo de...". En lugar de eso, presenta directamente la conclusión o el problema.
• Escribir # Título en el cuerpo del texto; o saltar de h2 directamente a h4.
• Usar oraciones completas como título ("Veamos cómo implementarlo") en lugar de un sintagma nominal ("Implementación").
• Mezclar comas o paréntesis de ancho medio en texto chino; usar cursiva para enfatizar en chino.
• Escribir componentes en archivos .md, o en .mdx olvidar el import; olvidar client:visible en componentes interactivos.
• Imágenes sin alt; referenciar archivos .excalidraw que aún no se han generado (primero dibujar, luego referenciar); referenciar el archivo fuente en lugar de .wisp.svg.
• Usar etiquetas nuevas para un mismo concepto (por ejemplo, Llm, 大模型 coexistiendo con la etiqueta existente LLM).
• Texto excesivamente largo en nodos Mermaid, que se superpone al renderizar; debe acortarse a aproximadamente 12 caracteres chinos o menos.
• Dejar TODO pendientes al entregar; check_post.py --strict los detecta.
• Escribir código sin explicación: antes del código indica su propósito, después del código explica los puntos clave o el resultado esperado.