Communitygithub.com

brag-more / alardear-más

Transforma el README de GitHub de tu proyecto actual en una portada profesional y atractiva — un héroe SVG animado con los colores y fuentes del proyecto, tarjetas de características diseñadas, el video de alarde o un bucle de demostración en vivo, insignias honestas, un eslogan de una línea, características reales y un inicio rápido que realmente funciona. Se usa cuando alguien dice "/brag-more", "haz que mi README se vea bien", "alardea en el README", "embellece el repo de GitHub", o quiere que la página del repositorio luzca tan bien como el proyecto.

¿Qué es alardear-más?

/brag-more es una habilidad de agente de IA (diseñada para plataformas como Claude Code que soportan el formato SKILL.md) que convierte el README de un repositorio de GitHub en una portada de proyecto pulida y visual, similar a las de proyectos open-source populares como Excalidraw o Supabase. Examina el código del proyecto, manifi estos, configuraciones de CI y archivos existentes (incluyendo marcas, colores y fuentes) para generar automáticamente un README rico en contenido, visual y que se vende por sí solo. Sus características clave incluyen la generación de un héroe SVG animado con CSS @keyframes (utilizando estilos reales del proyecto), bucles de demostración de video o GIF, tarjetas de características en cuadrícula, insignias reales verificadas (basadas en licencias, estados de CI o publicaciones de paquetes) y una sección de inicio rápido que verifica cada comando contra el proyecto. Soporta múltiples estilos de salida (limpio, audaz, minimalista y de exhibición), maneja ambos temas de GitHub (claro y oscuro) y garantiza que todas las afirmaciones sean verdaderas, ejecutables y escaneables. La habilidad también puede crear un video de lanzamiento si falta (usando la habilidad /brag o un flujo de trabajo de video ligero incluido) y actualiza la descripción y los temas del repositorio. El result ado es un README que capta la atención en segundos, guía a los visitantes desde el interés hasta la ejecución en un minuto, y reutiliza todos los textos valiosos del README original mientras embellece su presentación.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/omer-chandna/brag-more/tree/HEAD/skills/brag-more

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Vista previa

Del README del skill

 alardear-más preview

Documentación

/brag-more (alardear-más)

Lo construiste. Ahora haz que el repo también alardee. El README es lo primero que cualquiera ve en GitHub; conviértelo en una portada que venda el proyecto en cinco segundos y lleve a un desconocido de cero a ejecutarlo en un minuto.

Sea cual sea el proyecto, el resultado debe sentirse como un README de un proyecto open-source querido: seguro, escaneable, visual y verdadero. Nada en la página que no merezca su lugar.

Uso: /brag-more [opciones]. Opciones (flags o lenguaje natural):

