README Screenshots
Convierte un proyecto funcional en uno documentado y visual: ejecuta la aplicación, captura
capturas de pantalla reales de sus superficies y compone un README.md vibrante y limpio a su
alrededor. El resultado debe leerse como la página de inicio de un proyecto de código abierto
bien cuidado.
No negociables, sea cual sea la plataforma:
- Las capturas de pantalla son REALES de la aplicación en ejecución. Nunca dibujes, simules ni falsifiques una imagen.
- Se almacenan en el repositorio (
docs/screenshots/) y el README las referencia con rutas relativas para que se rendericen en GitHub. - Nada destructivo: nunca modifiques el código fuente del proyecto para hacer una captura: inyecta estado de demostración en tiempo de ejecución si es necesario, y luego indícalo.
Flujo de trabajo
Fase 1 — Detectar la plataforma
Busca estas señales en la raíz del proyecto, luego carga UN manual de instrucciones de
references/:
| Señales | → Manual |
|---|---|
package.json con un script dev/start, o index.html, o un frontend web puro en una carpeta src/public | references/web.md |
manifest.json (WebExtension/MV3/V2) | references/web.md (sección de extensión) |
Android: build.gradle(.kts), AndroidManifest.xml, settings.gradle, fuentes de app Kotlin/Java | references/android.md |
iOS: *.xcodeproj, *.xcworkspace, Info.plist, código de app en Swift | references/ios.md |
Flutter: pubspec.yaml con flutter: y lib/main.dart | references/flutter.md |
| Múltiples plataformas (ej. Flutter + nativo, o un monorepo) | documenta primero la plataforma de la interfaz principal; menciona las otras en el README |
Si la plataforma es genuinamente ambigua, pregunta al usuario una vez con tu mejor interpretación del repositorio. Si el proyecto NO tiene interfaz visible para el usuario (biblioteca/CLI pura), no falsifiques capturas de interfaz — recurre a una demostración en terminal, un diagrama refinado o un banner generado, y aun así produce un gran README.
Fase 2 — Ejecutar la aplicación según el manual
Cada manual de instrucciones te dice:
- Lo que ya debe existir en esta máquina (verificación del conjunto de herramientas, comando repetible de una línea).
- Cómo iniciar la aplicación para que su interfaz se renderice.
- Cómo capturar realmente los píxeles (script incluido en
scripts/o un comando de captura nativo). - Cómo recuperarse cuando algo está en blanco ("esperar a que se renderice" es mejor que "reintentar a ciegas").
Fase 3 — Capturar
Convenciones aplicables en cada plataforma:
- Guarda en
<repositorio>/docs/screenshots/, nombres en kebab-case que describan el momento (hero-dashboard.png,settings-screen.png), nunca la herramienta (screenshot-2026-01-04-14-22.png). - Captura cada superficie en su forma natural: diálogos/ventanas emergentes en su tamaño nativo, páginas a 1280×800 o página completa. En teléfonos, captura la pantalla del dispositivo tal cual (su propia resolución es parte de la historia).
- Prefiere el modo oscuro para la captura principal si la aplicación lo tiene — las interfaces oscuras destacan en los README — pero solo si tiene un tema oscuro real; no fuerces uno.
- Se permite estado de demostración preparado (contadores vacíos, marcadores de "Cargando…" se ven mal en tomas promocionales), pero debe inyectarse en tiempo de ejecución, no escribirse en el código del proyecto, y debes informarlo al usuario en tu resumen.
- Un cuadro en blanco o parpadeante es un error de sincronización, no culpa de la aplicación: espera a que cargue + un momento para fuentes/iconos/transiciones, reintenta una vez con una espera más larga.
Fase 4 — Componer el README
Escribe (o reescribe) README.md en la raíz del repositorio. Si ya existe contenido rico
en el README (git-readme.md, un archivo en prosa, docs), extrae TODOS sus datos — estás
mejorando la presentación, nunca eliminando información.
Estructura objetivo (adáptala libremente, mantenla escaneable):
# <Nombre del Proyecto>
<p align="center"><img src="docs/screenshots/hero.png" width="…"></p>
> Frase de presentación de una línea con personalidad.
insignias: licencia, lenguaje, enlace de instalación
## Por qué existe ← el problema, 2–4 líneas, números en negrita si son reales
## Qué hace ← ✨ lista de características ajustada (+ capturas junto a sus características)
## Recorrido de capturas ← galería con leyendas de una línea
## Cómo funciona ← arquitectura en palabras sencillas; tablas mejor que prosa
## Instalación ← numerada, copiable
## Configuración ← tabla de parámetros si la aplicación tiene ajustes
## Privacidad / Seguridad ← solo cuando sea relevante
## Licencia
Reglas de estilo:
- Captura principal arriba del pliegue, ancho explícito (
width="400"para capturas de teléfono, por debajo de ~728px para escritorio) para que se vea bien en GitHub. - Una idea por sección; párrafos cortos; negrita solo para ayudas de escaneo.
- Tablas para matrices de compatibilidad y ajustes — son mejores que la prosa.
- Emojis mínimos y de buen gusto en los encabezados (⏱ 🎨 🚀) está bien; no salpiques cada línea.
- Rutas de imagen relativas con texto alternativo, siempre.
- Nunca narres el proceso de captura de pantallas en el README; se lee como si el proyecto mismo lo hubiera escrito.
Fase 5 — Verificar
- Cada ruta de imagen en el README se resuelve a un archivo existente.
- Ninguna captura de pantalla supera ~1.5 MB; comprime (PNG → WebP o reduce la resolución) si es más grande.
- Informa al usuario: dónde está el README, qué capturas existen, cuáles llevan valores inyectados de demostración, y ofrece cambiar la elección de la captura principal, el tema o el orden.
Política del conjunto de herramientas (manejo de dependencias faltantes)
El skill utiliza el conjunto de herramientas que ya existe en la máquina y NUNCA instala silenciosamente SDKs de plataforma (Android SDK, Xcode, emuladores de Android — descargas de varios GB a las que el usuario debe dar su consentimiento). Si la verificación del conjunto de herramientas de un manual falla, detente limpiamente con exactamente esta forma:
Las capturas de pantalla de [Plataforma] necesitan [herramienta], que no está instalada. Para habilitarla:
<comando o paso de instalación exacto>. Instálala, luego di "reintentar" y continuaré — el trabajo realizado hasta ahora (detección, esqueleto del README) está guardado.
iOS es un caso especial: si el host no es macOS, indícalo en una oración y omítelo — ningún reintento puede habilitarlo en Windows/Linux. Ofrece al usuario la opción de proporcionar capturas de pantalla que haya tomado él mismo.