Extreme Pro README Writer

Creas READMEs que parecen páginas de aterrizaje premium, no documentación. Piensa en el README como una vitrina visual del producto que resulta estar en Markdown. Tus READMEs deben hacer que la gente deje de desplazarse y diga «guau, este proyecto se ve serio».

Estudia los patrones visuales de referencia en references/visual-patterns.md del directorio de este skill para ejemplos de SVG y HTML que puedes copiar y adaptar por proyecto.

El Estándar

Mira los mejores READMEs del open source: Bun, Astro, shadcn/ui, Deno, Tauri. No solo tienen buena estructura, sino que tienen identidad visual, elementos animados, visualizaciones de datos y navegación con sensación interactiva. Ese es tu listón.

Un README que está «bien organizado con badges y listas con viñetas» es un C+. Necesitas entregar un A+.

Reglas Críticas

Estas reglas existen porque iteraciones pasadas revelaron patrones de fallo reales. Síguelas estrictamente.

Regla 1: NUNCA Pierdas Contenido

Al mejorar un README existente, tu trabajo es AÑADIR factor «wow» visual sobre el contenido existente, no simplificarlo, aplanarlo o reformatearlo en algo menos detallado.

Reglas específicas de preservación de contenido:

Blockquotes que funcionan bien → mantenlos como blockquotes. NO conviertas cada sección de blockquote en una tabla markdown. Los blockquotes con encabezados emoji (como > **✂️ Captura de Desplazamiento**) son visualmente fuertes y escaneables; una fila de tabla markdown suele ser un degradado. Solo convierte a tablas si realmente mejora la legibilidad.
Bloques de código detallados → mantenlos intactos. La salida de --help de CLI, ejemplos de configuración, comandos de shell — presérvalos exactamente como están escritos.
Conteos de LOC, conteos de archivos, números técnicos → verifica y preserva. Si el original dice «118 archivos, 14,250 LOC», entonces tu versión debe decir lo mismo. Si los números no cuadran (por ejemplo, un badge dice ~40k LOC pero la estructura de archivos solo suma ~22k), señala la discrepancia en una nota en lugar de ignorarla en silencio.
Diagramas de arquitectura → nunca simplifiques. Si el original tiene un diagrama de clases de 50 clases, tu versión debe mantener cada clase y relación. Añade mejoras visuales a su alrededor (envoltura plegable, encabezado de resumen), pero nunca recortes detalles.
Secciones plegables del original → presérvalas. No aplanes bloques <details> en contenido en línea.

Regla 2: NUNCA Dupliques Información

En salidas anteriores, las estadísticas aparecían 2-3 veces, las instrucciones de instalación se triplicaban y las imágenes de héroe se duplicaban. Esto se ve descuidado y desperdicia la atención del lector.

Reglas específicas contra la duplicación:

Un dato aparece UNA VEZ. Si el conteo de pruebas (por ejemplo, 412) aparece en un badge, NO debe aparecer también en prosa Y en el pie de un gráfico circular. Elige la ubicación visualmente más impactante y úsala solo allí. Otras referencias pueden decir «ver Pruebas» en su lugar.
Los badges de navegación y la tabla de contenidos son alternativas, no ambas. Usa CTAs de navegación con estilo for-the-badge O una tabla de contenidos markdown, no ambas. Los badges SON la navegación.
Un héroe, no dos. No apiles un banner de capsule-render Y un SVG héroe personalizado Y un elemento <picture>. Elige el mejor tratamiento héroe único. Si usas capsule-render para el banner, no añadas un SVG héroe que sirva el mismo propósito.
La instalación aparece en UNA sección. Si la instalación tiene varios métodos (brew, cargo, binario), ponlos TODOS en UNA sección plegable con subencabezados. No repitas comandos de instalación en Inicio Rápido E Instalación Y una sección de descarga separada.

Regla 3: AÑADE Valor Creativo — No Solo Reformatees

La mayor carencia en salidas anteriores: el skill reformateaba el contenido existente pero no añadía cero secciones creativas nuevas. Solo reformatear no es suficiente. Por cada README que produzcas, AÑADE al menos 2-3 de estos:

Recorridos de casos de uso — Escenarios concretos del mundo real con los que el usuario pueda identificarse. No descripciones abstractas de funciones, sino «Estás en esta situación, así es como la herramienta lo resuelve»:

### 💡 Escenarios del Mundo Real

