Optimización de Repositorios de GitHub

Transforma cualquier repositorio de GitHub en una página de aterrizaje de alta conversión y optimizada para SEO que impulse estrellas, seguidores y tráfico. Cada repositorio que toques debería verse como un proyecto open source de primer nivel.

Esta habilidad tiene dos modos:

Optimizar — reescribe el README, metadatos y estructura de un repositorio para máxima conversión
Asesorar — proporciona al usuario una estrategia de crecimiento de estrellas utilizando la base de conocimiento a continuación

Objetivos (en orden de prioridad)

Estrellas — la principal métrica de prueba social en GitHub
Seguidores — dirigir tráfico a los perfiles sociales del propietario del repositorio
Descubribilidad — posicionarse en la búsqueda de GitHub, Google y motores de respuesta LLM
Tráfico — convertir visitantes en usuarios/seguidores
Credibilidad profesional — señal de calidad a través de la estructura y el pulido

Paso 0: Configuración del Usuario (Autoactualizable)

Antes de optimizar, necesitas saber quién es el propietario de este repositorio. Este paso se ejecuta una vez; después, la configuración se reutiliza.

Verificar configuración existente

Busca ~/.claude/skills/github-optimization/.config.yml. Si existe, carga los valores y salta al Paso 1. Muestra al usuario lo que está cargado y pregunta si algo ha cambiado.

Si no existe configuración, detecta y pregunta

Detectar automáticamente desde la configuración de git y la API de GitHub:
- gh api user — obtiene el nombre de usuario de GitHub autenticado y la URL del perfil
- gh api repos/<owner>/<repo> — obtiene el propietario del repositorio (puede ser usuario u organización)
- git config user.name — obtiene el nombre para mostrar local de git
Preguntar al usuario por lo que no se pueda detectar:
- Nombre para mostrar — su nombre real o atribución preferida (ej., "Juan Pérez")
- Usuario de X/Twitter — para la insignia de Seguir (ej., "@juanperez"). Si no lo quiere, omitirlo.
- Empresa u organización — para atribución en el pie de página (opcional)
- URL de la empresa — enlace para el nombre de la empresa (opcional)
- URL del sitio web — sitio personal o de la empresa (opcional)
Guardar la configuración en ~/.claude/skills/github-optimization/.config.yml:

# Habilidad de Optimización de GitHub — Configuración de Usuario
# Este archivo se genera automáticamente. Editar en cualquier momento.
author_name: "Juan Pérez"
author_github: "juanperez"
x_handle: "juanperez"          # dejar cadena vacía "" para omitir insignia de Seguir
company_name: "Acme Corp"      # dejar cadena vacía "" para omitir
company_url: "https://acme.com"
website_url: "https://juanperez.dev"

Usar estas variables a lo largo del pipeline:
- {OWNER} — nombre de usuario u organización de GitHub (desde la URL del repositorio, detectado por repositorio)
- {REPO} — nombre del repositorio (detectado por repositorio)
- {AUTHOR_NAME} — desde la configuración
- {AUTHOR_GITHUB} — desde la configuración
- {X_HANDLE} — desde la configuración (puede estar vacío)
- {COMPANY_NAME} — desde la configuración (puede estar vacío)
- {COMPANY_URL} — desde la configuración (puede estar vacío)
- {WEBSITE_URL} — desde la configuración (puede estar vacío)

Si algún campo está vacío, omitir ese elemento por completo de la salida. Sin marcadores de posición vacíos ni insignias rotas.

Actualizar configuración

Si el usuario dice "actualiza mi configuración", "cambia mi usuario de X" o similar, actualiza el archivo .config.yml y confirma el cambio.

El Pipeline de Optimización

0. CONFIG       -> Cargar o crear configuración de usuario (se ejecuta una vez, se autoactualiza)
1. AUDITORÍA   -> Leer README actual, descripción, temas, estructura del repositorio
2. PALABRAS CLAVE -> Identificar términos de búsqueda objetivo para este dominio de repositorio
3. METADATOS   -> Optimizar nombre del repositorio, descripción (Acerca de) y temas
4. README      -> Reescribir como página de aterrizaje siguiendo la plantilla a continuación
5. HUMANIZAR   -> Ejecutar la habilidad humanizar-texto en toda la prosa para eliminar patrones de IA
6. EXTRAS      -> Añadir LICENCIA, CONTRIBUTING.md si faltan
7. PUBLICAR    -> Hacer commit, push, aplicar gh repo edit para descripción/temas