OpciónPor defecto
`--style limpioaudaz
--previewdesactivado: escribe README.md en su lugar. Con él, escribe solo en brag-output/repo/ y deja README.md intacto
--no-bannerbanner activado
--no-videodesactivado: si el proyecto no tiene video de alarde, crea uno primero (ver El video)
--no-demodemo activada cuando hay algo que mostrar

Los archivos de trabajo van en brag-output/repo/ (brag-output-YYYY-MM-DD-HHmmss/repo/ con marca de tiempo si brag-output/ ya existe y no es de esta ejecución). Los activos a los que el README hace referencia van en el repo, en .github/readme/, para que se envíen con él.

1. Inspeccionar

Lee el proyecto, no solo el README antiguo:

  • El README existente, cada línea. Es el texto del usuario. Mantén todo lo que sea verdadero y útil (pasos de instalación, tablas de configuración, créditos, notas de licencia, enlaces de patrocinadores, agradecimientos); rediseñalo, no lo descartes.
  • Identidad: colores exactos de la marca y fuentes de las hojas de estilo o configuración del tema, el logotipo o favicon, cualquier imagen de héroe o imagen OG existente.
  • Qué es: manifiestos de paquetes (package.json, pyproject.toml, Cargo.toml, go.mod, …) para el nombre, descripción, versión, licencia, binarios y scripts; el punto de entrada y las rutas o comandos principales para las características reales.
  • Cómo ejecutarlo: los comandos reales de instalación e inicio de los scripts del manifiesto, Makefile, justfile, Dockerfile o flujo de trabajo de CI. Anota las versiones de runtime que el proyecto fija.
  • Señales para insignias: LICENSE, .github/workflows/*, si el paquete está publicado (npm, PyPI, crates.io — verifica el nombre del manifiesto y el flag private), el remoto git (git remote get-url origin) para propietario/repo.
  • Salida de alarde existente: si brag-output*/brag.mp4 y brag.jpg existen, son el mejor material de demostración en la máquina. Usa el más reciente. Si no hay uno, lo crearás en el siguiente paso.

Omite la salida de compilación, archivos de bloqueo, .git/, archivos env y secretos (.env, .env.*), material de claves y credenciales, y cualquier cosa que .gitignore excluya por esas razones.

Antes de escribir, responde: ¿Qué es (una frase que un desconocido entienda)? ¿Para quién es? ¿Qué es lo único que hace mejor que la alternativa? ¿Cuál es el gancho visual — la captura de pantalla, GIF o banner que hace que alguien deje de desplazarse? ¿Cuáles son las 3–5 características reales? ¿Cuál es el camino más corto desde clonar hasta ejecutar?

El README es público. Nunca lleves secretos, tokens, nombres de host internos, nombres de clientes o usuarios reales, direcciones de correo electrónico u otros datos personales a él o a sus imágenes. Si una captura de pantalla muestra tales datos, intercambia por sustitutos ficticios plausibles.

El video (antes del plan, cuando aún no hay uno)

La mejor demo del README es el video de lanzamiento del proyecto, por lo que brag-more lo crea cuando falta. Omite este paso cuando --no-demo o --no-video esté configurado, o cuando ya exista un brag-output*/brag.mp4.

  1. Si la habilidad /brag está instalada (verifica la lista de habilidades), ejecútala para este proyecto a través de la herramienta Skill, pasando cualquier deseo de --tone o formato. Informa al usuario en una línea: "Todavía no hay video de lanzamiento, así que primero lo creo con /brag".
  2. De lo contrario, lee <skill-dir>/video.md (el flujo de trabajo de video ligero incluido aquí, de brag-slim) y síguelo. Solo necesita herramientas ya en la máquina.
  3. Cuando termine, el video, el póster y la copia para compartir están en brag-output/. Continúa con el README usándolos como la demo.

Si crear el video falla o el usuario no quiere esperar, continúa sin él y usa las alternativas bajo Demo.

2. Planificar

Escribe brag-output/repo/readme-plan.md: el eslogan de una línea, el estilo elegido, el orden de las secciones, qué imágenes crearás y qué muestra cada una, qué insignias están justificadas (y la evidencia para cada una), y qué estás conservando del README antiguo.

Forma: una forma inicial, no una plantilla. Elimina cualquier sección que estaría vacía o sería relleno.

  1. Héroe — el héroe SVG animado (ver Construir), luego centrado: el eslogan de una línea, una fila corta de insignias y una línea de navegación de enlaces (Demo · Instalar · Docs · …).
  2. Demo — el producto en uso, justo debajo del héroe, enmarcado: el bucle del video de alarde, un GIF de la interfaz de usuario real o una grabación de terminal. Un visual, grande.
  3. Por qué — 2–4 oraciones: qué hace por el usuario y qué lo diferencia, con las propias palabras del proyecto. Para una herramienta de desarrollador, un bloque de código de 3–5 líneas que sea el argumento de venta supera un párrafo (bun run index.tsx # TS y JSX listos para usar).
  4. Escaparate de características — 3–6 características reales, cada una con su propio visual pequeño: una captura de pantalla recortada de la interfaz de usuario real, un GIF de terminal por comando o un fragmento de código y su salida. Coloca las visuales como tarjetas una al lado de la otra (ver Construir). Las características solo de texto obtienen una introducción en negrita y una línea.
  5. Inicio rápido — copiable y pegable, en orden, cada comando verificado contra el proyecto. Requisitos previos primero.
  6. Uso — uno o dos ejemplos reales: un comando y su salida, un fragmento de código o un bloque de configuración.
  7. Cómo funciona — opcional. Un párrafo corto o un diagrama Mermaid cuando la arquitectura es la parte interesante.
  8. Todo lo demás del README antiguo — configuración, preguntas frecuentes, hoja de ruta, contribuciones, créditos — ordenado, plegado en <details> cuando sea largo.
  9. Pie de página — línea de licencia, más la tira de arte de cierre (ver Construir).

Leyes del README

  • Verdadero. Cada afirmación, número, característica e insignia debe estar respaldado por el proyecto. Sin estrellas, descargas, puntos de referencia, testimonios o logotipos "usado por" inventados. Una insignia aparece solo si existe aquello a lo que apunta (un paquete publicado, un flujo de trabajo real, un archivo de licencia).
  • Ejecutable. Cada comando en Inicio rápido y Uso existe en el proyecto tal como está escrito. Si puedes ejecutarlo de forma segura (instalar, compilar, --help, pruebas), hazlo. Si un paso necesita secretos o un servicio de pago, dilo claramente en lugar de ocultarlo.
  • Prueba de cinco segundos. Alguien que llegue al repo desde un tweet sabe qué es, lo ve funcionando y encuentra el comando de instalación sin desplazarse más allá de la primera pantalla.
  • Muestra la cosa. La demo muestra el producto real en uso, no una animación de logotipo o arte abstracto. Reutiliza la interfaz de usuario real, CSS real, texto real.
  • Di qué es el repo. Si el repo es el sitio web, la página de aterrizaje o la demo de un producto, dilo en el eslogan de una línea; no impliques que la gente puede descargar una aplicación o instalar un paquete que el repo no entrega.
  • Específico. Debe sentirse escrito para este proyecto exacto. "Rápidísimo", "sin fisuras", "de última generación", "optimiza tu flujo de trabajo" están prohibidos a menos que el proyecto los gane de forma medible.
  • Escaneable. Párrafos cortos, encabezados que digan algo, una idea por viñeta. Emoji en encabezados solo si la propia voz del proyecto los usa, y entonces con moderación (el estilo exhibición es la excepción: un emoji por encabezado de sección, por diseño).
  • Ambos temas. Los lectores de GitHub usan modo claro y oscuro. Cada imagen se ve bien en #ffffff y en #0d1117: PNG transparentes con un borde visible, o <picture> con una fuente prefers-color-scheme por tema.
  • Encaja en la columna. La columna del README tiene aproximadamente 830px de ancho en escritorio y mucho más estrecha en teléfonos. El texto del banner sigue siendo legible cuando se escala al ancho del teléfono; las tablas tienen pocas columnas; sin diseños HTML sin procesar que se rompan en móvil.
  • Cada enlace resuelve. Los enlaces relativos apuntan a archivos que existen; los anclajes coinciden con encabezados reales.

Estilos

EstiloSensaciónCuándo usarlo
limpioHéroe animado con movimiento moderado, demo enmarcada, tarjetas ordenadasLa mayoría de los proyectos; el predeterminado
audazHéroe a sangre completa en colores de la marca con un momento animado más grande, eslogan impactante, demo al frente y al centroAplicaciones de consumo, proyectos lúdicos, lanzamientos
minimalPequeño logo animado + nombre + eslogan de una línea, secciones simplesBibliotecas, CLI, infraestructura, herramientas serias
exhibiciónEl README técnico denso con secciones de emoji (piensa en un hackathon ganador o proyecto de investigación): una captura de pantalla real del producto en la parte superior, una línea de premio o estado, luego una sección por tema liderada por emojiHackathon, investigación, ML, datos o proyectos de ciencia; cualquier cosa con profundidad real para mostrar. Elígelo cuando el usuario pida "algo como Find My Shark" o un README detallado estilo documentación

La receta exhibición

Modelado en el README de Find-My-Shark del propietario. Mantén lo que lo hace funcionar y arregla lo que no:

  • Título con un emoji y la línea de logro debajo ("NASA Space Apps 2025, Ganador de Impacto Galáctico"), solo si el proyecto realmente lo ganó. Pregunta o léelo del README antiguo; nunca inventes uno.
  • Una captura de pantalla real o el GIF de demostración justo debajo del título, enmarcado (ver Demo, enmarcado). Mantén el héroe animado solo si añade algo; aquí el producto real es la estrella.
  • Un argumento de 2-3 líneas y la línea de "por qué importa", luego secciones cada una liderada por un emoji: Características, Región/Alcance o Entradas, Fuentes de datos (tabla), Cómo funciona o Modelo matemático, Inicio rápido (instalación, uso básico, uso de API), Estructura del proyecto (árbol anotado), Configuración (la configuración real), Archivos de salida, Opciones de línea de comandos, Antecedentes, Extensiones futuras, Pruebas, Registro, eslogan de cierre.
  • Incluye solo secciones para las que el proyecto tenga contenido real. La profundidad de nivel hackathon es el punto, así que mantén los detalles: parámetros, fórmulas, umbrales, nombres de conjuntos de datos y el árbol del proyecto.
  • Arregla los deslices habituales: usa la URL de clonación real (nunca tu-nombre-de-usuario), reemplaza las entradas obsoletas del bloque de código del árbol del proyecto con lo que existe, añade una tabla de contenido o fila de enlaces rápidos una vez que haya más de seis secciones, envuelve secciones largas de referencia (opciones de CLI, configuración completa, antecedentes científicos) en <details>, añade insignias para la pila real (versión de Python, licencia, bibliotecas clave) y una <picture> o captura de pantalla enmarcada para ambos temas, y establece la descripción del repo y los temas en la entrega.
  • Anclajes con emoji: GitHub elimina el emoji del slug de un encabezado pero mantiene el guión, así que ## 🚀 Inicio rápido es #-inicio-rápido, no #inicio-rápido. Escribe cada enlace de navegación y enlace de insignia de esa manera y verifica cada uno contra su encabezado. El resumen de <details> no es un encabezado y no tiene anclaje.
  • Aún sigue cada ley del README (Verdadero, Ejecutable, Ambos temas) y el paso de Verificar.

3. Construir

Los mejores README en GitHub (Excalidraw, Scalar, Supabase, Charm, Rich, Bun) comparten algunos movimientos. Úsalos todos; eso es lo que hace que este detenga un desplazamiento.

El héroe: un SVG animado

Esta es la firma. Un banner estático se lee como una plantilla; un héroe que se mueve — en los propios colores, fuentes e interfaz de usuario del proyecto — se lee como hecho para este proyecto. GitHub renderiza un SVG en una etiqueta <img> con su CSS @keyframes en ejecución, por lo que el héroe puede animarse sin la bandificación o el peso de un GIF.

Construye .github/readme/hero.svg (viewBox alrededor de 1600×800, renderizado a width="100%"):

  • La escena es el producto. Recrea el héroe real del proyecto o la pantalla clave como formas SVG: su imagen de fondo, su titular en su propia fuente y un elemento de interfaz de usuario real haciendo su trabajo (una tarjeta deslizándose, un comando escribiéndose, un gráfico dibujándose, un toast aterrizando). Una idea, un bucle.
  • Movimiento: CSS @keyframes en un bloque <style> dentro del SVG, solo en transform y opacity, con transform-box: fill-box; transform-origin: center en cualquier cosa que escale o rote. Un bucle de 6–10 s que vuelve a su fotograma inicial sin problemas, entradas escalonadas, cada línea de texto asentada el tiempo suficiente para leerla. Añade una deriva lenta en el fondo (una escala de 1.0 → 1.05 a lo largo del bucle) para que el fotograma nunca se sienta congelado. Un transform de CSS reemplaza el atributo transform SVG de un elemento, así que posiciona las cosas con un <g transform=…> externo y anima un elemento interno.
  • Movimiento reducido: envuelve los keyframes en @media (prefers-reduced-motion: no-preference) para que los lectores que optan por salir vean el fotograma terminado y asentado. El fotograma asentado debe ser publicable por sí mismo y mostrar el producto, por lo que cualquier cosa que solo aparezca a medio bucle (una superposición de coincidencia, un toast) comienza oculta con un atributo opacity="0" y se revela solo por sus keyframes.
  • Autónomo. Un SVG cargado a través de <img> no puede buscar nada: sin fuentes web por URL, sin imágenes externas, sin scripts. Incrusta fuentes como @font-face base64 (los archivos latin de Google Fonts ya tienen ~20 KB y se pueden incrustar enteros; subconjunta otras fuentes con pyftsubset … --text="…" --flavor=woff2, que necesita una fontTools reciente), o convierte el texto a trazados. Incrusta fotos como JPEG base64, redimensionadas a lo que el héroe necesita. Evita <foreignObject> (Safari no lo renderizará dentro de <img>). Mantén el archivo por debajo de ~1.5 MB.
  • Ambos temas. Si el héroe es a sangre y opaco funciona en ambos; de lo contrario, haz hero-dark.svg también e intercambia con <picture> o fragmentos de URL #gh-dark-mode-only / #gh-light-mode-only.
  • Texto: el nombre del proyecto y el eslogan de una línea, grandes (el héroe se reduce a ~40% en teléfonos). Nada más.
<p align="center">
  <a href="<enlace del sitio o demo>"><img src=".github/readme/hero.svg" alt="<Proyecto> — <eslogan de una línea>" width="100%"></a>
</p>

También captura el fotograma asentado a 1280×640 para .github/readme/social-preview.png (opaco) para la tarjeta social del repo; renderiza el SVG en un navegador sin cabeza con movimiento reducido activado.

Si el proyecto no tiene una identidad visual que valga la pena animar (una biblioteca sin interfaz de usuario), haz una marca denominativa animada en su lugar: el nombre en una fuente adecuada, un movimiento que diga lo que hace (un valor fluyendo a través de una tubería, texto siendo formateado, una prueba volviéndose verde).

Demo, enmarcada

En orden de preferencia:

  1. El video de alarde. El encontrado en Inspeccionar o creado en el paso El video. Si existe un brag.mp4, haz un GIF de vista previa en bucle o WebP animado de sus 4–8 segundos más fuertes

Skills relacionados