karix-ai/readme-que-vende

README que vende

Un README no es documentación. Es una página de aterrizaje que casualmente vive en un repositorio git. Un visitante decide en unos 15 segundos si dar estrella, probar o irse. Todo lo que está sobre el pliegue debe ganarse la estrella. La documentación va debajo del pliegue o dentro de docs/.

La prueba de los 15 segundos

Antes de escribir nada, responde estas preguntas en una línea cada una. Si no puedes, el README tampoco podrá.

1. ¿Qué es? Una oración, sin adjetivos. "Un navegador sin interfaz gráfica para agentes de IA, escrito en Zig."
2. ¿Por qué existe? El dolor que elimina, en palabras del usuario. "Chrome consume 500 MB por pestaña; los agentes necesitan 50 pestañas."
3. Prueba de que funciona. Un GIF de demostración, un número de benchmark, o un antes/después. No una lista de características.
4. ¿Cómo lo pruebo en un comando? npx ..., pip install ..., curl ... | sh, docker run ....

Estructura (en este orden, sin excepciones)

# nombre-del-proyecto
Frase de presentación en una línea. (qué + para quién + el gancho)

[GIF de demostración o captura de pantalla — menos de 10 segundos, muestra el resultado, no la configuración]

## Instalar           ← un comando, copiable y pegable, sin requisitos previos ocultos
## Por qué            ← 3–5 líneas: el dolor, las alternativas existentes, por qué esto es diferente
## Uso                ← el caso más común, como ejemplo ejecutable
## Características    ← opcional, corto, lista con viñetas, sin adjetivos de marketing
## Cómo funciona      ← opcional, un párrafo o un diagrama
## Comparación        ← opcional tabla vs 2–3 alternativas, honesto sobre los compromises
## Cómo contribuir / Licencia

Reglas

• Línea de presentación: ≤ 15 palabras. Nombra la categoría y el diferenciador. Evita "súper rápido", "potente", "simple pero". Si tiene un número, usa el número: "Reduce el uso de tokens de Claude Code en un 40%."
• Demo primero, palabras después. El GIF o captura de pantalla va justo debajo de la presentación. Si aún no hay demo, haz una antes de lanzar (consulta la skill demo-gif). Un README sin demo convierte una fracción de lo que convierte uno con demo.
• Instalar es un bloque, un comando. Si necesita una clave API o un archivo de configuración, muéstralo también, en el mismo bloque. Los requisitos previos ocultos son la razón #1 por la que la gente se va después de clonar.
• "Por qué" está escrito para alguien que ya tiene una solución. Nombra las alternativas. Di lo que hacen bien. Luego di la única cosa que esto hace que ellas no hacen. Los lectores confían en READMEs que son justos con la competencia.
• Sin emojis en los encabezados a menos que el proyecto sea deliberadamente lúdico. Sin insignias sobre la presentación (un muro de insignias es lo primero que los visitantes pasan por alto). Dos o tres insignias bajo la presentación está bien: estado de compilación, versión, licencia.
• Un ejemplo real vale más que diez viñetas de características. Muestra entrada → salida. Haz que sea algo que el lector realmente ejecutaría.
• Di lo que no es. Una línea de alcance honesto ("No reemplaza a Playwright; aún no renderiza JS") se anticipa al primer comentario hostil en Hacker News.
• Enlaza la prueba social que tengas. "Usado por X", un benchmark, un hilo de Show HN. No inventes nada.
• Mantén las primeras 60 líneas libres de cualquier cosa que un visitante por primera vez no necesite. Arquitectura, hoja de ruta, FAQ, registro de cambios: todo debajo o en otro lugar.

Anti-patrones que matan la conversión

• Comenzar con un párrafo de antecedentes o historia.
• Una tabla de contenidos como lo primero en la página.
• "Características" antes de "Instalar".
• Instrucciones de instalación que comienzan con "Primero, clona el repositorio" para una herramienta destinada a ser usada, no desarrollada.
• Capturas de pantalla de archivos de configuración en lugar de resultados.
• Voz de marketing ("revolucionario", "de última generación", "sin esfuerzo").
• Marcadores de posición muertos ("TODO: añadir demo").

Procedimiento

1. Lee el README actual (si lo hay) y los puntos de entrada del código. Extrae las cuatro respuestas de la prueba de los 15 segundos.
2. Redacta la línea de presentación. Escribe tres variantes; elige la que tenga el sustantivo más concreto y la menor cantidad de adjetivos.
3. Escribe Instalar, luego Uso, luego Por qué. Ejecuta cada comando en Instalar para confirmar que funciona desde un directorio limpio.
4. Inserta la demo debajo de la presentación. Si no existe, añade un marcador TODO(demo) y dile al usuario que bloquea el lanzamiento.
5. Corta todo lo que esté sobre el pliegue y que no responda a la pregunta "¿Necesita esto un desconocido para decidir?"
6. Lee las primeras 60 líneas como un ingeniero escéptico. Arregla lo primero que haría que cerraran la pestaña.

Salida

Devuelve el README.md completo. Luego enumera, en ≤ 5 viñetas, lo que cambiaste y lo que el usuario aún debe proporcionar (GIF de demo, números de benchmark, citas de usuarios reales).