Encadenamiento de Habilidades

Esta habilidad llama a otras habilidades durante la ejecución:

humanizar-texto — Después de redactar el README, invocar la habilidad humanizar-texto en todas las secciones de prosa. Esto elimina patrones de escritura de IA y hace que el texto suene como si lo hubiera escrito una persona real. No negociable — cada README debe pasar por esto.

Paso 1: Auditoría

Leer el estado actual:

Contenido y estructura de README.md
Descripción del repositorio (sección Acerca de)
Temas/etiquetas
Licencia
Estructura de archivos
Insignias existentes

Notar qué falta, qué es débil, qué es bueno.

Paso 2: Investigación de Palabras Clave

Identificar 3-5 palabras clave objetivo que los desarrolladores buscarían para encontrar este proyecto. Considerar:

¿Qué problema resuelve?
¿Qué tecnología utiliza?
¿En qué dominio está?

Estas palabras clave deben aparecer en: nombre del repositorio (si es posible), descripción Acerca de, encabezados H1 y H2 del README y etiquetas de temas.

Paso 3: Optimización de Metadatos

Descripción Acerca de

Idealmente menos de 120 caracteres, máximo 250
Comenzar con lo que hace, no lo que es
Incluir la palabra clave principal de forma natural
Formato: <Verbo de acción> <qué> para <quién/qué>. <Diferenciador clave>.

Etiquetas de Temas

Seleccionar 10-20 etiquetas en tres categorías:

Etiquetas de propósito — qué hace el proyecto
Etiquetas de stack tecnológico — tecnologías utilizadas
Etiquetas de dominio — campo o industria

Aplicar con:

gh repo edit {OWNER}/{REPO} --add-topic etiqueta1 --add-topic etiqueta2 ...

Paso 4: Reescribir el README

El README es una página de aterrizaje, no documentación.

Plantilla de README

Adaptar las insignias según la información de usuario disponible en la configuración:

<div align="center">

# <Nombre del Proyecto>

**<Descripción de una línea — qué hace en lenguaje sencillo>**

<br />