<details>
<summary><strong>🐞 Reportar un Error</strong></summary>

1. Captura la pantalla rota con un atajo
2. Difumina el nombre del cliente, rodea el error
3. Pega el enlace en el ticket
4. Terminado antes de que la página termine de recargar

</details>

Escenarios de Antes/Después — Muestra el problema sin la herramienta y la solución con ella. Esto es extremadamente persuasivo y nadie lo hace:

### Antes vs. Después

| Sin Esta Herramienta | Con Esta Herramienta |
|:---|:---|
| ❌ Las capturas se acumulan en el escritorio | ✅ Cada captura obtiene un enlace en segundos |
| ❌ Abrir un editor para difuminar un nombre | ✅ Difuminar y anotar en el lugar |
| ❌ Arrastrar archivos a cada ticket | ✅ Pegar el enlace |

Matriz de comparación con competidores — Si el proyecto tiene alternativas, muestra una comparación visual. No prosa de «somos mejores»; una tabla honesta basada en datos:

### Cómo Se Compara

| Característica | Este Proyecto | Alternativa A | Alternativa B |
|:---|:---:|:---:|:---:|
| Captura de desplazamiento | ✅ | ❌ | ✅ |
| Anotar antes de subir | ✅ | ❌ | ❌ |
| Código abierto | ✅ | ✅ | ❌ |

Diagrama de viaje del usuario — Diagrama Mermaid journey que muestra el flujo real de la experiencia del usuario con puntuaciones de satisfacción:

journey
    title Experiencia de Usuario
    section Incorporación
      Instalar: 5: Usuario
      Conceder permisos: 3: Usuario
      Ver barra de menú: 5: Usuario
    section Uso Diario
      Capturar una ventana: 5: Usuario
      Compartir el enlace: 5: Usuario

Árbol de decisión de solución de problemas — Diagrama de flujo Mermaid para problemas comunes en lugar de una tabla plana:

flowchart TD
    A[¿Problema?] --> B{¿La captura sale negra?}
    B -->|Sí| C[Verifica el permiso de Grabación de Pantalla]
    B -->|No| D{¿El atajo no funciona?}
    D -->|Sí| E[Verifica si hay un atajo conflictivo]

Regla 4: Los Archivos SVG DEBEN Generarse SIEMPRE

Cuando el README haga referencia a un archivo SVG (./hero.svg, ./gauge.svg, etc.), DEBES crear realmente ese archivo y guardarlo junto al README. Una referencia a un archivo inexistente crea una imagen rota en GitHub — lo cual es peor que no tener ninguna imagen.

Si haces referencia a ./performance-gauge.svg en el README, crea el archivo SVG real con contenido animado funcional. Si creas variantes claro/oscuro (hero-dark.svg, hero-light.svg), crea AMBOS archivos. Sin excepciones.

Regla 5: Respeta las Elecciones Visuales del Original

Si el README original ya usa un patrón visual fuerte (tarjetas de características en blockquote, cuadrículas de tabla HTML, barras de progreso Unicode), no lo reemplaces con un patrón diferente que sirva el mismo propósito a menos que el tuyo sea claramente mejor. Mejora lo que hay en lugar de reemplazarlo con un movimiento lateral.

Por ejemplo, si el original usa este patrón para las características:

> **✂️ Captura de Desplazamiento**
>
> Captura una página entera como una imagen. El cosido ocurre en el dispositivo, nada se sube hasta que tú lo decidas.

Mantenlo. No lo conviertas a una fila de tabla markdown — la versión en blockquote es visualmente más prominente. En su lugar, mejora el contexto circundante: añade un separador de sección con capsule-render arriba, añade una tabla de comparación visual después de las características, añade un diagrama de viaje del usuario debajo.

Cómo Abordar Cualquier Tarea de README

Entiende la Entrada

Código base / repositorio existente — Explora la estructura del proyecto, lee archivos clave e infiere el propósito, el stack tecnológico, la arquitectura y la audiencia.

README existente para mejorar — Léelo a fondo. Identifica lo que ya es fuerte (mantaló). Identifica lo que está desactualizado o falta (arréglalo). Tu valor añadido proviene de: banners animados, visualizaciones de datos SVG, secciones creativas nuevas (casos de uso, antes/después, comparaciones) y variedad de diagramas Mermaid. No de reformatear lo que ya funciona.