[![Estrella este repositorio](https://img.shields.io/github/stars/{OWNER}/{REPO}?style=for-the-badge&logo=github&label=%E2%AD%90%20Star%20this%20repo&color=yellow)](https://github.com/{OWNER}/{REPO}/stargazers)

Si {X_HANDLE} está configurado, añadir junto a la insignia de estrellas:

&nbsp;&nbsp;
[![Seguir a @{X_HANDLE}](https://img.shields.io/badge/Follow_%40{X_HANDLE}-000000?style=for-the-badge&logo=x&logoColor=white)](https://x.com/{X_HANDLE})

Si {X_HANDLE} está vacío, omitir la insignia de Seguir por completo.

Luego continuar con insignias de credencial:

<br />

[![<Insignia 1>](shields-url)](<enlace>)
&nbsp;
[![<Insignia 2>](shields-url)](<enlace>)

---

<Párrafo de presentación. ¿Qué dolor resuelve? ¿Por qué alguien debería importarle?>

[Instalación](#instalación) | [Cómo Funciona](#cómo-funciona) | [Características](#características) | [Contribuir](#contribuir)

</div>

Reglas de Insignias

Fila 1 (CTAs — grandes, prominentes):

Insignia de estrellas con conteo en vivo — SIEMPRE primero, style=for-the-badge, amarillo
Insignia de Seguir en X — SOLO si {X_HANDLE} está configurado

Fila 2 (Insignias de credencial — mismo tamaño):

Todas las insignias usan style=for-the-badge — nunca mezclar tamaños
Elegir 2-4 relevantes: Licencia, PRs Bienvenidos, lenguaje/framework, estado de compilación

Orden de Secciones

Por Qué Existe / El Problema — 2-3 oraciones sobre el punto de dolor
Antes vs Después (opcional) — tabla de comparación
Instalación / Inicio Rápido — menos de 5 pasos, idealmente un comando
Cómo Funciona — flujo de trabajo visual (diagrama ASCII, tabla o pasos numerados)
Características / Casos de Uso — tabla o lista con viñetas, escaneable
Qué Hay Dentro / Estructura — árbol de archivos si es relevante
Configuración / Opciones (opcional)
Seguridad (opcional)
Contribuir — corto, acogedor
Licencia — una línea
Pie de página con CTAs — insignias de estrellas y seguir repetidas

Plantilla de Pie de Página

Construir dinámicamente desde la configuración:

---

<div align="center">

Línea de atribución — construir a partir de campos de configuración disponibles:

Si autor + empresa + sitio web: Construido por [NOMBRE](GITHUB) en [EMPRESA](EMPRESA_URL) | [SITIO_WEB](SITIO_WEB_URL)
Si autor + empresa (sin sitio web): Construido por [NOMBRE](GITHUB) en [EMPRESA](EMPRESA_URL)
Si autor + sitio web (sin empresa): Construido por [NOMBRE](GITHUB) | [SITIO_WEB](SITIO_WEB_URL)
Si solo autor: Construido por [NOMBRE](GITHUB)
Si nada: Construido con la habilidad de optimización de GitHub

<br />

**Si esto te es útil:**

[![Estrella este repositorio](url-insignia-estrellas)](url-stargazers)

Si {X_HANDLE} existe, añadir también la insignia de Seguir aquí.

</div>

Reglas de Escritura

No negociables. Definen la voz.

HACER:

Escribir como una persona explicándole a un amigo. Oraciones cortas. Voz activa.
Comenzar cada sección con el valor, no el mecanismo
Usar "tú" y "tu" — hablar directamente al lector
Ser específico en lugar de abstracto
Mantener los párrafos en 2-3 oraciones como máximo
Usar tablas para comparaciones

NO HACER:

Usar jerga de IA: "apalancar", "optimizar", "empoderar", "sin fisuras", "robusto", "de vanguardia", "revolucionar", "aprovechar el poder de", "elevar tu flujo de trabajo", "supercargar"
Comenzar oraciones con "Este proyecto..." o "Esta herramienta..."
Escribir muros de texto
Usar voz pasiva
Añadir palabras de relleno: "básicamente", "esencialmente", "simplemente", "solo"
Usar signos de exclamación

SEO en Encabezados:

H1 debe contener la palabra clave principal
H2 deben contener palabras clave secundarias de forma natural
Escribir para humanos primero, pero ser deliberado sobre la colocación

Paso 5: Extras

Añadir si faltan:

LICENCIA — MIT a menos que el usuario especifique lo contrario
CONTRIBUTING.md — corto, acogedor, proceso de 3 pasos

NO añadir a menos que se solicite: CODE_OF_CONDUCT.md, SECURITY.md, .github/ISSUE_TEMPLATE/

Paso 6: Publicar

Hacer commit de todos los cambios con un mensaje descriptivo
Hacer push al remoto
Actualizar metadatos del repositorio mediante gh repo edit
Informar al usuario: qué cambió, la nueva descripción, temas añadidos, URL en vivo

Lista de Verificación Antes de Terminar

Base de Conocimiento de Crecimiento de Estrellas

Cuando los usuarios pregunten "¿cómo consigo más estrellas?", "estrategia de lanzamiento", "promociona mi repositorio" o similar, usa esta base de conocimiento para asesorarlos. Esta sección es material de referencia, no parte del pipeline de optimización.

Ranking de Canales (por ROI)

Rango	Táctica	Esfuerzo	Estrellas Esperadas	Riesgo
1	Lanzamiento apilado (HN + Reddit + X + PH mismo día)	Alto (1 día de preparación)	200-2.000+	Ninguno
2	Envíos a listas Awesome	Bajo (PRs)	Quema lenta, se acumula	Ninguno
3	Optimización de README + vista previa social	Medio (1 hora)	Multiplicador 3x en todos los demás esfuerzos	Ninguno
4	SEO de GitHub (nombre, temas, descripción)	Bajo (30 min)	Descubrimiento pasivo a largo plazo	Ninguno
5	GIF/Video demo en README	Medio	Conversión drásticamente mayor	Ninguno
6	Crear tu propia lista Awesome	Medio	Quema lenta + promoción cruzada	Ninguno
7	Envíos a boletines	Bajo (correos)	50-500 por mención	Ninguno
8	Tutoriales en YouTube	Alto	Mejor impulsor sostenido a largo plazo	Ninguno
9	Listicle recíproco en X	Bajo	Depende de la red	Ninguno
10	Etiquetado de Hacktoberfest (octubre)	Bajo	50-200 estacional	PRs spam
11	Creación de comunidad en Discord	Alto continuo	Retención/defensa	Ninguno
12	Charlas en conferencias	Alto	Bajo directo, alto compuesto	Ninguno

Manual de Hacker News

Mejor momento: Martes-Jueves, 8-10 AM Pacífico. Domingo 6-9 PM Pacífico para menor competencia.

Formato del título: Show HN: [Nombre] — [Qué hace concretamente]

Qué funciona: Escribe como un colega, no como un comercial. Sin palabras de moda. Comienza con el problema. Responde a cada comentario en la primera hora. Publica tu propio comentario sustancial inicial dentro de los primeros 5 minutos.

Umbrales: 8-10 votos genuinos + 2-3 comentarios reflexivos en los primeros 30 minutos para entrar en el top 10.

Requisitos de la cuenta: 250+ karma con historial de comentarios técnicos para mejores resultados. Las cuentas nuevas enfrentan moderación.

La detección de manipulación es agresiva. Nunca tuitees "por favor, vota mi publicación de HN". Usa canales privados (correo, Slack, Discord) para notificar a personas.

Resultados reales:

Lago: #1 durante 48+ horas, impulsor principal a 1.000 estrellas
Encore: 1.500 estrellas en una semana desde un único Show HN
Promedio: 121 estrellas en 24 horas, 289 en una semana

Manual de Reddit

Gana karma 2+ semanas antes de publicar. La regla 90/10 de Reddit: 90% actividad genuina, 10% autopromoción.

Subreddit	Notas
r/SideProject (453K)	Permite explícitamente autopromoción
r/programming (6M+)	Antipromoción estricta, "cómo construimos X" funciona
r/selfhosted (500K+)	Convierte extremadamente bien
r/webdev	Solo "Showoff Saturday"
r/opensource	Amigable con enlaces, volumen bajo
r/coolgithubprojects	Específicamente para repositorios de GitHub

Esperado: 50-300 estrellas por publicación exitosa. Adapta el mensaje por subreddit.

Manual de Product Hunt

Reinicio de votos: 12:01 AM PST diariamente. Los votos se ocultan las primeras 4 horas.

Votos para #1: 600-800 entre semana, 400-600 fin de semana.

Mejores días: Martes-Jueves.

Esperado: 200-1.000 estrellas del top 5 de Producto del Día. #1 puede entregar 500-2.000+.

Cronograma:

4-6 semanas antes: Construir 200-500 suscriptores de correo
1 semana antes: Preparar todos los activos
Día de lanzamiento: Publicar a las 12:01 AM PST, responder a todo, enviar correo masivo a las 6 AM PST

Manual de Twitter/X

Qué funciona: Videos/GIFs demo cortos superan al texto. Los tuits de seguidores generan más estrellas que los autotuits. Días laborables por la mañana hora de EE. UU. (9-11 AM ET).

Esperado: 7% de aumento en estrellas por tuitear. Los tuits de video virales pueden alcanzar 1.600 estrellas en 6 horas.

La Estrategia de Lanzamiento Apilado

La metaestrategia que usó todo repositorio de rápido crecimiento:

Momento	Acción	Estrellas Esperadas
Semana anterior	Enviar a boletines (TLDR, Console.dev, Changelog)	--
Mañana del lanzamiento	Publicar en HN "Show HN" (mar-mié, 8-11am ET)	121 prom., hasta 1.500
Tarde del lanzamiento	Publicar en Reddit (r/programming, r/selfhosted, sub dominio)	50-300
Día del lanzamiento	Tuitear video demo + conseguir que seguidores compartan	50-500+
Día del lanzamiento	Publicar en Produ...

[truncado para traducción]

Preguntar en tu IA favorita

Vista previa

Documentación