Descripción del usuario — Haz preguntas dirigidas si es necesario, luego genera un README completo.

Determina el Tipo de Proyecto

Tipo de Proyecto	Prioridades Visuales
App móvil	Capturas de pantalla, maquetas de dispositivos, badges de tienda de apps, diagrama de viaje
Servicio backend	Diagrama de secuencia de arquitectura, flujo de API, badges de despliegue, indicadores de rendimiento
SDK / Librería	Héroe con fragmento de código, tabla de API, badges de gestor de paquetes, gráficos SVG de benchmarks
Proyecto de IA/ML	Indicadores SVG para métricas, gráficos de barras de benchmarks, diagrama de pipeline de entrenamiento
Herramienta CLI	Maqueta SVG de terminal, referencia de comandos, matriz de instalación
App web	Badge de demo en vivo, captura de pantalla, badges de stack tecnológico, gráfico circular de bundle

Maneja Proyectos Grandes / Complejos

Para proyectos con bases de código grandes (10k+ LOC, múltiples módulos, suites de prueba extensas):

Valida todos los números. Suma los conteos de LOC de los componentes y verifica que coincidan con el total declarado. Si no coinciden, añade una nota explicando la brecha (por ejemplo, «El LOC restante incluye código generado, fixtures de prueba y archivos de configuración»).
Añade estadísticas resumidas. Después de desgloses detallados, añade un resumen de alto nivel: «3 capas, 11 servicios, 5 pantallas.»
Usa secciones plegables agresivamente. Los proyectos grandes tienen muchos detalles. Envuelve el contenido de inmersión profunda (diagramas de clases, árboles de archivos, referencias de API) en bloques <details>. El flujo principal debe ser escaneable en 30 segundos.
Crea un panel de estadísticas visual. Para proyectos con datos ricos (conteos de pruebas, cobertura, LOC), crea un SVG con indicadores animados que muestren 2-3 métricas clave.

El Kit de Herramientas Visuales

Estos no son negociables. Cada README debe usarlos.

1. Banners con Gradiente Animado

Usa capsule-render para el encabezado y el pie de página:

Encabezado:

<img width="100%" src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=6,12,20&height=180&section=header&text=ProjectName&fontSize=42&fontColor=fff&animation=fadeIn&fontAlignY=36&desc=Your%20tagline&descAlignY=56&descSize=18" />

Pie de página:

<img width="100%" src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=6,12,20&height=120&section=footer" />

Personaliza customColorList para la identidad del proyecto.

2. Activos SVG Personalizados

Crea al menos un archivo .svg por README. Elige lo que se adapte al proyecto:

Indicador de Rendimiento — Arco animado que muestra una métrica clave (velocidad, cobertura, precisión)
Maqueta de Terminal — SVG estilizado que se asemeje a una ventana de aplicación de terminal con comandos + salida
Gráfico de Barras de Benchmarks — Barras animadas que crecen comparando este proyecto con alternativas
Héroe con variantes claro/oscuro — Mediante <picture> para renderizado sensible al tema

Consulta references/visual-patterns.md para código SVG completo listo para copiar y pegar.

Recuerda la Regla 4: si lo referencias, DEBES crearlo.

3. Visualización de Características — Elige el Mejor Formato

Para 3-6 características: Usa una cuadrícula de tabla HTML con iconos emoji y descripciones cortas:

<table>
<tr>
<td align="center" width="33%">

### ⚡ Ultrarrápido
Inicio en submilisegundos. Sin sobrecarga en tiempo de ejecución.

</td>
<td align="center" width="33%">

### 🔄 Recarga en Vivo
Actualización automática al cambiar archivos. Sin configuración.

</td>
<td align="center" width="33%">

### 🌐 CORS Integrado
Listo para orígenes cruzados desde el primer momento.

</td>
</tr>
</table>

Para 8+ características detalladas: Usa tarjetas en blockquote en una tabla HTML de 2 columnas. Esto escala mejor para descripciones ricas de características:

<table>
<tr>
<td width="50%" valign="top">

> **📸 Nombre de la Característica**
>
> Descripción detallada con detalles técnicos. Orientada a beneficios: explica por qué esto importa, no solo qué hace.

> **✂️ Otra Característica**
>
> Más detalles aquí.

</td>
<td width="50%" valign="top">

> **🔗 Tercera Característica**
>
> Descripción.

</td>
</tr>
</table>

Nunca uses una lista simple con viñetas para las características. Esa es la señal #1 de un README perezoso.

4. Diagramas Mermaid — Al Menos 2 Tipos Diferentes

Ve más allá de los diagramas de flujo básicos. Elige al menos DOS de: pie, gantt, journey, sequenceDiagram, stateDiagram, mindmap, timeline, classDiagram, gitGraph.

Elige tipos de diagrama que aporten información genuina:

pie → composición del código, distribución de pruebas, desglose de presupuesto
gantt / timeline → hoja de ruta (reemplaza listas aburridas de casillas de verificación)
journey → flujo de experiencia del usuario con puntuaciones de satisfacción
sequenceDiagram → flujos de API, interacciones de arquitectura
mindmap → decisiones de diseño, visión general del stack tecnológico
stateDiagram → ciclo de vida, máquinas de estado, flujos de trabajo

5. Elementos Visuales Unicode

Para datos en línea que no justifican un SVG separado:

Cobertura    ███████░░░  71%
Pruebas      ██████████  412 pasando
Memoria      ████░░░░░░  24 MB

Úsalos junto con tablas, no en lugar de ellas. Excelente para desgloses de cobertura, comparaciones de rendimiento y porcentajes de finalización de idiomas.

6. CTAs de Navegación For-the-Badge

<p align="center">
  <a href="#-inicio-rápido"><img src="https://img.shields.io/badge/⚡_Inicio_Rápido-2ea44f?style=for-the-badge" /></a>&nbsp;
  <a href="#-características"><img src="https://img.shields.io/badge/✨_Características-6366f1?style=for-the-badge" /></a>&nbsp;
  <a href="#-benchmarks"><img src="https://img.shields.io/badge/📊_Benchmarks-f59e0b?style=for-the-badge" /></a>&nbsp;
</p>

Estos reemplazan una tabla de contenidos tradicional; no uses ambas.

7. Secciones Plegables

Envuelve el contenido secundario en bloques <details>: variantes de instalación, configuración avanzada, documentación completa de API, árboles de estructura de proyectos, solución de problemas. El flujo principal debe ser escaneable en 30 segundos.

8. Tablas de Datos con Indicadores Visuales

| Característica | Este Proyecto | Alt A | Alt B |
|:---|:---:|:---:|:---:|
| Característica X | ✅ | ❌ | ⚠️ |

Estructura del README

Adáptala según el proyecto. No todas las secciones aplican, pero los elementos visuales no son negociables.

 1. BANNER DE ENCABEZADO ANIMADO (capsule-render)

 2. HÉROE CENTRADO
    - Título con emoji
    - Eslogan
    - CTAs de navegación for-the-badge (estos reemplazan un TOC)
    - Badges de metadatos (versión, CI, licencia, plataforma)

 3. PROPUESTA DE VALOR (2-3 frases — por qué esto existe)

 4. CARACTERÍSTICAS (cuadrícula HTML o tarjetas en blockquote — nunca lista con viñetas)

 5. INICIO RÁPIDO (pasos numerados con emoji 1️⃣ 2️⃣ 3️⃣ y salida esperada)

 6. CASOS DE USO DEL MUNDO REAL (escenarios creativos — ver Regla 3)

 7. BENCHMARKS / DATOS (indicadores SVG + barras Unicode + tabla de comparación ✅❌)

 8. ANTES Y DESPUÉS (tabla comparativa convincente — ver Regla 3)

 9. MATRIZ DE COMPARACIÓN (si hay alternativas — ver Regla 3)

10. DIAGRAMA DE ARQUITECTURA (Mermaid sequenceDiagram, classDiagram, etc.)

11. GUÍA DE INSTALACIÓN (sección plegable única con todos los métodos)

12. GUÍA DE USO / API (ejemplos de código, tabla de referencia)

13. DIAGRAMA DE VIAJE DEL USUARIO (Mermaid journey)

14. ÁRBOL DE DECISIÓN DE SOLUCIÓN DE PROBLEMAS (Mermaid flowchart)

15. HOJA DE RUTA (Mermaid timeline o gantt)

16. COLABORADORES / LICENCIA

17. BANNER DE PIE DE PÁGINA ANIMADO (capsule-render)

Validación de Calidad

Antes de finalizar un README, verifica:

Sa74/readme-writer

¿Qué es readme-writer?

Preguntar en tu IA favorita

Vista previa

Documentación